BayesianTracker

class btrack.BayesianTracker(verbose: bool = True)

Bases: object

BayesianTracker.

BayesianTracker is a multi object tracking algorithm, specifically used to reconstruct tracks in crowded fields. Here we use a probabilistic network of information to perform the trajectory linking. This class is a wrapper for the C++ implementation of the BayesianTracker.

Parameters:

verbosebool: A flag to set the verbosity level while logging the output.

Attributes:

n_tracksint: Return the number of tracks found.
n_dummiesint: Return the number of dummy objects (negative ID).
trackslist: Return a sorted list of tracks, default is to sort by increasing length.
refslist: Return tracks as a list of IDs (essentially pointers) to the original objects.
dummieslist: Return a list of dummy objects.
volumetuple: The imaging volume as [(xlo, xhi), …, (zlo, zhi)]. See btrack.btypes.ImagingVolume() for more details.
frame_rangetuple: Return the frame range.
LBEPlist[List]: Return an LBEP list describing the track lineage information.
configurationconfig.TrackerConfig: Get the current configuration.

Notes

This method uses positional information (position, velocity …) as well as visual information (labels, features…) for track linking.

The tracking algorithm assembles reliable sections of track that do not contain splitting events (tracklets). Each new tracklet initiates a probabilistic model in the form of a Kalman filter [1], and utilises this to predict future states (and error in states) of each of the objects in the field of view. We assign new observations to the growing tracklets (linking) by evaluating the posterior probability of each potential linkage from a Bayesian belief matrix for all possible linkages [2]. The best linkages are those with the highest posterior probability.

Data can be passed in in the following formats:

numpy arrays

btrack.btypes.PyTrackObject

CSV (see btrack.io.import_CSV())

HDF (see btrack.io.HDF5FileHandler)

The tracker can be used to return all of the original data neatly packaged into tracklet objects, or as a nested list of references to the original data sets. The latter is useful if using only the first part of a tracking protocol, or other metadata is needed for further analysis. The references can be used to make symbolic links in HDF5 files, for example. Use optimise to generate hypotheses for global optimisation [3] [4]. Read the optimiser.TrackOptimiser documentation for more information about the track linker.

Full details of the implementation can be found in [5] and [6].

References

[1]

‘A new approach to linear filtering and prediction problems.’ Kalman RE, 1960 Journal of Basic Engineering

[2]

‘A Bayesian algorithm for tracking multiple moving objects in outdoor surveillance video’, Narayana M and Haverkamp D 2007 IEEE

[3]

‘Report Automated Cell Lineage Construction’ Al-Kofahi et al. Cell Cycle 2006 vol. 5 (3) pp. 327-335

[4]

‘Reliable cell tracking by global data association’, Bise et al. 2011 IEEE Symposium on Biomedical Imaging pp. 1004-1010

[5]

‘Local cellular neighbourhood controls proliferation in cell competition’, Bove A, Gradeci D, Fujita Y, Banerjee S, Charras G and Lowe AR 2017 Mol. Biol. Cell vol 28 pp. 3215-3228

[6]

‘Automated deep lineage tree analysis using a Bayesian single cell tracking approach’, Ulicna K, Vallardi G, Charras G and Lowe AR 2021 Front. Comput. Sci. 3

Examples

Can be used with ContextManager support, like this:

>>> with BayesianTracker() as tracker:
>>>    tracker.configure("./models/cell_config.json")
>>>    tracker.append(observations)
>>>    tracker.track()
>>>    tracks = tracker.tracks

Attributes Summary

`LBEP`	Return an LBEP list describing the track lineage information.
`configuration`	Get the current configuration.
`dummies`	Return a list of dummy objects.
`frame_range`	Return the frame range.
`n_dummies`	Return the number of dummy objects (negative ID).
`n_tracks`	Return the number of tracks found.
`objects`	Return the list of objects added through the append method.
`refs`	Return tracks as a list of IDs (essentially pointers) to the original objects.
`tracks`	Return a sorted list of tracks, default is to sort by increasing length.

Methods Summary

`append`(objects)	Append a single track object, or list of objects to the stack.
`candidate_graph_edges`()	Return the edges from the full candidate graph.
`configure`(configuration)	Configure the tracker with a motion model, an object model and hypothesis generation_parameters.
`configure_from_file`(filename)	Configure the tracker from a configuration file.
`export`(filename[, obj_type, filter_by])	Export tracks using the appropriate exporter.
`hypotheses`()	Calculate and return hypotheses using the hypothesis engine.
`optimise`([options])	Optimize the tracks.
`optimize`(**kwargs)	Proxy for optimise for our American friends ;)
`step`([n_steps])	Run an iteration (or more) of the tracking.
`to_napari`([replace_nan, ndim])	Return the data in a format for a napari tracks layer.
`track`(*[, step_size, tracking_updates])	Run the tracking in an interactive mode.
`track_interactive`(args, *kwargs)

Attributes Documentation

LBEP

Return an LBEP list describing the track lineage information.

Notes

LBEP table layout
Index	Description
L	A unique label of the track (label of markers, 16-bit positive).
B	A zero-based temporal index of the frame in which the track begins.
E	A zero-based temporal index of the frame in which the track ends.
P	Label of the parent track (0 is used when no parent is defined).
R	Label of the root track.
G	Generational depth (from root).

configuration: Get the current configuration.

dummies: Return a list of dummy objects.

frame_range: Return the frame range.

n_dummies: Return the number of dummy objects (negative ID).

n_tracks: Return the number of tracks found.

objects: Return the list of objects added through the append method.

refs: Return tracks as a list of IDs (essentially pointers) to the original objects. Use this to write out HDF5 tracks.

tracks: Return a sorted list of tracks, default is to sort by increasing length.

Methods Documentation

append(objects: list[PyTrackObject] | ndarray[Any, dtype[_ScalarType_co]]) → None

Append a single track object, or list of objects to the stack. Note that the tracker will automatically order these by frame number, so the order here does not matter. This means several datasets can be concatenated easily, by running this a few times.

Parameters:

objectslist, npt.NDArray: A list of objects to track.

candidate_graph_edges() → list[PyGraphEdge]: Return the edges from the full candidate graph.

configure(configuration: dict | PathLike | TrackerConfig) → None

Configure the tracker with a motion model, an object model and hypothesis generation_parameters.

Parameters:

configuration: A dictionary containing the configuration options for a tracking session.

configure_from_file(filename: PathLike) → None: Configure the tracker from a configuration file. See configure.

export(filename: PathLike, obj_type: str | None = None, filter_by: str | None = None) → None

Export tracks using the appropriate exporter.

Parameters:

filenamestr: The filename to export the data. The extension (e.g. .h5) is used to select the correct export function.
obj_typestr, optional: The object type to export the data. Usually obj_type_1
filter_bystr, optional: A string that represents how the data has been filtered prior to tracking, e.g. using the object property area>100

hypotheses() → list[Hypothesis]: Calculate and return hypotheses using the hypothesis engine.

optimise(options: dict | None = None) → list[Hypothesis]

Optimize the tracks.

Parameters:

optionsdict: A set of options to be used by GLPK during convex optimization.

Returns:

optimizedlist: The list of hypotheses which represents the optimal solution.

Notes

This generates the hypotheses for track merges, branching etc, runs the optimiser and then performs track merging, removal of track fragments, renumbering and assignment of branches.

optimize(**kwargs): Proxy for optimise for our American friends ;)

step(n_steps: int = 1) → PyTrackingInfo | None: Run an iteration (or more) of the tracking. Mostly for interactive mode tracking.

to_napari(replace_nan: bool = True, ndim: int | None = None) → tuple[ndarray[Any, dtype[_ScalarType_co]], dict, dict]: Return the data in a format for a napari tracks layer. See btrack.utils.tracks_to_napari().

track(*, step_size: int = 100, tracking_updates: list[str | BayesianUpdateFeatures] | None = None) → None

Run the tracking in an interactive mode.

Parameters:

step_sizeint, default=100: The number of tracking steps to be taken before returning summary statistics. The tracking will be followed to completion, regardless of the step size provided.
tracking_updateslist, optional: A list of tracking updates to perform. See btrack.btypes.BayesianUpdateFeatures for details.

track_interactive(*args, **kwargs) → None