Using the napari plugin¶
The Track Analyzer dock widget loads and filters tracks, runs analyses, and displays previews alongside images in napari. Install it as described in Installation, start napari, and select Plugins > Track Analyzer. The widget has five tabs: Load data, Filtering, Trajectory analysis, Map analysis, and Comparator.
The Load data tab. The path shown is an example.¶
Inputs¶
Use a CSV or TXT table containing track IDs, frame numbers, X and Y coordinates, and optionally Z coordinates and custom variables. Coordinates may be in pixels or scaled units. The plugin maps source columns to Track Analyzer’s column names. For TrackMate data, export the spots table.
An image is optional. Open it in napari before using image-based previews or backgrounds; there is no general image loader in the plugin. For exported backgrounds, the open grayscale image must have a saved source file, or the layer name must match a file in the dataset directory.
Load data and metadata¶
In Load data, choose one of the following:
Load table: select a new table, set the column separator, header-row option, and TrackMate CSV option, then click Import table. To change the parsing options, edit them and import again. Expand Inspect and link columns. Assign
x,y,frame, andtrack; assignzand named custom variables if needed. Choose how to resolve trajectory gaps and click Apply mapping. TrackMate column assignments are proposed automatically when the TrackMate option is enabled.Load existing database: select an existing
data_base.p. Its processed table is loaded directly, so column mapping is not needed.
The selected table or database’s parent folder is used for metadata and outputs. File dialogs initially open in the user’s home directory, unless an open image has a source path.
Clear loaded data removes the current dataset, its filters and plugin-generated previews, but keeps image layers and comparator datasets. It does not delete files. Wait for any running trajectory or map analysis or grid computation to finish before clearing.
In Input metadata, enter or load the pixel size, frame interval, units, image dimensions, and optional Z step. Use Save info.txt to save metadata in the dataset directory; replacing an existing file requires confirmation.
Before saving a new database, optionally set preprocessing coordinates in
Custom origin and axis orientation. Use Pick origin in viewer to
choose an origin on an open image. These settings affect preprocessing;
displayed tracks retain their source coordinates. Then click Save database
to preprocess trajectories and write data_base.p. Saving over an existing
database requires confirmation. Trajectory and map analyses require a
processed database and saved info.txt.
Plotting configuration controls figure size, resolution, format, stack export, data-point export, and custom colors. Enable Render TIFF stacks in parallel to render trajectory, Voronoi, scalar, and vector TIFF stacks using up to four worker processes. This shared option is off by default and does not affect individual-image exports. Worker startup and data transfer can make parallel rendering slower for small stacks.
Filtering¶
In Filtering, set the number of named subsets and choose whether to analyze them separately or together. Expand Define analysis subsets to set each subset’s color, position ranges, frame window, and track-length limits. Draw ROI sets the X/Y ranges using a rectangle drawn in the viewer. If no image is open, it uses displayed tracks or shows a 2D X/Y projection of the loaded tracks for reference.
Optionally add track-selection sets under Select tracks within each subset. Each set can select track IDs, tracks entering a position ROI within a frame window, or both, and is applied within every analysis subset. Use Draw track ROI to define a selection ROI in the viewer. Set the two frame-window endpoints to the same value to select at a single frame.
Click Apply filters to apply the selections; a successfully applied ROI
drawing layer is hidden, but its coordinate ranges are retained. Display
tracks shows the filtered tracks using the selected colors. Save filters
writes config/filters.csv; Remove all subsets clears subset and
track-selection controls.
Trajectory analysis¶
The trajectory tab offers Trajectories on movie, Total trajectories, Parameter plots, Mean squared displacement (MSD), and Voronoi analysis. Each foldout has an independent On/Off switch: opening or closing it does not change whether that analysis runs. Add histogram, boxplot, or scatter-plot rows for instantaneous or whole-track parameters as needed.
Expand a foldout to edit its settings; its switch controls whether it runs.¶
The track color code and colormap at the top are shared by Preview colored
tracks and the trajectory exports. The group color code uses the
filtering subset colors, or the track-selection set colors when those sets
are present.
In Voronoi analysis, Preview Voronoi displays a 2D tessellation for the current filters and frame. The outline color is editable; enabling Show cell area adds a separate area-colored layer. The area threshold, length scale, colormap, and color limits determine the fill. Unbounded and excluded cells are not filled. The preview supports 2D images and 2D time-lapse images; it follows the current frame and is computed per subset in separate mode. Area and color settings update an existing preview automatically; run it again after changing data or filters.
Click Run trajectory analysis to save results in numbered folders under
<dataset>/traj_analysis/. Subsets must have unique names and contain data.
The progress bar indicates work is ongoing rather than a percentage; the log
shows analysis messages. A notification and a log message indicate when the
analysis completes.
Map analysis¶
Maps average quantities on a regular 2D grid. In Define grid, select the number of X cells and grid origin, then click Preview grid. Changing these settings updates a visible grid preview. The grid uses the open image dimensions, or filtered track extents if no image is open.
Set temporal averaging, relative arrow size, frame increment, and export options under Map parameters. In Fields to plot, add scalar fields, vector fields, or vector means and remove any unwanted rows. Vector fields can have a scalar background.
Compute grid values calculates all available fields and displays finite ranges for the selected fields across frames and subsets. Use the two-handle slider to select color limits within the computed range. For a constant range the slider is disabled; select Enter custom limits to type limits instead, including values outside the computed range. Custom limits may also be entered before computing grid values. Changing the data, filters, grid, image geometry, or temporal average invalidates the computed values. Run the computation again after such changes. A subsequent map analysis reuses current computed values; if none are available, analysis computes them as usual.
Show selected maps in viewer creates scalar image layers and vector arrow
layers. Missing scalar values are transparent. Scalar colors and limits are
set in the widget; click the display button again after changing them.
Relative arrow size updates existing preview arrows immediately.
Run map analysis saves plots and optional field exports under
<dataset>/map_analysis/. A notification and a log message indicate when
the analysis completes.
Comparator¶
The comparator pools or compares previously saved trajectory analyses, even when they come from different dataset roots. All selected datasets must use the same length and time units: unit conversion is not supported.
Expand Datasets and choose a dataset root. Select an individual folder under Trajectory analysis and click Add selected analysis. Repeat for other analyses or roots. Use Refresh analyses after generating new analyses, or browse directly to an analysis folder.
Give the selected datasets unique names and choose
compare(separate colors) orpool(one group).Add instantaneous or whole-trajectory histograms, boxplots, or scatter plots. Parameter choices are numerical fields shared by all datasets and supported by the plotting engine.
Optionally turn on the Mean squared displacement (MSD) foldout switch; it is off by default. MSD comparison requires a nonempty
all_MSD.csvfor each selected analysis. Parameter plots useall_data.csvandmean_track_data.csv.Click Run comparison. Results are saved under
<first dataset>/pooled_datasets/<mode>_<dataset names>/. If the output folder exists, choose Overwrite, Create new folder, or Cancel. Overwrite replaces matching files but retains unrelated files in the folder.
The comparator runs in a separate process and displays progress and output messages in the widget. A notification and a log message indicate when the comparison completes.
Synthetic datasets¶
Open Plugins > Track Analyzer > Synthetic Dataset Generator as a separate dock widget. Choose an existing output directory and set the track and frame counts, dimensionality, frame interval, pixel size, space bounds, and initial-position bounds. Initial positions can be random or, in 2D, arranged on an approximate grid; grid spacing can change the actual track count. Periodic boundaries wrap positions into the configured space bounds. For 3D, select random initial positions.
The separate synthetic dataset generator.¶
Set the diffusion and velocity polynomials using the coefficients shown in the widget; powers must be non-negative. Diffusion must be finite and non-negative at initial positions and at each position where a step is computed. Positions and coefficients use the script’s physical units (micrometers and seconds): diffusion is in µm²/s and velocity in µm/s.
Velocity coefficients are normalized by the corresponding space size by
default: each term is coefficient * ((position - center) / size) ** power.
For example, to make X velocity increase linearly from 0 to 2 µm/s across X,
set its X coefficient to 2, its center to the X minimum, and its power to 1;
set the constant and other terms to zero. Choose Physical coefficients
to use the original unnormalized polynomial instead. Switching modes
reinterprets the entered values; it does not convert them. The saved
config.csv always contains the equivalent physical coefficients for the
command-line script.
Setting a linear X velocity gradient from 0 to 2 µm/s when the X space minimum is 0. Other velocity terms are set to zero.¶
The synthetic TIFF export is enabled by default and writes stack.tiff.
It is an XY projection even for 3D data. Its parallel rendering option is
independent of the main analysis widget. Viewer tracks use
the physical coordinates saved in positions.csv; TIFF coordinates are
pixels relative to the space minima.
Click Generate synthetic dataset. The process confirms before replacing
existing output files, saves its configuration and results, and displays the
generated tracks in the viewer. Generation does not automatically load those
tracks as an analysis database: use Load table, select positions.csv,
apply the column mapping, and save a database to analyze them. Files not
selected for export, such as an existing TIFF when TIFF export is off, are
left unchanged.
napari troubleshooting¶
If the plugin is missing from napari, check that napari and Track Analyzer are installed in the same environment, as described in Installation.
If analysis cannot start, check the status and log, confirm
info.txtanddata_base.pare available, and remove or adjust empty subsets.If an exported background cannot be found, save the image to a file or hide the background in the analysis settings.
If map colors are unavailable, compute grid values and select a field with finite values. After changing grid inputs, recompute them.
If comparator fields are unavailable, check that the corresponding analysis tables exist and contain the selected numerical parameter in every dataset.