Welcome to diff_classifier

The diff_classifier package is complete particle tracking package implemented using the ImageJ plugin Trackmate.

Motivation

Multi-particle tracking is a powerful tool used in fields as diverse as aeronautics to oceanography that allows researchers to collect spatial information of moving objects from video and image datasets. Examples include:

  • Tracking tracers in ocean currents to study fluid flow
  • Tracking molecular motors (e.g. myosin, kinesin) to assess motile activity
  • Measuring intracellular trafficking by tracking membrane vesicles
  • Assessing microrheological properties by tracking nanoparticle movement.

Multi-particle tracking software packages abound (see for example this Nature methods paper comparing the results of 14 different teams). But researchers are often on their own when it comes to scale up, analysis, and visualization. In practice, each individual video requires user-defined hyperparameters to both accurately identify particles in images and link identified particles from frame to frame. It also raises questions of reproducibility as user-defined parameters vary from user to user. Our parallelized workflow overcomes this challenge using a regression technique using a small subset of images as a training dataset.

Diff_classifier seeks to provide these tools in a centralized package, including MSD and trajectory feature analysis tools, MSD and heatmap plots of output data, and parallelization tools implemented using Amazon Web Services. This package is the primary tool for tracking analysis of nanoparticles in the brain in the Nance research group at the University of Washington.

_images/summary.png

Sample output from diff_classifier visualization tools.

Usage

import diff_classifier.utils as ut
import diff_classifier.msd as msd
import diff_classifier.features as ft
import diff_classifier.imagej as ij
import diff_classifier.heatmaps as hm

prefix = 'test_video'
frames = 651
local_im = prefix + '.tif' # Name of image file
outfile = 'Traj' + local_im.split('.')[0] + '.csv'
msd_file = 'msd_{}.csv'.format(prefix)
ft_file = 'features_{}.csv'.format(prefix)

ij.track(local_im, outfile, template=None, fiji_bin=None, radius=4.5, threshold=0.,
          do_median_filtering=True, quality=4.5, x=511, y=y, ylo=1, median_intensity=300.0, snr=0.0,
          linking_max_distance=8.0, gap_closing_max_distance=10.0, max_frame_gap=2,
          track_displacement=10.0)

df = ut.csv_to_pd(outfile)
msds = msd.all_msds2(df, frames=frames)
features = ft.calculate_features(msds)

hm.plot_trajectories(prefix)

Installation and getting started

To install diff_classifier and begin analyzing your data, visit Getting started with diff_classifier.

Particle tracking

For instructions scripting Trackmate for particle tracking analysis, visit Scripting Trackmate as well as the instructions using the diff_classifier pre-built functions (Tracking particles).

Features analysis

Trajectory features calculations are based off the TrajClassifier package developed by Thorsten Wagner. The calculations can be found at the Traj wiki. Instructions using the diff_classifier implementation can be found at Calculating features.

Interacting with s3

Diff_classifier provides functions for interacting with buckets on AWS S3. Instructions on implementing uploading to/downloading from s3 can be found at Uploading and download with s3.

Cloudknot parallelization

Diff_classifier includes Cloudknot parallelization functions for complete tracking, analysis, and visualization of large tracking experiments. In general, these are only templates, and will have to be modified by the user for their own experimental implementations. Instructions can be found at Cloudknot parallelization.

Bugs and issues

If you are having issues, please let us know by opening a new issue. Please tag your issues with the “bug” or “question” label.

License

This project is licensed under the MIT License.