[](https://badge.fury.io/py/trajpy)
[](https://trajpy.readthedocs.io/en/latest/?badge=latest)
[](https://www.python.org/downloads/)
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://zenodo.org/badge/latestdoi/194252287)
[](https://mybinder.org/v2/gh/ocbe-uio/trajpy/master?labpath=%2Fexamples%2Fclinical_data_analysis_tutorial.ipynb)
# TrajPy
Trajectory analysis is a challenging task and fundamental for
understanding the movement of living organisms in various scales.
We propose TrajPy as an easy pythonic solution to be applied in studies that
demand trajectory analysis. With a friendly graphic user interface (GUI) it requires little knowledge of computing
and physics to be used by nonspecialists.
TrajPy is composed of three main units of code:
- Basic usage:
- The GUI: it is where you interact with trajpy and the only thing you need to know to start using it
- Advanced
- trajpy.py: it's the heart of trajpy, it computes the **Features** for characterizing the trajectories
- traj_generator.py: a **trajectory generator** that can be used to build a dataset for trajectory classification
Our dataset and Machine Learning (ML) model are available for use, as well
the generator for building your own database.
## Installation
We have the package hosted at PyPi, for installing use the command line:
```bash
pip3 install trajpy
```
If you want to test the development version, clone the repository at your local directory from your terminal:
```bash
git clone https://github.com/ocbe-uio/trajpy
```
Then run the setup.py for installing
```bash
python setup.py --install
```
## Basic Usage Example
### Using the Graphic User Interface (GUI)
Open a terminal and execute the line bellow
```bash
python3 -m trajpy.gui
```
1 - You can open one file at time clicking on `Open file...` or process several files in the same director with `Open directory...`
2 - Select the features to be computed by ticking the boxes
3 - Click on `Compute`
4 - Select the directory and file name where the results will be stored
The processing is ready when the following message appears in the text box located at the bottom of the GUI:
`Results saved to /path/to/results/output.csv`
### File formats
#### Comma separated values (CSV)
Currently trajpy support CSV files organized in 4 columns: time `t` and 3 spatial coordinates `x`, `y`, `z`:
|t|x|y|z|
|---|---|---|---|
| 1.00 | 10.00 | 50.00 | 50.00
| 2.00 | 11.00 | 50.00 | 50.00
| 3.00 | 11.00 | 50.00 | 50.00
| 4.00 | 12.00 | 50.00 | 50.00
| 5.00 | 12.00 | 50.00 | 50.00
| 6.00 | 13.00 | 50.00 | 50.00
See the [sample file](https://github.com/ocbe-uio/trajpy/blob/a370e49444ea845becb573fd5cc835b5c899c7dc/data/samples/sample.csv) provided in this repository as example.
#### LAMMPS YAML dump format
LAMMPS YAML files are defined with the following structure:
```yaml
---
time: 0.0
natoms: 100
keywords: [id, type, x, y, z, vx, vy, vz, fx, fy, fz]
data:
- [1, 1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, -nan, -nan, -nan]
- [2, 1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, -nan, -nan, -nan]
- [3, 1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, -nan, -nan, -nan]
...
```
We provide support for parsing this type of data files with the function [`parse_lammps_dump_yaml()`](https://github.com/ocbe-uio/trajpy/blob/8381bedfc3f0d696072af1d66f08af497eb0cced/trajpy/auxiliar_functions.py#L5).
### Scripting
First we import the package
```python
import trajpy.trajpy as tj
```
Then we load the data sample provided in this repository, we pass the arguments `skip_header=1`
to skip the first line of the file and `delimiter=','` to specify the file format
``` python
filename = 'data/samples/sample.csv'
r = tj.Trajectory(filename,
skip_header=1,
delimiter=',')
```
Finally, for computing a set of features for trajectory analysis we can simple run the function `r.compute_features()`
```python
r.compute_features()
```
The features will be stored in the object `r`, for instance:
```python
>>> r.asymmetry
>>> 0.5782095322093505
>>> r.fractal_dimension
>>> 1.04
>>> r.efficiency
>>> 0.29363293632936327
>>> r.gyration_radius
>>> array([[30.40512689, 5.82735002, 0.96782673],
>>> [ 5.82735002, 2.18625318, 0.27296851],
>>> [ 0.96782673, 0.27296851, 2.41663589]])
```
For more examples please consult the extended documentation: https://trajpy.readthedocs.io/
## Requirements
- numpy >= 1.14.3
- scipy >= 1.7.1
- ttkthemes >= 2.4.0
- Pillow >= 8.1.0
- PyYAML >= 5.3.1
## Citation
If using the TrajPy package in academic work, please cite Moreira-Soares et al. (2020), in addition to the relevant methodological papers.
```latex
@article{moreira2020adhesion,
title={Adhesion modulates cell morphology and migration within dense fibrous networks},
author={Moreira-Soares, Maur{\'\i}cio and Cunha, Susana P and Bordin, Jos{\'e} Rafael and Travasso, Rui DM},
journal={Journal of Physics: Condensed Matter},
volume={32},
number={31},
pages={314001},
year={2020},
publisher={IOP Publishing}
}
@software{mauricio_moreira_2020_3978699,
author = {Mauricio Moreira and Eduardo Mossmann},
title = {phydev/trajpy: TrajPy 1.3.1},
month = aug,
year = 2020,
publisher = {Zenodo},
version = {1.3.1},
doi = {10.5281/zenodo.3978699},
url = {https://doi.org/10.5281/zenodo.3978699}
}
```
## Contribution
This is an open source project, and all contributions are welcome. Feel free to open an Issue, a Pull Request, or to e-mail us.
## Publications using trajpy
Eduardo Henrique Mossmann. [A physics based feature engineering framework for trajectory analysis](#). MSc dissertation. Federal University of Pelotas 2022, Brazil.
Simões, RF, Pino, R, Moreira-Soares, M, et al. [Quantitative Analysis of Neuronal Mitochondrial Movement Reveals Patterns Resulting from Neurotoxicity of Rotenone and 6-Hydroxydopamine.](https://faseb.onlinelibrary.wiley.com/doi/10.1096/fj.202100899R) FASEB J. 2021; 35:e22024. doi:10.1096/fj.202100899R
Moreira-Soares, M., Pinto-Cunha, S., Bordin, J. R., Travasso, R. D. M. *[Adhesion modulates cell morphology and migration within dense fibrous networks](https://www.biorxiv.org/content/10.1101/838995v1)*. https://doi.org/10.1088/1361-648X/ab7c17
## References
Arkin, H. and Janke, W. 2013. Gyration tensor based analysis of the shapes of polymer chains in an attractive spherical cage. J Chem Phys 138, 054904.
Wagner, T., Kroll, A., Haramagatti, C.R., Lipinski, H.G. and Wiemann, M. 2017. Classification and Segmentation of Nanoparticle Diffusion Trajectories in Cellular Micro Environments. PLoS One 12, e0170165.
Raw data
{
"_id": null,
"home_page": "https://github.com/ocbe-uio/trajpy.git",
"name": "trajpy",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "trajectory quantification,feature engineering,diffusion classification",
"author": "Mauricio Moreira",
"author_email": "trajpy@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/6f/9e/fe8a65430832be507740af9dcd2db0a52a9e14f8264ea2a3e2033d18ef8a/trajpy-1.4.3.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/trajpy)\n\n[](https://trajpy.readthedocs.io/en/latest/?badge=latest)\n[](https://www.python.org/downloads/) \n[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://zenodo.org/badge/latestdoi/194252287)\n[](https://mybinder.org/v2/gh/ocbe-uio/trajpy/master?labpath=%2Fexamples%2Fclinical_data_analysis_tutorial.ipynb)\n\n# TrajPy\n\nTrajectory analysis is a challenging task and fundamental for\nunderstanding the movement of living organisms in various scales.\n\nWe propose TrajPy as an easy pythonic solution to be applied in studies that\ndemand trajectory analysis. With a friendly graphic user interface (GUI) it requires little knowledge of computing\nand physics to be used by nonspecialists.\n\nTrajPy is composed of three main units of code:\n\n- Basic usage:\n - The GUI: it is where you interact with trajpy and the only thing you need to know to start using it\n- Advanced \n - trajpy.py: it's the heart of trajpy, it computes the **Features** for characterizing the trajectories \n - traj_generator.py: a **trajectory generator** that can be used to build a dataset for trajectory classification\n\n\nOur dataset and Machine Learning (ML) model are available for use, as well\nthe generator for building your own database.\n\n## Installation\n\n\nWe have the package hosted at PyPi, for installing use the command line: \n```bash\npip3 install trajpy\n```\nIf you want to test the development version, clone the repository at your local directory from your terminal:\n```bash\ngit clone https://github.com/ocbe-uio/trajpy\n```\nThen run the setup.py for installing \n```bash\npython setup.py --install\n```\n\n## Basic Usage Example\n\n### Using the Graphic User Interface (GUI)\n\nOpen a terminal and execute the line bellow\n```bash\npython3 -m trajpy.gui\n```\n\n1 - You can open one file at time clicking on `Open file...` or process several files in the same director with `Open directory...`\n\n2 - Select the features to be computed by ticking the boxes\n\n3 - Click on `Compute`\n\n4 - Select the directory and file name where the results will be stored\n\nThe processing is ready when the following message appears in the text box located at the bottom of the GUI:\n\n`Results saved to /path/to/results/output.csv`\n\n### File formats\n\n#### Comma separated values (CSV)\nCurrently trajpy support CSV files organized in 4 columns: time `t` and 3 spatial coordinates `x`, `y`, `z`:\n\n|t|x|y|z|\n|---|---|---|---|\n| 1.00 | 10.00\u00a0| 50.00 | 50.00\n| 2.00 | 11.00 | 50.00 | 50.00\n| 3.00 | 11.00 | 50.00 | 50.00\n| 4.00 | 12.00 | 50.00 | 50.00\n| 5.00 | 12.00 | 50.00 | 50.00\n| 6.00 | 13.00 | 50.00 | 50.00\n\nSee the [sample file](https://github.com/ocbe-uio/trajpy/blob/a370e49444ea845becb573fd5cc835b5c899c7dc/data/samples/sample.csv) provided in this repository as example.\n\n#### LAMMPS YAML dump format\n\nLAMMPS YAML files are defined with the following structure:\n```yaml\n ---\n time: 0.0\n natoms: 100\n keywords: [id, type, x, y, z, vx, vy, vz, fx, fy, fz]\n data:\n - [1, 1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, -nan, -nan, -nan]\n - [2, 1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, -nan, -nan, -nan]\n - [3, 1, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, -nan, -nan, -nan]\n ...\n```\nWe provide support for parsing this type of data files with the function [`parse_lammps_dump_yaml()`](https://github.com/ocbe-uio/trajpy/blob/8381bedfc3f0d696072af1d66f08af497eb0cced/trajpy/auxiliar_functions.py#L5).\n\n\n### Scripting\n\nFirst we import the package \n```python\nimport trajpy.trajpy as tj\n```\nThen we load the data sample provided in this repository, we pass the arguments `skip_header=1`\n to skip the first line of the file and `delimiter=','` to specify the file format\n``` python\nfilename = 'data/samples/sample.csv'\nr = tj.Trajectory(filename,\n skip_header=1,\n delimiter=',')\n```\nFinally, for computing a set of features for trajectory analysis we can simple run the function `r.compute_features()`\n```python\n r.compute_features()\n```\nThe features will be stored in the object `r`, for instance:\n```python\n >>> r.asymmetry\n >>> 0.5782095322093505\n >>> r.fractal_dimension\n >>> 1.04\n >>> r.efficiency\n >>> 0.29363293632936327\n >>> r.gyration_radius\n >>> array([[30.40512689, 5.82735002, 0.96782673],\n >>> [ 5.82735002, 2.18625318, 0.27296851],\n >>> [ 0.96782673, 0.27296851, 2.41663589]])\n```\n\nFor more examples please consult the extended documentation: https://trajpy.readthedocs.io/\n\n## Requirements\n\n- numpy >= 1.14.3\n- scipy >= 1.7.1\n- ttkthemes >= 2.4.0\n- Pillow >= 8.1.0\n- PyYAML >= 5.3.1\n\n\n## Citation\nIf using the TrajPy package in academic work, please cite Moreira-Soares et al. (2020), in addition to the relevant methodological papers.\n\n```latex\n@article{moreira2020adhesion,\n title={Adhesion modulates cell morphology and migration within dense fibrous networks},\n author={Moreira-Soares, Maur{\\'\\i}cio and Cunha, Susana P and Bordin, Jos{\\'e} Rafael and Travasso, Rui DM},\n journal={Journal of Physics: Condensed Matter},\n volume={32},\n number={31},\n pages={314001},\n year={2020},\n publisher={IOP Publishing}\n}\n\n@software{mauricio_moreira_2020_3978699,\n author = {Mauricio Moreira and Eduardo Mossmann},\n title = {phydev/trajpy: TrajPy 1.3.1},\n month = aug,\n year = 2020,\n publisher = {Zenodo},\n version = {1.3.1},\n doi = {10.5281/zenodo.3978699},\n url = {https://doi.org/10.5281/zenodo.3978699}\n}\n```\n\n## Contribution\nThis is an open source project, and all contributions are welcome. Feel free to open an Issue, a Pull Request, or to e-mail us.\n\n## Publications using trajpy\n\nEduardo Henrique Mossmann. [A physics based feature engineering framework for trajectory analysis](#). MSc dissertation. Federal University of Pelotas 2022, Brazil.\n\n Sim\u00f5es, RF, Pino, R, Moreira-Soares, M, et al. [Quantitative Analysis of Neuronal Mitochondrial Movement Reveals Patterns Resulting from Neurotoxicity of Rotenone and 6-Hydroxydopamine.](https://faseb.onlinelibrary.wiley.com/doi/10.1096/fj.202100899R) FASEB J. 2021; 35:e22024. doi:10.1096/fj.202100899R\n\nMoreira-Soares, M., Pinto-Cunha, S., Bordin, J. R., Travasso, R. D. M. *[Adhesion modulates cell morphology and migration within dense fibrous networks](https://www.biorxiv.org/content/10.1101/838995v1)*. https://doi.org/10.1088/1361-648X/ab7c17\n\n## References\nArkin, H. and Janke, W. 2013. Gyration tensor based analysis of the shapes of polymer chains in an attractive spherical cage. J Chem Phys 138, 054904.\n\nWagner, T., Kroll, A., Haramagatti, C.R., Lipinski, H.G. and Wiemann, M. 2017. Classification and Segmentation of Nanoparticle Diffusion Trajectories in Cellular Micro Environments. PLoS One 12, e0170165.\n",
"bugtrack_url": null,
"license": "GNU GPLv3",
"summary": "Empowering feature engineering for trajectory analysis across domains.",
"version": "1.4.3",
"project_urls": {
"Homepage": "https://github.com/ocbe-uio/trajpy.git"
},
"split_keywords": [
"trajectory quantification",
"feature engineering",
"diffusion classification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ae0f9c6f863a4b59bfd279db43f0f57e9e1d766595b41976ae7dcf49eeb1deb5",
"md5": "f31611fa292056afecb3cb0e68cc9199",
"sha256": "97272cd973c625d8e6c1fffd518783843f38f46db96957746aef6de38d069519"
},
"downloads": -1,
"filename": "trajpy-1.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f31611fa292056afecb3cb0e68cc9199",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 31876,
"upload_time": "2023-08-18T13:30:35",
"upload_time_iso_8601": "2023-08-18T13:30:35.054904Z",
"url": "https://files.pythonhosted.org/packages/ae/0f/9c6f863a4b59bfd279db43f0f57e9e1d766595b41976ae7dcf49eeb1deb5/trajpy-1.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6f9efe8a65430832be507740af9dcd2db0a52a9e14f8264ea2a3e2033d18ef8a",
"md5": "b0962879af0057e1c23168675afb9874",
"sha256": "a69b3ceebf737ca97ec5364d014b098d974379bcd56efcce025bbad361ab5910"
},
"downloads": -1,
"filename": "trajpy-1.4.3.tar.gz",
"has_sig": false,
"md5_digest": "b0962879af0057e1c23168675afb9874",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 32346,
"upload_time": "2023-08-18T13:30:36",
"upload_time_iso_8601": "2023-08-18T13:30:36.879651Z",
"url": "https://files.pythonhosted.org/packages/6f/9e/fe8a65430832be507740af9dcd2db0a52a9e14f8264ea2a3e2033d18ef8a/trajpy-1.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-18 13:30:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ocbe-uio",
"github_project": "trajpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "trajpy"
}
JSON
