idtracker.ai stores trajectories in image (top-left) coordinates; the
reader reflects y so the returned aniframe is in the conventional
bottom_left origin. For h5 files the frame height is read from the
file, as described below. CSV exports do not include the frame
height, so pass video_height explicitly to get an accurate flip
(otherwise max(y) is used as a fallback).
Usage
read_idtracker(
path,
path_probabilities = NULL,
video_height = NULL,
format = c("auto", "h5", "csv", "csv_tidy", "parquet")
)Arguments
- path
Path to an idtracker.ai data frame
- path_probabilities
Path to a csv file with probabilities. Only needed if you are reading csv files as they are included in h5 files.
- video_height
Optional numeric height of the source video frame in pixels. Overrides the value read from the h5 or Parquet file when both are available.
- format
Which idtracker.ai export
pathis:"h5", the CSV export ("csv",trajectories.csv), the tidy CSV export ("csv_tidy",trajectories_tidy.csv) or"parquet". The default,"auto", tells them apart by the suffix and, for a CSV, by its header. Which one was read is recorded in thesource_formatmetadata field.
Value
a movement dataframe. The first frame of the video is at
time = 0, in frames or in seconds; see "Time" in read_dataset().
Details
An h5 file also records, as attributes of its root, how the recording was tracked, and the reader keeps what has a place in the metadata:
version, the idtracker.ai version that tracked it, becomes thesource_versionmetadata field.frames_per_second, the frame rate of the video, becomes thesampling_ratemetadata field.timestays the frame number, counted from 0 as idtracker.ai counts frames, sounit_timeis still"frame"; the frame rate is what converts it to seconds.height, the height of the video frame, is what y is reflected around, unlessvideo_heightis given. Aheightdataset is used when there is no such attribute.width, the width of the video frame, written by newer releases, becomes the x extent in theaxis_extentsmetadata field.identities_labels, the names of the identities, which can be changed in idtracker.ai's validator, name the individuals. idtracker.ai writes"1","2", ... when none were set, which are also the names used when the file has no usable labels (one distinct, non-empty label per individual).
source_version and sampling_rate stay NA when the file does not
record them, and no x extent is recorded without a width.
The CSV export keeps these in a separate attributes.json rather than in
trajectories.csv, and the reader does not read it, so a frame read from
the CSV has no source_version; set it with anicore::set_metadata().
Its time column (seconds, or time in newer releases) is the time in
seconds, so unit_time is "s", where a frame read from the h5 has
"frame". The time column still states the frame rate: idtracker.ai
writes one row per frame, with the time as the row number divided by the
frame rate, rounded to 1 ms. The reader takes the rate from the rows over
the time they span, or the whole number nearest to it when that fits every
row as well, and sets it as sampling_rate. It is left NA when the
times are not evenly spaced.
When idtracker.ai could not read the video's frame rate, it writes the
CSV export without a time column, and frames_per_second as null in
attributes.json. time is then the frame number, the row counted from
0 as the h5 reader counts frames, unit_time is "frame", and
sampling_rate is NA. Set the rate with anicore::set_metadata() if you know it.
Tidy CSV and Parquet exports
idtracker.ai 6.0.13 added a Parquet export, trajectories.parquet, and
6.0.14 a tidy CSV export, trajectories_tidy.csv. Both hold one row per
frame and individual, with the columns frame, time, individual, x,
y and probability, and are written only when asked for in
TRAJECTORIES_FORMATS (or by idtrackerai_format --formats csv_tidy parquet).
The Parquet file stores the attributes the h5 keeps (
version,frames_per_second,height,width,identities_labels, ...) as JSON in its own metadata, and the reader uses them as it does the h5's.The tidy CSV keeps them in
attributes_tidy.jsonbeside it, which the reader reads when it is there, since idtracker.ai writes the two together as one export.
frame and individual count from 0. Individuals are numbered from 1, as
the h5 reader numbers them, and named by identities_labels where those
are usable. probability becomes confidence. When the frame rate is
known, time is the file's time in seconds, which is the frame over the
frame rate, as the CSV export times its rows, with unit_time "s" and
the frame rate as sampling_rate. When idtracker.ai could not read the
frame rate it still writes a time column, but as the frame over 1, so
time is then the frame, counted from 0, with unit_time "frame" and
sampling_rate NA. Without
attributes_tidy.json, a tidy CSV whose time equals its frame in every
row is read as one without a frame rate, and otherwise the rate is taken
from the two columns, as for the CSV export.
References
Romero-Ferrero, F., Bergomi, M. G., Hinz, R. C., Heras, F. J. H., & de Polavieja, G. G. (2019). idtracker.ai: tracking all individuals in small or large collectives of unmarked animals. Nature Methods, 16, 179-182. doi:10.1038/s41592-018-0295-5 .
Torrents, J., Costa, T., & de Polavieja, G. G. (2025). New idtracker.ai: rethinking multi-animal tracking as a representation learning problem to increase accuracy and reduce tracking times. eLife (reviewed preprint). doi:10.7554/eLife.107602 .
Examples
path <- system.file("extdata", "idtracker.csv", package = "aniread")
read_idtracker(path)
#> # Individuals: 1, 2, 3, 4, 5, 6, 7, 8
#> # Keypoints: centroid
#> # Sampling rate: 28 Hz
#> # Time: 00:00:00.000 to 00:00:00.321
#> individual keypoint time x y
#> <fct> <fct> <dbl> <dbl> <dbl>
#> 1 1 centroid 0 853. 216.
#> 2 1 centroid 0.036 851. 211.
#> 3 1 centroid 0.071 850. 208.
#> 4 1 centroid 0.107 849. 203.
#> 5 1 centroid 0.143 848. 200.
#> 6 1 centroid 0.179 847. 196.
#> 7 1 centroid 0.214 846. 192.
#> 8 1 centroid 0.25 846. 189.
#> 9 1 centroid 0.286 846. 186.
#> 10 1 centroid 0.321 845. 183.
#> # ℹ 70 more rows