Skip to content

Latest commit

 

History

History
260 lines (193 loc) · 10.6 KB

README.md

File metadata and controls

260 lines (193 loc) · 10.6 KB
Raw

trackpy

build status doi

What is it?

trackpy is a Python package providing tools for particle tracking. Read the walkthrough to skim or study an example project from start to finish.

Then browse a list of more examples, or download the full repository of sample code and data to try them yourself.

There are many similar projects. (See table below.) Our implementation is distinguished by succinct and flexible usage, a thorough testing framework ensuring code stability and accuracy, scalability, and complete documentation.

Several researchers have merged their independent efforts into this code. We would like to see others in the community adopt it and potentially contribute code to it.

If you use trackpy in published research, please read the section Citing Trackpy.

Features

Basics

  • The widely-used particle locating algorithm originally implemented by John Crocker and Eric Weeks in IDL is reimplemented in Python. Wherever possible, existing tools from widely-used Python modules are employed.
  • This reimplemention is full-featured, including subpixel precision verified with test cases.
  • The module is actively used and tested on Windows, Mac OSX, and Linux, and it uses only free, open-source software.
  • Frames of video can be loaded from a video file (AVI, MOV, etc.), a multi-frame TIFF, or a directory of sequential images (TIFF, PNG, JPG, etc.).
  • Results are given as DataFrames, high-performance spreadsheet-like objects from Python pandas which can easily be saved to a CSV file, Excel spreadsheet, SQL database, HDF5 file, and more.
  • Particle trajectories can be characterized, grouped, and plotted using a suite of convenient functions.
  • To verify correctness and stability, a suite of 150+ tests reproduces basic results.

Special Capabilities

  • Both feature-finding and trajectory-linking can be performed on arbitrarily long videos using a fixed, modest amount of memory. (Results can be read and saved to disk throughout.)
  • A prediction framework helps track particles in fluid flows, or other scenarios where velocity is correlated between time steps.
  • Feature-finding and trajectory-linking works on images with any number of dimensions, making possible some creative applications.
  • Uncertainty is estimated following a method described in this paper by Savin and Doyle.
  • High-performance components (numba acceleration and FFTW support) are used only if if available. Since these can be tricky to install on some machines, the code will automatically fall back on slower pure Python implementations as needed.

Documentation

The examples linked to above are the best place to start. To try them out on your own computer, you will want to have the sample data as well; you can download all of the examples and data from the examples repository. There is also complete documentation for every function in the package.

Installation

For Python Novices

Installation is simple on Windows, OSX, and Linux, even for Python novices.

1. Get Scientific Python

To get started with Python on any platform, download and install Anaconda. It comes with the common scientific Python packages built in.

2. Install trackpy

Open a command prompt. On Windows, you can use the "Anaconda Command Prompt" installed by Anaconda or Start > Applications > Command Prompt. On a Mac, look for Applications > Utilities > Terminal. Type these commands:

conda update conda
conda install -c soft-matter trackpy

The above installs trackpy and all its requirements. Our tutorials also use the IPython notebook. To install that as well, type

conda install ipython-notebook

3. Try it out!

Finally, to try it out, type

ipython notebook

This will automatically open a browser tab, ready to interpret Python code. To get started, check out the links to tutorials at the top of this document.

More Information for Experienced Python Users

We strongly recommend using conda install trackpy, as described above, but pip is also supported.

Essential Dependencies:

You will also need the image- and video-reader PIMS, which is, like trackpy itself, part of the github.com/soft-matter organization.

You can install PIMS from the soft-matter binstar channel using conda:

conda install -c soft-matter pims

or from PyPI using pip:

pip install pims

Or, if you plan to edit the code, you can install both packages manually:

git clone https://github.com/soft-matter/pims
pip install -e pims

git clone https://github.com/soft-matter/trackpy
pip install -e trackpy

Optional Dependencies:

  • pyFFTW to speed up the band pass, which is one of the slower steps in feature-finding
  • PyTables for saving results in an HDF5 file. This is included with Anaconda.
  • numba for accelerated feature-finding and linking. This is included with Anaconda and Canopy. Installing it any other way is difficult; we recommend sticking with one of these. Note that numba v0.12.0 (included with Anaconda 1.9.0) has a bug and will not work at all; if you have this version, you should update Anaconda. We support numba versions 0.11 and 0.12.2.

PIMS has its own optional dependencies for reading various formats. You can read what you need for each format here on PIMS` README.

Updating Your Installation

Latest Stable Release

The code is under active development. To update to the latest stable release, run this in the command prompt:

conda update -c soft-matter trackpy

Latest Version Under Development

The master branch on github contains the latest tested development code. Changes are thoroughly tested before being merged. If you want to use the latest features it should be safe to rely on the master branch. (The primary contributors do.)

You can easily install a recent build from the soft-matter development channel on conda

conda config --add channels soft-matter
conda install -c soft-matter/channel/dev trackpy

If you plan to edit the code yourself, you should use git and pip as given above under "More Information for Advanced Python Users."

Versions & Project Roadmap

See the releases page for details.

The original release is tagged Version 0.1. Although there have been major changes to the code, v0.2.x maintains complete reverse compatibility with v0.1 and can be used as drop-in replacement. We recommend all users upgrade.

Roadmap:

  • expansion of data structures to simplify sharing frame-wise data between research groups
  • interactive filtering and visualization tools
  • continued performance improvments and benchmarking for a range of use cases (frame size, particle density, etc.)
  • tests that compare results again "battle-tested" Crocker-Grier code

Contributors

  • Daniel Allan feature-finding, uncertainty estimation, motion characterization and discrimination, plotting tools, tests
  • Thomas Caswell multiple implementations of sophisticated trajectory-linking, tests
  • Nathan Keim alternative trajectory-linking implementations, major speed-ups, prediction

Citing Trackpy

If you use trackpy for published research, please cite this repository, including the primary contributors' names -- Daniel B. Allan, Thomas A. Caswell, and Nathan C. Keim -- and doi:10.5281/zenodo.9971. If your citation style also allows for a URL, please include github.com/soft-matter/trackpy to help other researchers discover trackpy. Our DOI record page provides more detail and citations in various formats.

Related Projects

Author(s) Project URL Programming Language
Crocker and Grier http://physics.nyu.edu/grierlab/software.html IDL
Crocker and Weeks http://www.physics.emory.edu/~weeks/idl/ IDL
Blair and Dufresne http://physics.georgetown.edu/matlab/ MATLAB
Maria Kilfoil http://people.umass.edu/kilfoil/downloads.html MATLAB and Python
Graham Milne http://zone.ni.com/devzone/cda/epd/p/id/948 LabVIEW
Ryan Smith and Gabe Spalding http://titan.iwu.edu/~gspaldin/rytrack.html stand alone/IDL GUI
Peter J Lu https://github.com/peterlu/PLuTARC_centerfind2D C++ (identification only)
Thomas A Caswell https://github.com/tacaswell/tracking C++

Support

This package was developed in part by Daniel Allan, as part of his PhD thesis work on microrheology in Robert L. Leheny's group at Johns Hopkins University in Baltimore, MD. The work was supported by the National Science Foundation under grant number CBET-1033985. Dan can be reached at dallan@pha.jhu.edu.

This package was developed in part by Thomas A Caswell as part of his PhD thesis work in Sidney R Nagel's and Margaret L Gardel's groups at the University of Chicago, Chicago IL. This work was supported in part by NSF Grant DMR-1105145 and NSF-MRSEC DMR-0820054. Tom can be reached at tcaswell@gmail.com.

This package was developed in part by Nathan C. Keim, as part of his postdoctoral research in Paulo Arratia's group at the University of Pennsylvania, Philadelphia. This work was supported by NSF-MRSEC DMR-1120901.