APPROVED FOR PUBLIC RELEASE: PR2024-1237
<h1 align="center" > FLOCK - Feature Learning of Organized Collective Kinetics </h1>
Welcome to the FLOCK-GPS repository
The purpose of this package is to serve as a processing and feature extraction toolkit for assessing group movement dynamics from GPS location data.
## Quick start
### Installation
`pip install FLOCK-GPS`
FLOCK-GPS for Python >= 3.8 and all its dependancies are available from PyPi
### Tutorials
To run the [tutorials](https://github.com/Tufts-University/FLOCK/blob/main/Tutorials), download the repository to your local storage and open the notebooks from there.
The [Tutorials](https://github.com/Tufts-University/FLOCK/blob/main/Tutorials) folder contains a walkthrough for each preprocessing and feature extraction step, while the [ExtractAllFeatures](https://github.com/Tufts-University/FLOCK/blob/main/ExtractAllFeatures.py) script shows how to combine and run all processing and extraction.
To run the predictive modeling analysis, fist instantiate your R home in the [Predictive-Modeling](https://github.com/Tufts-University/FLOCK/blob/main/PredictiveModeling/Predictive-Modeling.ipynb) notebook.
### Documentation
Documentation can be found in the [Docs](https://github.com/Tufts-University/FLOCK/blob/main/Docs) folder of this repository. The HTML files will open in your default browser from the downloaded repository.
## FLOCK functions
* **DataLoading.py**
* Functions for loading and re-formatting data from a directory of .csv files
* See the SampleData folder for input data format examples
* GPX data from different devices can be formatted uniquely, data is assumed to be in teh format of the example .csv files in the [SampleData](https://github.com/Tufts-University/FLOCK/blob/main/SampleData) folder
* **Preprocessing.py** [](https://nbviewer.org/github/Tufts-University/FLOCK/blob/main/Tutorials/Break-Detection.ipynb)
* Preprocessing functions such as outlier sample detection, interpolation of missing datapoints, path smothing and break detection for identifying movement periods
* **VelocityFeats.py** [](https://nbviewer.org/github/Tufts-University/FLOCK/blob/main/Tutorials/Velocity-Metrics.ipynb)
* Feature extraction functions for finding the velocity of each individual over time and features related to difference in velocities across group members
* **SpatialFeats.py** [](https://nbviewer.org/github/Tufts-University/FLOCK/blob/main/Tutorials/Spatial-Metrics.ipynb)
* Feature extraction functions for spatio-temporal features (spatial features over time). Such as the stretch index, convex hull surface area and voronoi spaces
<p align="center">
<img src="https://github.com/Tufts-University/FLOCK/blob/main/Figures/SpatialFeatureFig.png" alt="Spatial feature figure" width="400" title="Spatial features" /> <br>
<em>Spatial features such as distance to centroid (stretch index), convex hull surface area, and voronoi spaces</em>
</p>
* **PACS.py** [](https://github.com/Tufts-University/FLOCK/blob/main/Tutorials/PACS-Metrics.ipynb)
* Path-adapted coordinate system transformation
<p align="center">
<img src="https://github.com/Tufts-University/FLOCK/blob/main/Figures/PACSfig.png" alt="PACS figure" width="600" title="PACS transformation" /> <br>
<em>Path-adapted coordinate system example. The leftmost figure shows the raw path and one timepoint while the next figures show the straightened PACS path and coordinates of group members over a time-window in the PACS space.</em>
</p>
* **PacsFeats.py** [](https://github.com/Tufts-University/FLOCK/blob/main/Tutorials/PACS-Metrics.ipynb)
* Feature extraction for path adapted coordinate system tranaformed data. Such as the spatial exploration index of each individual, the nearest neighbor (left/right and front/back), the length/width ratio of the group and the consistency of member positions in different movement periods
* **DirectionalCorrelation.py** [](https://nbviewer.org/github/Tufts-University/FLOCK/blob/main/Tutorials/Leadership-Metrics.ipynb)
* Directional correlation time delay leadership metrics from [Nagy et. al.](https://www.nature.com/articles/nature08891) including the directional correlation time delay for each individual, Highly correlated segments (HCS) for each pair and directed graph representation of the directional correaltion time dealy leadership heirarchy for each movement period
<p align="center">
<img src="https://github.com/Tufts-University/FLOCK/blob/main/Figures/DirCorrFig.png" alt="Directional correlation time delay figure" width="300" title="Directional correlation leadership heirarchy" /> <br>
<em>Leadership heirarchy from the directional correlation time delay analysis</em>
</p>
* **ClusteringFeats.py** [](https://nbviewer.org/github/Tufts-University/FLOCK/blob/main/Tutorials/Clustering-Metrics.ipynb)
* Features from clustering analysis using a density-based clustering method (DBSCAN) and/or a heirarchical density-based clustering method (HDBSCAN)
<p align="center">
<img src= 'https://github.com/Tufts-University/FLOCK/blob/main/Figures/GIF_Squad_1_0.gif' alt="Clustering gif" width="300" title="Clustering gif" /> <br>
<em>HDBSCAN clustering in action, tick lines are 5m apart<br>Outliers are labelled cluster -1<br>Plotly express doesn't allow for categorical legends in scatter animations</em>
</p>
* **Regularity.py** [](https://nbviewer.org/github/Tufts-University/FLOCK/blob/main/Tutorials/Regularity-Metrics.ipynb)
* Movement regularity feature extraction including PACS coordinate entropy for each individual at each movement period, Vector autoregression with and without exogenous varaibles for predicability of each individual's movement over time, and entropy measures for all features that are calculated over time
## Predictive modelling [](https://github.com/Tufts-University/FLOCK/blob/main/PredictiveModeling/Predictive-Modeling.ipynb)
Case study: During a 72 hour field study, 16 groups of soldiers complete a 'loaded ruck march' before engaging in strategic and tactical exercises the next day. During these exercises, experts score each of the groups. Our goal is to predict the expert's score of each group from features calculated with this toolbox during the loaded ruck march. To select features, we employ the [Terminating Random Experiments (TRex)](https://github.com/jasinmachkour/TRexSelector) method. We then train a linear regression model using only the selected features.
* **Explanatory model**
* Here we use all of our datapoints (16 groups) to select important features and we report the model's performance on the training data. This exploratory model achieves an R squared score of 0.82.
<p align="center">
<img src="https://github.com/Tufts-University/FLOCK/blob/main/Figures/ExplanatoryModelResults.png" alt="Explanatory Model Results" width="300" title="Explanatory Model Results" /> <br>
<em>Explanatory Model Results</em>
</p>
* **Predictive model**
* Here we employ a Leave-One-Out cross validation method, where we select features and train a new model for each iteration, then test the model on the left out datapoint. This predictive model achieves an R squared score of 0.63.
<p align="center">
<img src="https://github.com/Tufts-University/FLOCK/blob/main/Figures/PredictiveModelResults.png" alt="Predictive Model Results" width="300" title="Predictive Model Results" /> <br>
<em>Predictive Model Results</em>
</p>
**Why the T-Rex selector?** <br>
Compared with a basic Least Absolute Shrinkage and Selection Operator (LASSO) feature selection method, the TRex achieves a much higher stability (i.e. the selcted features in each Leave-One-Out iteration are more similar). The LASSO struggles with wide datasets (small number of observations and large number of features), especially when there is a low sparsity (a high amount of relevant features) such as with our sample study dataset.
## Citation information
Please cite [[0]](#publications) when using FLOCK-GPS in your research and reference the appropriate release version.
## Publications
### About FLOCK-GPS
[0] COMING SOON
APPROVED FOR PUBLIC RELEASE: PR2024-1237
Raw data
{
"_id": null,
"home_page": null,
"name": "FLOCK-GPS",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "GPS, Group Dynamics, Group Movement, Human Performance Prediction, Machine Learning",
"author": null,
"author_email": "James McIntyre <james_mcintyre@uri.edu>",
"download_url": "https://files.pythonhosted.org/packages/b8/73/3fe3362df1dd2bb11c7d6cb4d1f9719e9f8e59d2195e18bc2729be769437/flock_gps-0.0.2.tar.gz",
"platform": null,
"description": "APPROVED FOR PUBLIC RELEASE: PR2024-1237\n\n\n<h1 align=\"center\" > FLOCK - Feature Learning of Organized Collective Kinetics </h1>\n\nWelcome to the FLOCK-GPS repository\n\nThe purpose of this package is to serve as a processing and feature extraction toolkit for assessing group movement dynamics from GPS location data.\n\n\n## Quick start\n\n### Installation\n\n`pip install FLOCK-GPS` \n\nFLOCK-GPS for Python >= 3.8 and all its dependancies are available from PyPi\n\n### Tutorials\n\nTo run the [tutorials](https://github.com/Tufts-University/FLOCK/blob/main/Tutorials), download the repository to your local storage and open the notebooks from there.\n\nThe [Tutorials](https://github.com/Tufts-University/FLOCK/blob/main/Tutorials) folder contains a walkthrough for each preprocessing and feature extraction step, while the [ExtractAllFeatures](https://github.com/Tufts-University/FLOCK/blob/main/ExtractAllFeatures.py) script shows how to combine and run all processing and extraction. \nTo run the predictive modeling analysis, fist instantiate your R home in the [Predictive-Modeling](https://github.com/Tufts-University/FLOCK/blob/main/PredictiveModeling/Predictive-Modeling.ipynb) notebook.\n\n\n### Documentation\nDocumentation can be found in the [Docs](https://github.com/Tufts-University/FLOCK/blob/main/Docs) folder of this repository. The HTML files will open in your default browser from the downloaded repository.\n\n\n## FLOCK functions\n\n* **DataLoading.py** \n * Functions for loading and re-formatting data from a directory of .csv files\n * See the SampleData folder for input data format examples\n * GPX data from different devices can be formatted uniquely, data is assumed to be in teh format of the example .csv files in the [SampleData](https://github.com/Tufts-University/FLOCK/blob/main/SampleData) folder \n \n* **Preprocessing.py** [](https://nbviewer.org/github/Tufts-University/FLOCK/blob/main/Tutorials/Break-Detection.ipynb)\n * Preprocessing functions such as outlier sample detection, interpolation of missing datapoints, path smothing and break detection for identifying movement periods\n \n* **VelocityFeats.py** [](https://nbviewer.org/github/Tufts-University/FLOCK/blob/main/Tutorials/Velocity-Metrics.ipynb)\n * Feature extraction functions for finding the velocity of each individual over time and features related to difference in velocities across group members\n \n* **SpatialFeats.py** [](https://nbviewer.org/github/Tufts-University/FLOCK/blob/main/Tutorials/Spatial-Metrics.ipynb)\n * Feature extraction functions for spatio-temporal features (spatial features over time). Such as the stretch index, convex hull surface area and voronoi spaces\n<p align=\"center\"> \n <img src=\"https://github.com/Tufts-University/FLOCK/blob/main/Figures/SpatialFeatureFig.png\" alt=\"Spatial feature figure\" width=\"400\" title=\"Spatial features\" /> <br>\n <em>Spatial features such as distance to centroid (stretch index), convex hull surface area, and voronoi spaces</em>\n</p>\n\n* **PACS.py** [](https://github.com/Tufts-University/FLOCK/blob/main/Tutorials/PACS-Metrics.ipynb)\n * Path-adapted coordinate system transformation\n<p align=\"center\"> \n <img src=\"https://github.com/Tufts-University/FLOCK/blob/main/Figures/PACSfig.png\" alt=\"PACS figure\" width=\"600\" title=\"PACS transformation\" /> <br>\n <em>Path-adapted coordinate system example. The leftmost figure shows the raw path and one timepoint while the next figures show the straightened PACS path and coordinates of group members over a time-window in the PACS space.</em>\n</p>\n\n* **PacsFeats.py** [](https://github.com/Tufts-University/FLOCK/blob/main/Tutorials/PACS-Metrics.ipynb)\n * Feature extraction for path adapted coordinate system tranaformed data. Such as the spatial exploration index of each individual, the nearest neighbor (left/right and front/back), the length/width ratio of the group and the consistency of member positions in different movement periods\n \n* **DirectionalCorrelation.py** [](https://nbviewer.org/github/Tufts-University/FLOCK/blob/main/Tutorials/Leadership-Metrics.ipynb)\n * Directional correlation time delay leadership metrics from [Nagy et. al.](https://www.nature.com/articles/nature08891) including the directional correlation time delay for each individual, Highly correlated segments (HCS) for each pair and directed graph representation of the directional correaltion time dealy leadership heirarchy for each movement period \n<p align=\"center\"> \n <img src=\"https://github.com/Tufts-University/FLOCK/blob/main/Figures/DirCorrFig.png\" alt=\"Directional correlation time delay figure\" width=\"300\" title=\"Directional correlation leadership heirarchy\" /> <br>\n <em>Leadership heirarchy from the directional correlation time delay analysis</em>\n</p>\n\n* **ClusteringFeats.py** [](https://nbviewer.org/github/Tufts-University/FLOCK/blob/main/Tutorials/Clustering-Metrics.ipynb)\n * Features from clustering analysis using a density-based clustering method (DBSCAN) and/or a heirarchical density-based clustering method (HDBSCAN)\n\n\n<p align=\"center\"> \n <img src= 'https://github.com/Tufts-University/FLOCK/blob/main/Figures/GIF_Squad_1_0.gif' alt=\"Clustering gif\" width=\"300\" title=\"Clustering gif\" /> <br>\n <em>HDBSCAN clustering in action, tick lines are 5m apart<br>Outliers are labelled cluster -1<br>Plotly express doesn't allow for categorical legends in scatter animations</em>\n</p>\n\n* **Regularity.py** [](https://nbviewer.org/github/Tufts-University/FLOCK/blob/main/Tutorials/Regularity-Metrics.ipynb)\n * Movement regularity feature extraction including PACS coordinate entropy for each individual at each movement period, Vector autoregression with and without exogenous varaibles for predicability of each individual's movement over time, and entropy measures for all features that are calculated over time\n \n\n## Predictive modelling [](https://github.com/Tufts-University/FLOCK/blob/main/PredictiveModeling/Predictive-Modeling.ipynb)\nCase study: During a 72 hour field study, 16 groups of soldiers complete a 'loaded ruck march' before engaging in strategic and tactical exercises the next day. During these exercises, experts score each of the groups. Our goal is to predict the expert's score of each group from features calculated with this toolbox during the loaded ruck march. To select features, we employ the [Terminating Random Experiments (TRex)](https://github.com/jasinmachkour/TRexSelector) method. We then train a linear regression model using only the selected features.\n\n* **Explanatory model**\n * Here we use all of our datapoints (16 groups) to select important features and we report the model's performance on the training data. This exploratory model achieves an R squared score of 0.82.\n<p align=\"center\"> \n <img src=\"https://github.com/Tufts-University/FLOCK/blob/main/Figures/ExplanatoryModelResults.png\" alt=\"Explanatory Model Results\" width=\"300\" title=\"Explanatory Model Results\" /> <br>\n <em>Explanatory Model Results</em>\n</p>\n\n* **Predictive model**\n * Here we employ a Leave-One-Out cross validation method, where we select features and train a new model for each iteration, then test the model on the left out datapoint. This predictive model achieves an R squared score of 0.63.\n<p align=\"center\"> \n <img src=\"https://github.com/Tufts-University/FLOCK/blob/main/Figures/PredictiveModelResults.png\" alt=\"Predictive Model Results\" width=\"300\" title=\"Predictive Model Results\" /> <br>\n <em>Predictive Model Results</em>\n</p>\n\n**Why the T-Rex selector?** <br>\nCompared with a basic Least Absolute Shrinkage and Selection Operator (LASSO) feature selection method, the TRex achieves a much higher stability (i.e. the selcted features in each Leave-One-Out iteration are more similar). The LASSO struggles with wide datasets (small number of observations and large number of features), especially when there is a low sparsity (a high amount of relevant features) such as with our sample study dataset.\n\n\n## Citation information\n\nPlease cite [[0]](#publications) when using FLOCK-GPS in your research and reference the appropriate release version.\n\n## Publications\n\n### About FLOCK-GPS\n\n[0] COMING SOON\n\nAPPROVED FOR PUBLIC RELEASE: PR2024-1237\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A package for extracting metrics from group movement GPS data",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/Tufts-University/FLOCK",
"Issues": "https://github.com/Tufts-University/FLOCK/issues"
},
"split_keywords": [
"gps",
" group dynamics",
" group movement",
" human performance prediction",
" machine learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a0430247dc2db1a274d4acc136cde201eafce2d9d874ad9107b67b83fa4c3f29",
"md5": "6026dc5157eda0ed188343e0273e029a",
"sha256": "892b69de76073b36e732ea8241dcec030edcc4432cb6e5a6b0009dc50b5f6f17"
},
"downloads": -1,
"filename": "flock_gps-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6026dc5157eda0ed188343e0273e029a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 38303,
"upload_time": "2024-07-02T17:35:55",
"upload_time_iso_8601": "2024-07-02T17:35:55.973803Z",
"url": "https://files.pythonhosted.org/packages/a0/43/0247dc2db1a274d4acc136cde201eafce2d9d874ad9107b67b83fa4c3f29/flock_gps-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b8733fe3362df1dd2bb11c7d6cb4d1f9719e9f8e59d2195e18bc2729be769437",
"md5": "91de104a55a4c018c010cfce39b45a58",
"sha256": "21df4bb625a23fe82d503011ad4e00aabbeb043aa104ebcce489aa3b6a77b44b"
},
"downloads": -1,
"filename": "flock_gps-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "91de104a55a4c018c010cfce39b45a58",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26750009,
"upload_time": "2024-07-02T17:35:57",
"upload_time_iso_8601": "2024-07-02T17:35:57.740118Z",
"url": "https://files.pythonhosted.org/packages/b8/73/3fe3362df1dd2bb11c7d6cb4d1f9719e9f8e59d2195e18bc2729be769437/flock_gps-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-02 17:35:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Tufts-University",
"github_project": "FLOCK",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "flock-gps"
}
JSON
