Skip to main content

Traja is a trajectory analysis and visualization tool

Project description

Colab

Traja is a Python library for trajectory analysis. It extends the capability of pandas DataFrame specific for animal trajectory analysis in 2D, and provides convenient interfaces to other geometric analysis packages (eg, R and shapely).

Introduction

The traja Python package is a toolkit for the numerical characterization and analysis of the trajectories of moving animals. Trajectory analysis is applicable in fields as diverse as optimal foraging theory, migration, and behavioral mimicry (e.g. for verifying similarities in locomotion). A trajectory is simply a record of the path followed by a moving animal. Traja operates on trajectories in the form of a series of locations (as x, y coordinates) with times. Trajectories may be obtained by any method which provides this information, including manual tracking, radio telemetry, GPS tracking, and motion tracking from videos.

The goal of this package (and this document) is to aid biological researchers, who may not have extensive experience with Python, to analyze trajectories without being restricted by a limited knowledge of Python or programming. However, a basic understanding of Python is useful.

If you use traja in your publications, please cite the repo

@software{justin_shenk_2019_3237827,
  author       = {Justin Shenk and
                  the Traja development team},
  title        = {justinshenk/traja},
  month        = jun,
  year         = 2019,
  publisher    = {Zenodo},
  version      = {latest},
  doi          = {10.5281/zenodo.3237827},
  url          = {https://doi.org/10.5281/zenodo.3237827}
}

Installation and setup

To install traja with conda, run

conda install -c conda-forge traja

or with pip

pip install traja.

Import traja into your Python script or via the Python command-line with import traja.

Trajectories with traja

Traja stores trajectories in pandas DataFrames, allowing any pandas functions to be used.

Load trajectory with x, y and time coordinates:

import traja

df = traja.read_file('coords.csv')

Once a DataFrame is loaded, use the .traja accessor to access the visualization and analysis methods:

df.traja.plot(title='Cage trajectory')

Analyze Trajectory

The following functions are available via traja.trajectory.[method]

Function

Description

calc_derivatives

Calculate derivatives of x, y values

calc_turn_angles

Calculate turn angles with regard to x-axis

transitions

Calculate first-order Markov model for transitions between grid bins

generate

Generate random walk

resample_time

Resample to consistent step_time intervals

rediscretize_points

Rediscretize points to given step length

For up-to-date documentation, see https://traja.readthedocs.io.

Random walk

Generate random walks with

df = traja.generate(n=1000, step_length=2)
df.traja.plot()
walk\_screenshot.png

Resample time

traja.trajectory.resample_time allows resampling trajectories by a step_time.

Flow Plotting

df = traja.generate()
traja.plot_surface(df)
3D plot
traja.plot_quiver(df, bins=32)
quiver plot
traja.plot_contour(df, filled=False, quiver=False, bins=32)
contour plot
traja.plot_contour(df, filled=False, quiver=False, bins=32)
contour plot filled
traja.plot_contour(df, bins=32, contourfplot_kws={'cmap':'coolwarm'})
streamplot

Acknowledgements

traja code implementation and analytical methods (particularly rediscretize_points) are heavily inspired by Jim McLean’s R package trajr. Many thanks to Jim for his feedback.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

traja-22.0.0.tar.gz (6.5 MB view details)

Uploaded Source

Built Distribution

traja-22.0.0-py3-none-any.whl (91.8 kB view details)

Uploaded Python 3

File details

Details for the file traja-22.0.0.tar.gz.

File metadata

  • Download URL: traja-22.0.0.tar.gz
  • Upload date:
  • Size: 6.5 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/4.8.1 pkginfo/1.8.2 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.63.0 CPython/3.8.5

File hashes

Hashes for traja-22.0.0.tar.gz
Algorithm Hash digest
SHA256 4a4fff54216dadd9a8c2470ab864ccab296d11fb3866000efc7c1729c8bd2463
MD5 d85e856da4a43b2ea2c67b058a9ebe16
BLAKE2b-256 c8e706509c9262514b68ac7c4a8657a52373fe9eff49dc79b4d7139e2cbdf733

See more details on using hashes here.

File details

Details for the file traja-22.0.0-py3-none-any.whl.

File metadata

  • Download URL: traja-22.0.0-py3-none-any.whl
  • Upload date:
  • Size: 91.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/4.8.1 pkginfo/1.8.2 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.63.0 CPython/3.8.5

File hashes

Hashes for traja-22.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f32195fa33003a30770313e9d8178347a36334d851e57dc88a21c3d3d95a18b1
MD5 c0744c37fed0e7238f4f2eaccdf1e819
BLAKE2b-256 e6d8797d7abe859155e3b96cd46c1d7400a143c1eae19231e848c068d71e1397

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page