Icy EMHT

Wrapper around Spot Tracking protocol of ICY.

class byotrack.implementation.linker.icy_emht.icy_emht.Motion(value)

Bases: Enum

Different motion models:

BROWNIAN
Random gaussian displacement at each time
DIRECTED
Random gaussian noise around a directed trajectory
MULTI
Uses both models and switches between them

class byotrack.implementation.linker.icy_emht.icy_emht.EMHTParameters(detecions_fpr: float = 0.1, detecions_fnr: float = 0.1, expected_track_length: int = -1, expected_initial_particles: int = -1, expected_new_particles: int = 10, existence_prob: float = 0.5, termination_prob: float = 0.0001, motion: Motion = Motion.BROWNIAN, use_most_likely_model: bool = True, update_motion_1: bool = False, update_motion_2: bool = False, xy_std_1: float = 3.0, z_std_1: float = 3.0, xy_std_2: float = 3.0, z_std_2: float = 3.0, inertia: float = 0.8, gate_factor: float = 4.0, tree_depth: int = 4)

Bases: object

Parameters of EMHT algorithm [4]

Some parameters are still not very clear to us, but we describe them to the best of our knowledge.

detections_fpr

Estimation of the false positive rate of the detection process Default: 0.1

Type:: float

detections_fnr

Estimation of the false negative rate of the detection process Default: 0.1

Type:: float

expected_track_length

Expected length of tracks. If negative, it defaults to the sequence size Default: -1

Type:: int

expected_initial_particles

Estimation of the number of particles in the first frames. If negative, it defaults to the average number of detections by frame in the sequence Default: -1

Type:: int

expected_new_particles

Estimation of the number of new particle by frame Default: 0

Type:: int

existence_prob

Minimum probability to confirm a track existence Default: 0.5

Type:: float

termination_prob

Minimum probability before terminating a track Default: 1e-4

Type:: float

motion

Motion of the particles (Brownian vs Directed vs Multi). If MULTI, motion 1 is brownian and motion 2 is directed. Default: Motion.BROWNIAN

Type:: Motion

use_most_likely_model

Use the most likely model to predict rather than a weighted predictions Default: True

Type:: bool

update_motion_{1, 2}

Update the covariance (Q ?) online of motion 1 or 2

Type:: bool

xy_std_{1,2}

Used to define the covariance (Q) of the process. (Looking at Icy code, it is not clear what they truly are, depending on the motion the covariance Q is set a bit weirdly) Default: 3.0

Type:: float

z_std_{1,2}

Same as xy_std but for the 3d axes (if any) Default: 3.0

Type:: float

inertia

Probability to not switch of motion model (For MULTI motion) Default: 0.8

Type:: float

gate_factor

Max mahalanobis distance for potential association Default: 4.0

Type:: float

tree_depth

Number of frames to consider in the search tree Default: 4

Type:: int

to_xml(detections_sequence: Sequence[Detections]) → ElementTree

Convert to xml format used by Icy

Format example:

<root>
    <MHTconfiguration>
        <detectionInput detectionRate="0.9" detectionSource="noSource" numberFalseDetection="20"/>
        <targetExistence confirmationThreshold="0.5" terminationThreshold="1.0E-4" trackLength="200"/>
        <motionModel IMMinertia="0.8" isDirectedMotion_1="true" isDirectedMotion_2="true"
            isMostLikelyModel="true" isSingleMotion="false" updateCovariance_2="false" updateMotion_1="true"
            yxDisplacement_1="2" yxDisplacement_2="3" zDisplacement_1="2" zDisplacement_2="3"/>
        <mht gateFactor="4" mhtDepth="4" numberNewObjects="10" numberObjectsFirstFrame="50"/>
        <ouput trackGroupName="mht-tracks-1"/>
    </MHTconfiguration>
</root>

Parameters:: detections_sequence (Sequence[byotrack.Detections]) – Detections (Required to set default values for some parameters)
Returns:: Xml tree of the configuration
Return type:: xml.etree.ElementTree.ElementTree

class byotrack.implementation.linker.icy_emht.icy_emht.IcyEMHTLinker(icy_path: str | PathLike | None = None, full_specs: EMHTParameters | None = None, timeout: float | None = None)

Bases: Linker

Run EMHT [4] from Icy [1]

It is a wrapper around Icy’s tracking code. It supports 2D and 3D data.

About EMHT: It is a probabilistic tracking that uses statistical motion model on particles. It uses multiple kalman filters for each particle allowing a particle to have several mode of motions. It also keeps multiple hypothesis of tracking at each frame so that a final detections linking decision is made after seeing several frames in the past and future of these detections.

Here we rely on the handmade protocol “emht_protocol” that expects detections as a valid rois file for icy and some hyperparameters.

The workflow is:

Detections to rois in Icy format
Run the Icy protocol
[In ICY] Read rois, estimate or load emht parameters, run emht, export tracks to xml
Read Icy tracks and return

Note

This implementation requires Icy to be installed (https://icy.bioimageanalysis.org/download/) You should also install the Spot Tracking Blocks plugin (https://icy.bioimageanalysis.org/tutorial/how-to-install-an-icy-plugin/)

runner

Icy runner

Type:: byotrack.icy.IcyRunner

motion

Prior on the underlying motion model (Brownian vs Directed vs Both) Given to the Icy block that estimates EMHT parameters. (See full_specs and EMHTParameters to have a finegrained control over the algorithm parameters) Default: Motion.BROWNIAN

Type:: Motion

full_specs

Full specification of the algorithm. If not provided, we use the estimation of EMHT parameters provided by Icy (with motion the only parameter to set).

Type:: Optional[EMHTParameters]

run(video, detections_sequence: Sequence[Detections]) → List[Track]

Run the linker on a whole video

Parameters:

video (Sequence[np.ndarray] | np.ndarray) – Sequence of T frames (array). Each array is expected to have a shape ([D, ]H, W, C)
detections_sequence (Sequence[byotrack.Detections]) – Detections for each frame Detections is expected for each frame of the video, in the same order. (Note that for a given frame, the Detections can be empty)

Returns:

Tracks of particles

Return type:

Collection[byotrack.Track]