The analysis pipeline

Track Analyzer analyzes existing tracks; create them first with a tracking tool such as TrackMate. This page describes the common concepts. For the actual controls and any limitations, use the guide for Using the napari plugin, Jupyter notebook, Galaxy, or Command line.

1. Prepare the inputs

The required input is a table of positions with a track identifier, a frame number, X and Y coordinates, and optionally Z coordinates and additional measured variables. For TrackMate, export the spots table. Coordinates may be in pixels or physical units; supply the pixel size, time interval, units and image dimensions as metadata. An image is optional, but is useful for visualizing trajectories over the original movie.

The local graphical interfaces can map source column names to Track Analyzer columns. Galaxy and command-line inputs have more specific naming and file requirements; consult their interface guides.

Preprocessing converts and organizes the positions, handles trajectory gaps according to the selected settings, and computes motion quantities. A saved data_base.p can be reused for subsequent analyses.

2. Select trajectories

Define subsets by spatial ranges, frame windows, and track length. Depending on the interface, you can also select track IDs or tracks passing through a region at a particular time. This allows you to inspect their earlier and later motion. Analyze subsets separately or together with different colors.

3. Analyze trajectories

Plot tracks on a movie or as total trajectories. Examine instantaneous or whole-track quantities with histograms, boxplots, or scatter plots. These include velocity and acceleration; additional numerical variables can be available when supplied in the input.

Mean squared displacement (MSD) plots and model fits can help characterize motion and estimate diffusion. Voronoi tessellation can estimate local area and density; the tessellation is 2D even for 3D tracks.

4. Make maps and compare results

Map analysis averages measurements on a regular 2D grid, optionally over a time window. It produces scalar maps and vector fields, including velocity, acceleration, divergence, and curl. Mean speed and the magnitude of the mean velocity vector are different: the former averages individual speeds, while the latter measures the net motion after averaging directions.

The comparator can pool or compare previously saved trajectory analyses. Datasets must use matching length and time units; the comparator does not convert units.

5. Inspect and reuse outputs

Depending on the chosen analyses, Track Analyzer writes tables, plots, TIFF stacks, and configuration files. Local analyses are organized under traj_analysis and map_analysis in the dataset directory. See Outputs and saved data for the common files and Example datasets for datasets to try. Preprocessing and rendering large stacks can take time; parallel TIFF rendering is optional and may be slower for small stacks.