Data analysis#

While idtracker.ai’s job ends when the trajectory files are validated, users can utilize some external tools and analyses.

idtracker.ai objects inspection#

The internal output files generated by idtracker.ai, located in the session folder, can be manually analyzed for further insights. Refer to the Code reference for a guide to all methods and properties available for these objects.

Below is an example demonstrating how to regenerate trajectories from the ListOfBlobs and extract additional information, such as the Blob area. This example shows how to load the list of blobs, iterate through the frames, and extract the centroid and area of each identified blob:

Example to extract Blob areas and trajectories
import numpy as np

from idtrackerai import ListOfBlobs

list_of_blobs = ListOfBlobs.load(
    "session_folder/preprocessing/list_of_blobs.pickle"
)
n_animals = 8

trajectories = np.full((list_of_blobs.number_of_frames, n_animals, 2), np.nan)
areas = np.full((list_of_blobs.number_of_frames, n_animals), np.nan)

# ListOfBlobs.all_blobs is a flatten view of ListOfBlobs.blobs_in_video
# for blob in blobs.all_blobs:

for blobs_in_frame in list_of_blobs.blobs_in_video:
    for blob in blobs_in_frame:
        blobs_identities = list(blob.final_identities)
        blobs_centroids = list(blob.final_centroids)

        # identity=0 is a null identity, non-identified blob.
        # identity=None means the blob has not been processed by idtracker.ai,
        # this can happen in unfinished sessions

        for identity, centroid in zip(blobs_identities, blobs_centroids):
            if identity not in (None, 0):
                trajectories[blob.frame_number, identity - 1] = centroid

        # extract, for example, the blob area when the blob is an individual
        if blob.is_an_individual and len(blobs_identities) == 1:
            identity = blobs_identities[0]
            if identity not in (None, 0):
                areas[blob.frame_number, identity - 1] = blob.area

                # other properties from the blob
                #   - blob.convexHull  # np.ndarray
                #   - blob.bbox_corners  # tuple[tuple[int, int], tuple[int, int]]
                #   - blob.extension  # float
                #   - blob.centroid  # tuple[float, float]
                #   - blob.orientation  # float

Cluster inspection#

After a successful tracking session with version 6 or higher, the clusters of the embedded images can be inspected via the command idtrackerai_inspect_clusters.

Data policy

idtrackerai_inspect_clusters works with sessions tracked with data policy idmatcher.ai or all.

This uses the trained contrastive network (ResNet) to compute and store the image embeddings in a CSV file. It then generates a scatter plot of their t-SNE representation, enabling visual inspection of the resulting clusters. The results are saved in “session_folder/cluster_inspection”.

Predicted identities stored in the session’s ListOfFragments are used to color the scatter plot (predicted_t-SNE.png) and populate the predicted_id column in the CSV file. Groundtruth identities can be added by providing a path to a validated trajectory file with the argument --gt_path (see below), this generates an additional scatter plot with these identities (groundtruth_t-SNE.png) and populates the groundtruth_id column.

t-SNE example on zebrafish_8 t-SNE example on drosophila_80

Examples of t-SNE visualizations of image embeddings using the videos test_B.avi from Test the installation (left) and drosophila_80 from the data repository (right).

By running idtrackerai_inspect_clusters -h, a list of all available options is displayed:

--images_per_id

Sets the maximum number of images per animal to sample for speeding up t-SNE computation. The default value is 500. To disable subsampling, set this option to ‘inf’. Note that subsampling is performed randomly across all identities, so the exact number of images per class may vary.

--gt_path

Specifies the path to the ground truth trajectories used to compare image centroids and extract their ground truth identities. These identities are used to assign colors in the groundtruth scatter plot and populate the groundtruth_id column in the CSV output. The path can point to a trajectory file or a session folder.

Trajectorytools#

A Python package that performs basic trajectory analysis and it is available at polavieja_lab/trajectorytools.

You can find some analysis routines from [1] implemented with trajectorytools in polavieja_lab/idtrackerai_notebooks. Here we present some of the analysis we get using a 10 juvenile fish video:

Plot of the trajectories of zebrafish tracked with idtracker.ai Neighbors density plot of zebrafish tracked with idtracker.ai

Smoothed trajectories (left) and density of neighbors around a focal fish (right)

../_images/velocity_and_acceleration.png

Velocities and accelerations#

../_images/polar_plots.png

Polar distributions of positions, turnings and accelerations#

../_images/distances_vs_random.png

Inter-individual distance histograms compared with shuffled trajectories#

Fish Midline#

A short Python script available at polavieja_lab/midline to extract posture information of animals tracked with idtracker.ai. Intended to be used with fish data but easily customizable and adaptable.

https://gitlab.com/polavieja_lab/midline/-/raw/master/example.gif

Example of posture information extracted with Fish Midline.#

References