Skip to contents

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 .npz export is a zip of .npy arrays, 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 .npz export records this as video_size and it is used automatically; TRex's CSV export does not, so without it max(y) is used as a fallback when reflecting to bottom_left.

Value

A data frame containing movement data with the following columns:

  • time: TRex's time, in seconds, with the first frame of the video at 0; see "Time" in read_dataset()

  • individual: Factor. The identity TRex assigned, from the .npz export; NA from the CSV export, which does not record it

  • keypoint: Factor identifying tracked points (e.g., "head", "centroid")

  • x: x-coordinates in centimeters

  • y: y-coordinates in centimeters

  • confidence: Numeric. TRex's per-frame detection_p from the .npz export; NA from the CSV export, which does not record it

  • yaw: TRex's ANGLE, the direction the individual faces, from its posture, when the export includes it. Declared as the frame's orientation, so it is reflected with y; the same value on every keypoint of an individual.

Details

The function performs several processing steps:

  1. Validates the input file format (must be CSV)

  2. Reads the data using vroom for efficient processing

  3. Cleans column names to a consistent format

  4. Restructures the data from wide to long format

  5. 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 .

See also

  • TRex software: https://trex.run

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"))
}