Quick start

This is a quick start example of how to use the STracking library. This section supposes you to know the principles of particles tracking. If it is not the case, please refer to the Guide.

Input images

Input images are 2D+t or 3D+t gray scaled images. 2D+t images are represented as numpy arrays with the following columns ordering [T, Y, X] and 3D+t images are represented with numpy array with [T, Z, Y, X] columns ordering

First we load the images:

from stracking import data

image = data.fake_tracks1()

Particles detections

The first step of particle tracking is to detect individual particles frame by frame. STracking provides SDetector interface for particles detector. In this example we detect particles with the Difference of Gaussians detector:

from stracking.detectors import DoGDetector

detector = DoGDetector(min_sigma=4, max_sigma=5, threshold=0.2)
particles = detector.run(image)

The output `articles is an instance of the SParticles container. It contains the list of particles as a numpy array, the properties of the particles as a dict and the image scale as a tuple

Particles linking

The second step is linking the particles to create tracks. STracking provides SLinker interface to implement mulitple linking algorithms. In this quick start, we use the Shorted path graph based linker, using the Euclidean distance between particles as a link cost function:

from stracking.linkers import SPLinker, EuclideanCost

euclidean_cost = EuclideanCost(max_cost=3000)
my_tracker = SPLinker(cost=euclidean_cost, gap=1)
tracks = my_tracker.run(particles)

The output tracks in an instance of the STracks container. It contains the list of tracks as a numpy array and all the tracks metadata in dictionaries.

The next steps show the usage of SProperty, SFeature and SFilter to analyse the trajectories

Particles properties

The tracks properties module allows to calculate properties of the particles. This quickstart example shows how to calculate the intensity properties of particles:

from stracking.properties import IntensityProperty

property_calc = IntensityProperty(radius=2)
property_calc.run(particles, image)

All the calculated properties are saved in the properties attribute of the SParticles container.

Tracks features

The tracks features module allows to calculate features of tracks like length and distance. This quickstart example shows how to calculate the distance of tracks:

from stracking.features import DistanceFeature

feature_calc = DistanceFeature()
feature_calc.run(tracks)

The calculated features are stored in the features attribute of the STracks container.

Tracks filter

The last part is the filter module. It allows to extract a subset of tracks base on a defined criterion. In this example, we select the tracks that move less that a distance of 60 pixels:

from stracking.filters import FeatureFilter

filter = FeatureFilter(feature_name='distance', min_val=0, max_val=60)
filtered_tracks = filter.run(tracks)

Filtered set of tracks are return as a STracks object.