Computational geometric tools for quantitative comparison of locomotory behavior
Project description
Locomotion - Quantitative Comparisons of Locomotive Behavior
locomotion
is a Python package that provides computational geometric tools for
quantitative comparisons of locomotive behaviors. The package makes use of curve
and shape alignment techniques to accurately quantify (dis)similarities in
animal behavior without excluding inherent variability present between
individuals.
For more information on the techniques implemented in this repository, please read our publication.
Table of Contents
- Getting Started
- Data Format
- Using the Package
- Contributing
- Versioning
- Authors
- Citation
- License
- Acknowledgments
Getting Started
To begin using the locomotion
package, please follow the installation
instructions below. After the package has been successfully installed, please
proceed to the Data Format section to understand how your data
should be formatted for use.
Installation and Requirements
As of 24 January 2020, the locomotion
package has been converted for use on
Python 3.7.3. This module also requires the following python packages:
- numpy (>= 1.16.2)
- scipy (>= 1.5.0)
- plotly (>= 4.4.1)
- dtw-python (>= 1.1.4)
- igl (>=2.2.0)
Installation instructions
The locomotion
package is available for installation on
PyPI, which can be done by running the
following command on your terminal:
pip install locomotion
Another installation option is to install it from the source directory directly. Once you've cloned the directory or downloaded the source file, run the following command while in the main directory.
python setup.py install
Note: One of our dependencies, igl
, is still in development phase, and is
not currently on PyPI. You will have to install it manually in order to use
locomotion
. You may find the installation instructions
here.
After installing all the requirements, you should now be able to run import locomotion
in your Python shell.
Checking the installation
To ensure that all the functions in the package work as intended, run the
jupyter notebook scripts/example_notebook.ipynb
. Follow through the notebook,
which will run through the basic functions of the package. If the package is
installed properly, it should be able to generate a small sample dataset and run
the BDD and CSD methods on it.
Data Format
File Format
The package accepts .csv
and .tsv
files. However, because it distinguishes
between tsv and csv by doing a simple check to see if tabs or commas are present
in the first (header) line, make sure to avoid using both delimiters in the
header of your data file. If your data must use both, you will need to edit the
get_raw_data
function in animal.py
.
Header Format
The computations require X and Y coordinate data with corresponding column titles in string format, so the coordinate data columns must be labelled "X" and "Y", including the quotation marks. They can also be single quotes.
Information File Format
The information about the animals are stored in a json file, which is required to read in relevant data for each computation. The fields and format are as in this sample entry below. Note that all times are in minutes. In general, avoid using spaces in the field values.
{
"name": "NSS_01", //Can be anything. Make it unique
"data_file_location": "/data/medaka/NSS_01.dat",
//full path to the data file
"animal_attributes": {
"species": "Medaka", //species name
"exp_type": "NSS", //experiment type
"ID": "01" //number, but in quotations
},
"capture_attributes": {
"frames_per_sec": 20, //integer
"pixels_per_mm": 1.6, //float
"dim_x": 200, //in mm
"dim_y": 100, //in mm
"start_time": 0, //in min
"end_time": 10, //in min
"baseline_start_time": 0, //in min
"baseline_end_time": 2 //in min
}
}
To generate the info file, you can make use of scripts/json_generator.ipynb
which contains a step-by-step walkthrough that populates a .json
file, prompting
you to include the correct data.
Using the Package
Once you import the locomotion
package, you will need to first initiate animal
objects using the locomotion.setup_animal_objs
command, which returns a list of
animal objects with basic X and Y data from the data files.
The routines for calculating Behavioral Distortion Distance (BDD) are located in
the trajectory.py
file and can be called by
locomotion.trajectory.[routine_name]
.
Example script:
import locomotion
info_files = ["/path/to/animal_info.json"]
animals = locomotion.setup_animal_objs( info_files )
for a in animals:
locomotion.trajectory.populate_curve_data( a )
variables = ['Y','Velocity','Curvature']
start_time, end_time = 0, 1
norm_mode = 'spec'
distances = locomotion.trajectory.compute_all_bdd( animals, variables, start_time, end_time, norm_mode )
output_directory, outfile_name = "/path/to/outdir", "results"
sort_table, square_table = False, False
color_min, color_max = 0.1, 0.5
locomotion.write.post_process( animals, distances, output_directory, outfile_name, sort_table, square_table, color_min, color_max )
To calculate the Intra-Individual Behavioral Distortion Distance (IIBDD) for each animal in a specified info sheet, one can run a script like the following:
import locomotion
info_files = ["/path/to/animal_info.json"]
animals = locomotion.setup_animal_objs( info_files )
for a in animals:
locomotion.trajectory.populate_curve_data( a )
variables = ['Y','Velocity','Curvature']
norm_mode = 'spec'
number_of_samples = 100
output_directory, outfile_name = "/path/to/outdir", "results.csv"
start_time, end_time = 0, 1
iibdds = locomotion.trajectory.compute_all_iibdd( animals, variables, norm_mode, number_of_samples, start_time=start_time, end_time=end_time )
locomotion.write.write_iibdd_to_csv( animals, iibdds, output_directory, outfile_name )
The routines for calculating Conformal Spatiotemporal Distance (CSD) are located
in the heatmap.py
file and can be called by locomotion.heatmap.[routine_name]
.
Example script:
import locomotion
info_files = ["/path/to/animal_info.json"]
animals = locomotion.setup_animal_objs( info_files )
grid_size, start_time, end_time = 10, 0, 2
for a in animals:
locomotion.heatmap.populate_surface_data( a, grid_size, start_time, end_time )
distances = locomotion.heatmap.compute_all_csd( animals )
output_directory, outfile_name = "/path/to/outdir", "results"
sort_table, square_table = False, False
color_min, color_max = 0, 0.2
locomotion.write.post_process( animals, distances, output_directory, outfile_name, sort_table, square_table, color_min, color_max )
Contributing
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
Versioning
We use SemVer for versioning. For the versions available, see the tags on this repository.
Authors
This package was written by Matthew T. Stamps, Zhong Xuan Khwa, Elaine Wijaya, Soo Go, and Ajay S. Mathuru.
See also the list of contributors who participated in this project.
Citation
If you use locomotion
in a scientific paper, we would appreciate citations to
the following paper:
Stamps, M.T., Go, S. & Mathuru, A.S. Computational geometric tools for quantitative comparison of locomotory behavior. Sci Rep 9, 16585 (2019). https://doi.org/10.1038/s41598-019-52300-8
Preferred citation format can be found here.
License
This project is licensed under the MIT License - see the LICENSE.md file for details
Acknowledgments
We would like to acknowledge the work of Alaukik Pant, Haroun Chahed, Karolina Grzeszkiewicz, Katherine Sun, Lucy Zhu, Sultan Aitzhan, and Yanhua Wang, for their contributions to this package.
README template provided by PurpleBooth.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for locomotion-1.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c7ea21ac42a543c955ee40a561d97ac0188a677fb15d0692bd4149e0ccc26abb |
|
MD5 | 73be2495709e823d3dac82416becfb27 |
|
BLAKE2b-256 | 652ff8173049eabc1f5fc02cbfe3a652a530a1f51b86e764161593ce0609fa54 |