Skip to contents

One entry point for every format aniread supports. By default the source software is worked out from the file itself, so you do not have to know which reader a file needs before opening it.

Usage

read_dataset(paths, source = "auto", ...)

Arguments

paths

Path to the file to read. A few readers take more than one path - read_trackball() takes one per sensor - in which case pass them all; detection inspects the first.

source

Which source software wrote the file. "auto" (the default) detects it with detect_source(). Otherwise one of the names in get_supported_sources().

...

Passed on to the reader for source. This is how arguments that only some readers take are supplied, e.g. sampling_rate for read_trackball() or path_probabilities for read_idtracker().

Value

An anipoint or anievent, depending on the reader. time (or an event's start and stop) follows the convention in the Time section.

Details

read_dataset() is a dispatcher, not a new reader: it works out which reader to call and calls it. The object you get back is exactly what the underlying reader returns - an anipoint for tracking data, or an anievent for behavioural events from read_boris().

DeepLabCut and LightningPose CSV exports are structurally identical, so a file in that format cannot be attributed to one or the other. Such a file is read with read_deeplabcut() - the parse is the same either way - and its source metadata is set to "deeplabcut/lightningpose" to record that the distinction is undetermined. Pass source explicitly to override this.

Every reader records the export it read in the source_format metadata field, so a file in a layout a reader does not expect can be traced back to it; get_supported_sources() lists the values each reader records. The version of the software that wrote the file goes in source_version only where the file states it, and is NA otherwise.

Time

Every reader gives time as the time elapsed since the first frame of the video, so the first frame of the video is at time = 0, whatever the unit (#150):

  • In frames, time is the frame number counted from 0: the first frame of the video is 0, the next 1, and so on. Converting to seconds is then a division by the frame rate, with no offset.

  • In seconds, the first frame of the video is at 0 s.

  • Offsets are kept. A file whose first row is frame 500 of the video has time = 500 there, not 0, so it stays aligned with the video.

Sources that count frames from 0 are read as they are. Sources that count them from 1 are shifted by one. Where a source gives times in seconds, they are kept. The table lists each source's own convention, what time was before aniread 0.8.0 and what it is now. Sources not marked as changed read as before.

Source (reader)The source's own timetime beforetime now
aniframe (read_aniframe())As written by write_aniframe()As writtenUnchanged
AnimalTA (read_animalta())Frame counts the video's frames from 0, keeping a cropped start; Time is the frame over the frame rate, in sTime in s; a detailed file without Time in frames, from its FrameUnchanged
Anipose (read_anipose())fnum counts frames from 0fnumUnchanged
Bonsai (read_bonsai())A clock time per row, set by the workflow; no frame numberSeconds from the first rowUnchanged
BORIS (read_boris())Start (s)/Stop (s) are media time in s. The image index counts a video's frames from 0 (mpv's frame number), and the images of an observation of images from 1In s, or the image index as writtenIn s unchanged; in frames, an observation of images is shifted by 1 so its first image is 0, and a video's frames are unchanged
C3D (read_c3d())Frames count from 1; the header records the recording frame the file starts atSeconds from the file's first frame, which was always 0Seconds from the recording's first frame: 0 for a file that starts at frame 1, (first frame - 1) / rate for a trimmed one
DeepLabCut (read_deeplabcut())The row index counts frames from 0The indexUnchanged
FastTrack (read_fasttrack())imageNumber is the video's frame, from 0imageNumberUnchanged
FicTrac (read_fictrac())A clock time per row, in msSeconds from the first rowUnchanged
FreeMoCap (read_freemocap())frame counts from 0, or the row is the frame; v1 also writes timestampsSeconds from the first frame's timestamp, or the frame from 0Unchanged
idtracker.ai .h5 (read_idtracker())Rows are the video's frames, from 0The row, counted from 1The frame, from 0
idtracker.ai CSV, with a time columntime (or seconds) is the frame over the frame rate, in sThe time in sUnchanged
idtracker.ai CSV, without a time columnRows are the video's frames, from 0The row, counted from 1The frame, from 0
idtracker.ai tidy CSV and Parquetframe counts from 0; time is the frame over the frame rate, or over 1 when the rate is unknownThe time in s, or the frame + 1In s unchanged; without a rate, the frame, from 0
Lightning Pose (read_lightningpose())The row index counts frames from 0The indexUnchanged
movement (read_movement())The time coordinate: frames from 0, or the frame over the frame rate in sAs writtenUnchanged
OCTRON (read_octron())frame_idx is the video's frame, from 0frame_idxUnchanged
SLEAP .h5 (read_sleap())The frame axis starts at frame_idx 0The position on the axis, counted from 1frame_idx, from 0
SLEAP CSVframe_idx counts from 0frame_idx + 1frame_idx
Trackball (read_trackball())Sensor samples with a clock or counter; no videoSeconds from the first shared sampleUnchanged
TrackMate (read_trackmate())FRAME counts from 0; POSITION_T is the frame times the frame intervalPOSITION_TUnchanged
TRex (read_trex())frame counts from 0; time is in s, 0 at frame 0timeUnchanged
read_custom()Whatever the file holdsAs in the fileUnchanged

Where a source keeps only clock times (Bonsai, FicTrac, the FreeMoCap v1 timestamps), nothing in the file marks the first frame of the video, so the first row is taken as 0. That is the first frame the tool logged: FicTrac writes no row for a frame it could not match, so if it lost its first frames, 0 is the first one it matched. A SLEAP .h5 written without its leading untracked frames (sleap-io's all_frames = FALSE) does not record where it starts, so its first row reads as frame 0.

See also

detect_source() to detect the format without reading, get_supported_sources() for what is supported, and the individual read_*() functions for format-specific arguments.

Examples

# Let aniread work out the format
path <- system.file("extdata", "sleap.analysis.csv", package = "aniread")
read_dataset(path)
#> # Individuals: track_0, track_1
#> # Keypoints:   abdomen, eyeL, eyeR, forelegL4, forelegR4, head, hindlegL4,
#> #   hindlegR4, midlegL4, midlegR4, thorax, wingL, wingR
#>    individual keypoint  time     x     y confidence
#>    <fct>      <fct>    <dbl> <dbl> <dbl>      <dbl>
#>  1 track_0    abdomen      0  240. 432.       0.489
#>  2 track_0    abdomen      1  403. 224.       0.955
#>  3 track_0    abdomen      2  584.  92.4      0.580
#>  4 track_0    abdomen      3  380.  99.8      0.741
#>  5 track_0    abdomen      4  265. 333.       0.636
#>  6 track_0    abdomen      5  268. 336.       0.736
#>  7 track_0    eyeL         0  213. 372.       0.851
#>  8 track_0    eyeL         1  440. 180.       1.07 
#>  9 track_0    eyeL         2  600.  28.4      1.00 
#> 10 track_0    eyeL         3  328. 128.       0.781
#> # ℹ 146 more rows

# Name it explicitly
read_dataset(path, source = "sleap")
#> # Individuals: track_0, track_1
#> # Keypoints:   abdomen, eyeL, eyeR, forelegL4, forelegR4, head, hindlegL4,
#> #   hindlegR4, midlegL4, midlegR4, thorax, wingL, wingR
#>    individual keypoint  time     x     y confidence
#>    <fct>      <fct>    <dbl> <dbl> <dbl>      <dbl>
#>  1 track_0    abdomen      0  240. 432.       0.489
#>  2 track_0    abdomen      1  403. 224.       0.955
#>  3 track_0    abdomen      2  584.  92.4      0.580
#>  4 track_0    abdomen      3  380.  99.8      0.741
#>  5 track_0    abdomen      4  265. 333.       0.636
#>  6 track_0    abdomen      5  268. 336.       0.736
#>  7 track_0    eyeL         0  213. 372.       0.851
#>  8 track_0    eyeL         1  440. 180.       1.07 
#>  9 track_0    eyeL         2  600.  28.4      1.00 
#> 10 track_0    eyeL         3  328. 128.       0.781
#> # ℹ 146 more rows

# Reader-specific arguments pass straight through
paths <- c(
  system.file("extdata", "trackball_sensor_1.csv", package = "aniread"),
  system.file("extdata", "trackball_sensor_2.csv", package = "aniread")
)
read_dataset(
  paths,
  setup = "of_free",
  sampling_rate = 60,
  col_time = "datetime"
)
#> # Keypoints:     centroid
#> # Sampling rate: 60 Hz (recorded with no fixed rate)
#> # Time:          2023-09-14 14:37:55.977 to 2023-09-14 14:37:56.110
#>   keypoint   time     x     y
#>   <fct>     <dbl> <dbl> <dbl>
#> 1 centroid 0          0     0
#> 2 centroid 0.0167     2     2
#> 3 centroid 0.0333     5     5
#> 4 centroid 0.05       6     6
#> 5 centroid 0.0667     6     6
#> 6 centroid 0.0833     7     7
#> 7 centroid 0.1       12    12
#> 8 centroid 0.117     16    16
#> 9 centroid 0.133     22    22