Setting keys for TrackMate detectors and trackers

The detectors and trackers in TrackMate are configured via a set of key and values. In the GUI, TrackMate takes care of presenting to the user only the settings relevant to the chosen detector or tracker, but in scripts or other program, they must be known. This document lists all the parameters of all the current known detectors and trackers in TrackMate and shows how to configure them in your scripts and programs.

Configuring a detector and a tracker

First a word of how to specify what detector / tracker to use, and how to configure them programmatically.

In TrackMate, all the parameters of a tracking are specified in a Settings object. This object contains everything, from the source image itself to the filters on tracks. It is made so that when properly set, you can get the final results of tracking and filtering with the following lines:

# imp is the source ImagePlus.
settings = Settings( imp )

# configure settings now...
settings.xyz = abc # etc see below

# Create a TrackMate instance on these settings and run it.
trackmate = TrackMate( settings )
if not trackmate.checkInput():
  print( trackmate.getErrorMessage() )
else:
  if not trackmate.process():
    print( trackmate.getErrorMessage() )
print( 'Done.' )

We restrict ourselves here in showing how to configure the detector and tracker in the Settings object.

The detector factory

The detector to use is determined by setting the field Settings.detectorFactory. The value to enter must be a SpotDetectorFactoryBase. For instance like this (in Python):

settings.detectorFactory = LogDetectorFactory()

As of today (February 2022), the following spot detectors are known:

Built-in detectors

They are all found in the fiji.plugin.trackmate.detection package.

1. LogDetectorFactory
2. DogDetectorFactory
3. MaskDetectorFactory
4. ThresholdDetectorFactory
5. LabelImageDetectorFactory
6. ManualDetectorFactory

Detectors in extensions

1. CellposeDetectorFactory, in the fiji.plugin.trackmate.cellpose package, requires the TrackMate-Cellpose extension.
2. IlastikDetectorFactory, in the fiji.plugin.trackmate.ilastik package, requires the TrackMate-Ilastik extension.
3. MorphoLibJDetectorFactory, in the fiji.plugin.trackmate.morpholibj package, requires the TrackMate-MorphoLibJ extension.
4. StarDistDetectorFactory, in the fiji.plugin.trackmate.stardist package, requires the TrackMate-StarDist extension.
5. StarDistCustomDetectorFactory, as above.
6. WekaDetectorFactory, in the fiji.plugin.trackmate.weka package, requires the TrackMate-Weka extension.

The tracker factory

The tracker to use is determined by setting the field Settings.trackerFactory. The value to enter must be a SpotTrackerFactory. For instance like this (in Python):

settings.trackerFactory = SimpleSparseLAPTrackerFactory()

As of today (February 2022), the following spot trackers are known:

1. SimpleSparseLAPTrackerFactory in the fiji.plugin.trackmate.tracking.sparselap package.
2. SparseLAPTrackerFactory in the same package.
3. KalmanTrackerFactory in the fiji.plugin.trackmate.tracking.kalman package.
4. OverlapTrackerFactory in the fiji.plugin.trackmate.tracking.overlap package.
5. NearestNeighborTrackerFactory in the fiji.plugin.trackmate.tracking.kdtree package.
6. ManualTrackerFactory in the fiji.plugin.trackmate.tracking package.

The settings map or dict

Once you picked a detector factory and a tracker factory, you must input their settings using a Map<String Object> in Java, or a dict in Python. In what follows we suppose we are using a Python script to run TrackMate and will use the syntax of its language.

So, the settings for a detector or a tracker factory are given by a collection of key / value pairs, where the keys are all strings, and the values can be int ,float, boolean or more rarely other objects. They must be stored in a field called detectorSettings for the detector and in a field called trackerSettings for the tracker. For instance, an example settings for the LoGDetectorFactory would be the following:

settings.detectorFactory = LogDetectorFactory()
settings.detectorSettings = {
    'DO_SUBPIXEL_LOCALIZATION' : True,
    'RADIUS' : 2.5,
    'TARGET_CHANNEL' : 1,
    'THRESHOLD' : 0.,
    'DO_MEDIAN_FILTERING' : False,
}

We need to know for each detector and tracker exactly what are the keys they support and what is the type of values they expect. This is the goal of this document.

Key / value definition for the detectors

LoG and DoG detector (LogDetectorFactory and DogDetectorFactory)

These two detectors use a different implementation but relies on the same key / valeus for their settings

The mask detector (MaskDetectorFactory)

The threshold detector (ThresholdDetectorFactory)

The label image detector (LabelImageDetectorFactory)

The manual detector factory (ManualDetectorFactory)

Using this detector will result in the automatic detection step to be skipped.

The cellpose detector (CellposeDetectorFactory)

The ilastik detector (IlastikDetectorFactory)

The MorphoLibJ detector (MorphoLibJDetectorFactory)

The StarDist detector with built-in nuclei model (StarDistDetectorFactory)

The StarDist detector with custom model (StarDistCustomDetectorFactory)

The Weka detector (WekaDetectorFactory)

Key / value definition for the trackers

The simple LAP tracker (SimpleSparseLAPTrackerFactory)

This stripped-down implementation of the LAP tracker from Jaqaman et al, 2008 has many parameters that are described in the next paragraph. For the purpose of this simplified version, it is best to start from the default settings returned by:

settings = fiji.plugin.trackmate.tracking.LAPUtils.getDefaultLAPSettingsMap()

and edit the 3 following important parameters:

The LAP tracker (SparseLAPTrackerFactory)

This tracker is fully configurable with many parameters and feature weights. All parameters are described in the table below. However for practical usage it is best to start from the default settings returned by:

settings = fiji.plugin.trackmate.tracking.LAPUtils.getDefaultLAPSettingsMap()

and edit the parameters that needs to change. For details on their meaning, please refer to the TrackMate documentation and Jaqaman et al, 2008.

The feature penalty map

Feature penalties are a way to alter individual linking cost by using the numerical features computed for all spots. We repeat here how individual costs they are calculated for this tracker.

The user is asked for a maximal allowed linking distance (entered in physical units, via e.g. the LINKING_MAX_DISTANCE parameter), and for a series of spot features, alongside with penalty weights. These parameters are used to tune the cost matrices. For two spots that may link, the linking cost is calculated as follow:

1. The distance between the two spots D is calculated

2. If the spots are separated by more than the max allowed distance, the link is forbidden, and the cost is set to infinity. If not,

3. For each feature in the map, a penalty p is calculated as

   p = 3 × W × |f1−f2| / ( f1+f2 )
   

   where W is the weight associated to the feature in the map. This expression is such that:

   • there is no penalty if the 2 feature values f1 and f2 are the same;
   • with a weight of 1, the penalty is 1 if one feature value is the double of the other;
   • the penalty is 2 if one feature is 5 times the other one.

4. All penalties are summed, to form P = (1 + ∑ p )

5. The cost is set to the square of the product: C = ( D × P )²

If the user feeds no penalty, the costs are simply the distances squared.

The penalties are specified via a dictionary that maps the feature key to the weight W for this feature. For instance to specify a feature penalty for the frame-to-frame linking step on the spot radius with a weight of 2 and on the mean intensity in channel 1 with a weight of 5, create the following dict:

penalty = {
    'RADIUS' : 2.,
    'MEAN_INTENSITY_CH1' : 5.
}

and use it as the value of the LINKING_FEATURE_PENALTIES key. This will penalize linking spots that have very different radii and small difference in the mean intensity.

You must use the keys of the features, not their name. Here is the table of the feature keys and names for the spot features:

The Kalman tracker (KalmanTrackerFactory)

The overlap tracker (OverlapTrackerFactory)

The nearest-neighbor tracker (NearestNeighborTrackerFactory)

The manual tracker (ManualTrackerFactory)

Using this tracker will result in the automatic tracking step to be skipped. It has no parameter.