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).
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: theListOfBlobs,ListOfFragmentsandListOfGlobalFragmentsobjects, 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:
trajectoriesArray 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_probabilitiesArray 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_accuracyEstimated accuracy of the identification over the whole session.
fraction_identifiedFraction of the entries of
trajectoriesthat hold a valid (non-NaN) position. 1.0 means that every animal was located in every frame.versionidtracker.ai version that created the file.
video_paths,height,width,frames_per_secondPaths, frame size in pixels, and frame rate of the input video.
body_lengthMedian body length of the animals in pixels, measured as the diagonal of the bounding boxes of single-animal blobs.
Warning
body_lengthis not a reliable measure of the real size of the animals. It depends on the segmentation parameters and the video conditions.areasMean, median and standard deviation of the blob area of each animal.
identities_labels,identities_groups,setup_pointsIdentity names, groups of identities and setup points defined in the Validator.
length_unitRatio between pixel distances and the real distances given in the Length calibration tool of the validator.
silhouette_scoreMean silhouette score of a random sample of images at the end of contrastive training (see the contrastive parameters in Advanced parameters).
fragment_connectivityHow 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 |
|---|---|---|---|
|
|
Sharing; readable from most languages |
|
|
|
Legacy Python scripts |
|
|
|
Python only |
|
|
|
Spreadsheets and quick inspection |
|
|
|
R, pandas and other tools that expect tidy data |
|
|
|
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 columnstime, x1, y1, x2, y2, ....id_probabilities.csv: one row per frame, with columnstime, 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"])