Reads movement tracking data exported from TRex (Walter & Couzin, 2021), from either of its two exports.
The .npz export is TRex's native one: a zip of .npy arrays, one file
per tracked individual, so a whole recording is a vector of paths. It
carries the pose keypoints, a per-frame detection probability, the
identity, and the recording's frame rate and frame size. The CSV export
carries the centroid and midline of a single individual and none of that
metadata, so several columns come back NA.
Both exports give time in seconds, so unit_time is "s". The .npz
records the frame rate as frame_rate, which becomes sampling_rate. The
CSV does not record it, but when it has both a frame and a time column,
and every time is the frame number divided by one rate (to within the
rounding of time), that rate becomes sampling_rate: the frames between
the first and last row over the seconds between them, or the whole number
nearest to it when that fits every row as well. Otherwise, as when the
times are camera timestamps that vary from frame to frame, it is left NA.
Both exports give positions in centimetres, so unit_space is "cm".
TRex converts from pixels with its cm_per_pixel, the real width of the
image (meta_real_width) over its width in pixels. When nobody set the
real width, TRex assumes 30 cm, so the centimetres are only as real as
that setting. The .npz records the frame size as video_size, in
pixels, and cm_per_pixel; their product is the frame's width and height
in centimetres, which become the axis_extents of x and y and what y is
reflected around.
Usage
read_trex(path, format = c("auto", "csv", "npz"), video_height = NULL)Arguments
- path
Character string specifying the path to a TRex CSV file. The file should contain columns for:
time
x and y coordinates for tracked points (e.g., x_head, y_head)
x and y coordinates for centroid (x_number_wcentroid_cm, y_number_wcentroid_cm)
- format
Which export to read.
"auto"(default) reads it from the file: the.npzexport is a zip of.npyarrays, the CSV export is not.- video_height
Optional numeric height of the source video frame in the same spatial units as the tracking output, centimetres. The
.npzexport records this asvideo_sizeand it is used automatically; TRex's CSV export does not, so without itmax(y)is used as a fallback when reflecting tobottom_left.
Value
A data frame containing movement data with the following columns:
time: TRex'stime, in seconds, with the first frame of the video at 0; see "Time" inread_dataset()individual: Factor. The identity TRex assigned, from the.npzexport;NAfrom the CSV export, which does not record itkeypoint: Factor identifying tracked points (e.g., "head", "centroid")x: x-coordinates in centimetersy: y-coordinates in centimetersconfidence: Numeric. TRex's per-framedetection_pfrom the.npzexport;NAfrom the CSV export, which does not record ityaw: TRex'sANGLE, the direction the individual faces, from its posture, when the export includes it. Declared as the frame's orientation, so it is reflected withy; the same value on every keypoint of an individual.
Details
The function performs several processing steps:
Validates the input file format (must be CSV)
Reads the data using vroom for efficient processing
Cleans column names to a consistent format
Restructures the data from wide to long format
Initializes metadata fields required for movement data
References
Walter, T., & Couzin, I. D. (2021). TRex, a fast multi-animal tracking system with markerless identification, and 2D estimation of posture and visual fields. eLife, 10, e64000. doi:10.7554/eLife.64000 .
Examples
# TRex's native export: one .npz per tracked individual
path <- system.file("extdata", "trex_id3.npz", package = "aniread")
read_trex(path)
#> # Individuals: 3
#> # Keypoints: centroid, pose0, pose1
#> # Sampling rate: 30 Hz
#> # Time: 00:00:00.000 to 00:00:00.133
#> individual keypoint time x y confidence
#> <fct> <fct> <dbl> <dbl> <dbl> <dbl>
#> 1 3 centroid 0 10 28 0.900
#> 2 3 centroid 0.0333 10.5 27.5 0.850
#> 3 3 centroid 0.0667 NA NA NA
#> 4 3 centroid 0.100 11.5 26.5 0.800
#> 5 3 centroid 0.133 12 26 0.950
#> 6 3 pose0 0 10 28 0.900
#> 7 3 pose0 0.0333 10.5 27.5 0.850
#> 8 3 pose0 0.0667 NA NA NA
#> 9 3 pose0 0.100 11.5 26.5 0.800
#> 10 3 pose0 0.133 12 26 0.950
#> 11 3 pose1 0 11 27 0.900
#> 12 3 pose1 0.0333 11.5 26.5 0.850
#> 13 3 pose1 0.0667 NA NA NA
#> 14 3 pose1 0.100 12.5 25.5 0.800
#> 15 3 pose1 0.133 13 25 0.950
if (FALSE) { # interactive()
# A whole recording is the vector of paths get_sample_data() returns
read_trex(get_sample_data("trex"))
}