trackpy

trackpy is a Python package designed for particle tracking in 2D, 3D, and higher dimensions. It provides a suite of tools for:

• Tracking: Locating and linking particles across frames.
• Motion Analysis: Analyzing the trajectories of tracked particles.
• Plotting: Visualizing particles, trajectories, and results.
• Advanced Workflows: Support for 3D tracking, uncertainty estimation, adaptive linking, and streaming data (on-disk processing).

Trackpy includes several advanced features for complex tracking scenarios:

• Scalability: Both feature-finding and trajectory-linking can be performed on arbitrarily long videos using a fixed, modest amount of memory by reading/saving results to disk throughout the process.
• Prediction Framework: Helps track particles in fluid flows or scenarios where velocity is correlated between time steps.
• Dimensionality: Works on images with any number of dimensions.
• Uncertainty Estimation: Estimates uncertainty following the Savin and Doyle method.
• Adaptive Search: Automatically adjusts parameters to prevent the algorithm from failing or becoming too slow.
• Performance: Uses numba acceleration if available; otherwise, it automatically falls back to pure Python implementations.

The core functionality of trackpy is organized into a three-step pipeline for particle tracking:

1. Locating features: Finding particles/features within individual images (e.g., using trackpy.locate).
2. Refining coordinates: Improving the precision of found features to achieve subpixel accuracy (e.g., using trackpy.refine_com or trackpy.refine_leastsq).
3. Linking: Identifying the same features across consecutive frames in time to build trajectories (e.g., using trackpy.link).

For simple workflows, convenience functions like trackpy.batch can automate these steps.

Trackpy provides a generic interface for storing and retrieving particle tracking data, allowing researchers to use different file formats. While the interface is designed to be subclassed for custom formats, it currently provides optimized implementations for HDF5 files.

Recommended HDF5 implementations:

• trackpy.PandasHDFStoreBig: A good general-purpose choice for large datasets.
• trackpy.PandasHDFStore: Standard HDF5 storage.
• trackpy.PandasHDFStoreSingleNode: Optimized for specific HDF5 structures.

To implement support for a new file format, subclass trackpy.FramewiseData.

Trackpy is designed to work with common scientific data formats:

• Input: Video frames are loaded via the PIMS sister project. Supported formats include:
  • Video files (AVI, MOV, etc.)
  • Specialized formats (LEI, ND2, SEQ, CINE)
  • Multi-frame TIFF
  • Directories of sequential images (TIFF, PNG, JPG, etc.)
• Output: Results are returned as pandas DataFrames. These can be easily exported to:
  • CSV files
  • Excel spreadsheets
  • SQL databases
  • HDF5 files

Trackpy follows a three-step process to track blob-like features in video images:

1. Feature finding: Initial feature coordinates are obtained from the images.
2. Refinement: Sub-pixel precision is obtained in the coordinates using a least-squares fitting framework that supports any radial model function in 2D and 3D.
3. Linking: Coordinates are linked across time steps to yield feature trajectories.

Advanced workflows may combine linking and feature-finding into a single routine where feature-finding optionally uses the history of feature coordinates.

To isolate your trackpy installation from other Python projects, create a dedicated conda environment named softmatter. Including nb_conda ensures the environment is visible within Jupyter notebooks.

conda create --name softmatter trackpy nb_conda

# To activate the environment on Linux/macOS:
source activate softmatter

# To activate the environment on Windows:
activate softmatter

Trackpy uses logging to report progress on long-running jobs. Upon import, trackpy automatically calls handle_logging(), which configures the logging level and a handler optimized for IPython notebooks.

To customize logging:

1. Call trackpy.ignore_logging() to stop the automatic configuration.
2. Configure the standard Python logging module as desired.

trackpy is designed to be extensible for non-standard particle types or custom detection requirements. Key customization tutorials include:

• Tracking Particles' Rings in Bright-Field Microscopy: Specialized detection for ring-like features.
• Tracking Large Features (e.g., Bubbles) and Visualizing Velocity Fields: Custom feature detection and downstream analysis of velocity fields.

When working with datasets that exceed available memory, trackpy provides several strategies for efficient processing:

• Streaming: Using on-disk storage to handle data that doesn't fit in RAM.
• Performance: Optimizing your workflow for speed.
• Parallelized Feature Finding: Distributing the feature detection step across multiple CPU cores to improve throughput.

If you intend to edit the trackpy source code, you can perform a manual installation using git and python setup.py develop.

git clone https://github.com/soft-matter/trackpy
cd trackpy
python setup.py develop