Output structure#

Each tracking session creates a session_[SESSION_NAME] folder next to the input videos, or inside output_dir if you set it (see Output).

Contents of an idtracker.ai session folder#
session_[SESSION_NAME]
├─ accumulation
│  ├─ identifier_[cnn, contrastive].model.pt
│  └─ model_params.json
├─ crossings_detector
│  ├─ crossing_detector.model.pt
│  └─ model_params.json
├─ bounding_box_images
│  └─ bbox_images_*.h5
├─ identification_images
│  └─ id_images_*.h5
├─ preprocessing
│  ├─ background.png
│  ├─ list_of_blobs.pickle
│  ├─ list_of_fragments.json
│  ├─ list_of_global_fragments.json
│  └─ ROI_mask.png
├─ session.json
├─ idtrackerai.log
└─ trajectories
   ├─ trajectories_csv
   │  ├─ areas.csv
   │  ├─ attributes.json
   │  ├─ id_probabilities.csv
   │  └─ trajectories.csv
   ├─ trajectories.h5
   ├─ trajectories.npy
   ├─ ...
   └─ trajectories.parquet

The highlighted trajectories folder holds the main result: the position of every animal in every frame (see Trajectory files). The Validator overwrites these files when you save your corrections.

The other files are mostly by-products of the tracking pipeline, and you will rarely need them:

  • accumulation: the trained identification network. idmatcher.ai, Knowledge transfer and Cluster inspection use it.

  • crossings_detector: the trained network that tells single animals apart from crossings.

  • bounding_box_images: intermediate image crops used to build the identification images.

  • identification_images: one identification image per animal and frame, in HDF5 format.

  • preprocessing: the ListOfBlobs, ListOfFragments and ListOfGlobalFragments objects, plus the background and ROI mask images. Advanced users can load these objects for extra details about the tracking (see Data analysis).

  • session.json: the session parameters and video properties, in human-readable JSON.

  • idtrackerai.log: a copy of the Tracking log, saved at the end of the session whether it succeeded or not. Send it to us when you ask for help.

Trajectory files#

The trajectory files in the trajectories folder are the files you will use most. They are saved in the formats listed in trajectories_formats (see Output).

Load trajectories in Python#

The simplest way to read them in Python, whatever the format, is idtrackerai.utils.load_trajectories():

from idtrackerai.utils import load_trajectories

data = load_trajectories("session_test")  # a session folder or a trajectory file
trajectories = data["trajectories"]  # shape (N_frames, N_animals, 2)

To read them without idtracker.ai, or from another language, see the Formats below.

Content#

Every format stores the same dictionary-like data:

trajectories

Array of shape (N_frames, N_animals, 2) with the x and y position, in pixels, of each animal in each frame. Missing positions are NaN.

id_probabilities

Array of shape (N_frames, N_animals, 1) with the probability, between 0 and 1, that the identity assigned to each animal in each frame is correct. It is 0 when the animal was not located in that frame.

estimated_accuracy

Estimated accuracy of the identification over the whole session.

fraction_identified

Fraction of the entries of trajectories that hold a valid (non-NaN) position. 1.0 means that every animal was located in every frame.

version

idtracker.ai version that created the file.

video_paths, height, width, frames_per_second

Paths, frame size in pixels, and frame rate of the input video.

body_length

Median body length of the animals in pixels, measured as the diagonal of the bounding boxes of single-animal blobs.

Warning

body_length is not a reliable measure of the real size of the animals. It depends on the segmentation parameters and the video conditions.

areas

Mean, median and standard deviation of the blob area of each animal.

identities_labels, identities_groups, setup_points

Identity names, groups of identities and setup points defined in the Validator.

length_unit

Ratio between pixel distances and the real distances given in the Length calibration tool of the validator.

silhouette_score

Mean silhouette score of a random sample of images at the end of contrastive training (see the contrastive parameters in Advanced parameters).

fragment_connectivity

How connected the fragments used for contrastive training are: the mean number of fragments that coexist with each fragment, divided by the number of animals minus one.

Formats#

Format

Parameter value

Files

Best for

HDF5

h5

trajectories.h5

Sharing; readable from most languages

NumPy

npy

trajectories.npy

Legacy Python scripts

Pickle

pickle

trajectories.pickle

Python only

CSV and JSON

csv

trajectories_csv/ folder

Spreadsheets and quick inspection

Tidy CSV

csv_tidy

trajectories_tidy.csv, attributes_tidy.json

R, pandas and other tools that expect tidy data

Parquet

parquet

trajectories.parquet

Large datasets; pandas, R, Polars, Spark

Tip

To convert the trajectories of an already tracked session to other formats, run:

idtrackerai_format path/to/session_test --formats h5 npy csv csv_tidy pickle parquet

HDF5#

The Hierarchical Data Format from the HDF Group. A binary, cross-platform format that is becoming a standard in neuroscience and can be read from most languages. In Python, it requires h5py, which is installed with idtracker.ai.

import h5py

with h5py.File("session_test/trajectories/trajectories.h5") as file:
    print(file.keys())  # list all datasets and groups
    trajectories = file["trajectories"][:]  # load trajectories as a NumPy array
    attributes = dict(file.attrs)  # scalar values are stored as attributes

NumPy#

A dictionary saved with np.save() (see NumPy’s binary format). It can only be read from Python and is kept for compatibility with older scripts.

Warning

Loading this file uses Python’s pickle module, which can run arbitrary code. Only load files you trust, and prefer other formats to share data (see the pickle documentation).

import numpy as np

data = np.load("session_test/trajectories/trajectories.npy", allow_pickle=True).item()

Pickle#

A dictionary saved with Python’s pickle module. It can only be read from Python, and the same security warning as for NumPy applies.

import pickle

with open("session_test/trajectories/trajectories.pickle", "rb") as file:
    data = pickle.load(file)

CSV and JSON#

A trajectories_csv folder with human-readable text files that open in any spreadsheet program:

  • trajectories.csv: one row per frame, with columns time, x1, y1, x2, y2, ....

  • id_probabilities.csv: one row per frame, with columns time, id_probabilities1, id_probabilities2, ....

  • areas.csv: the mean, median and standard deviation of the area of each animal.

  • attributes.json: the rest of the data.

Values are rounded, so some precision is lost.

import json
import numpy as np

with open("session_test/trajectories/trajectories_csv/attributes.json") as file:
    attributes = json.load(file)

# skip the header (first row) and the time column (first column)
trajectories = np.loadtxt(
    "session_test/trajectories/trajectories_csv/trajectories.csv",
    skiprows=1,
    delimiter=",",
)[:, 1:]
trajectories = trajectories.reshape(len(trajectories), -1, 2)

Tidy CSV#

A single human-readable file in long (tidy) layout, with one row per frame and animal. This is the layout that R, pandas and most statistics tools expect. Values are rounded, so some precision is lost.

trajectories_tidy.csv has the columns frame, time, individual, x, y and probability. The rest of the data is stored in attributes_tidy.json.

import json
import pandas as pd

with open("session_test/trajectories/attributes_tidy.json") as file:
    attributes = json.load(file)

# DataFrame with columns: frame, time, individual, x, y, probability
df = pd.read_csv("session_test/trajectories/trajectories_tidy.csv")

# Back to wide format (frames × individuals), if needed
x = df.pivot(index="frame", columns="individual", values="x").to_numpy()
y = df.pivot(index="frame", columns="individual", values="y").to_numpy()
Without pandas
import numpy as np

data = np.loadtxt(
    "session_test/trajectories/trajectories_tidy.csv", delimiter=",", skiprows=1
)
n_frames = int(data[:, 0].max()) + 1
n_animals = int(data[:, 2].max()) + 1
trajectories = data[:, 3:5].reshape(n_frames, n_animals, 2)

Parquet#

Apache Parquet, a binary, columnar, cross-platform format designed for large datasets. The table has the same tidy layout as the Tidy CSV, and the rest of the data is stored as JSON in the table metadata. In Python, it requires pandas and pyarrow (pip install pandas pyarrow).

import json
import pyarrow.parquet

table = pyarrow.parquet.read_table("session_test/trajectories/trajectories.parquet")

# DataFrame with columns: frame, time, individual, x, y, probability
df = table.to_pandas()

attributes = json.loads(table.schema.metadata[b"idtrackerai_attributes"])