Skip to contents

Read files from DeepLabCut (DLC) in either csv or h5 format. DeepLabCut stores predictions in image (top-left) coordinates; the reader reflects y so the returned aniframe is in the conventional bottom_left origin. DLC's csv/h5 exports do not contain the source video resolution (it lives in the project's config.yaml), so pass video_height to get an accurate flip; otherwise max(y) is used as a fallback.

Usage

read_deeplabcut(path, video_height = NULL)

Arguments

path

Path to a DeepLabCut data file

video_height

Optional numeric height of the source video frame in pixels. Not used for 3D files.

Value

an aniframe. time is DeepLabCut's frame index, with the first frame of the video at 0; see "Time" in read_dataset().

Layouts read

The file is read from its column header, the scorer, individuals (multi-animal projects only), bodyparts and coords levels, so the same data reads the same from a csv and an h5. An h5 is read whichever way pandas stored it: DeepLabCut writes the "table" format, while a file saved again with pandas' defaults, as movement's to_dlc_file() does, is in the "fixed" format. Predictions are read from the HDF key df_with_missing, and the stitched tracklets of a multi-animal project (*_el.h5) from the key tracks.

Of the coords, x, y, z and likelihood are read, and likelihood becomes confidence. Any other coords, such as the variances the Ensemble Kalman Smoother adds, are not read.

A multi-animal project tracks the bodyparts it does not assign to an animal (its uniquebodyparts) under the pseudo-individual single. They are kept as the keypoints of an individual called "single".

The layout read is recorded in the source_format metadata field: the file type, single- or multi-animal, and _3d for triangulated positions, such as "csv_single_animal" or "h5_multi_animal".

3D files

DeepLabCut's triangulation writes x, y and z and no likelihood, so confidence is NA. Triangulated positions are in the units and frame of the stereo calibration rather than in image pixels, so they are returned as stored: y is not reflected and video_height is not used. The aniframe is 3D from its z column.

References

  • Mathis, A., Mamidanna, P., Cury, K. M., Abe, T., Murthy, V. N., Mathis, M. W., & Bethge, M. (2018). DeepLabCut: markerless pose estimation of user-defined body parts with deep learning. Nature Neuroscience, 21, 1281-1289. doi:10.1038/s41593-018-0209-y .

  • Nath, T., Mathis, A., Chen, A. C., Patel, A., Bethge, M., & Mathis, M. W. (2019). Using DeepLabCut for 3D markerless pose estimation across species and behaviors. Nature Protocols, 14, 2152-2176. doi:10.1038/s41596-019-0176-0 .

Examples

path <- system.file("extdata", "deeplabcut.csv", package = "aniread")
read_deeplabcut(path)
#> # Keypoints: head, stinger
#>    keypoint  time     x     y confidence
#>    <fct>    <dbl> <dbl> <dbl>      <dbl>
#>  1 head         0 1086.  7.05     0.0531
#>  2 head         1 1086.  7.00     0.0353
#>  3 head         2 1086.  6.74     0.0171
#>  4 head         3 1085.  5.96     0.238 
#>  5 head         4 1085.  6.06     0.502 
#>  6 head         5 1085.  6.01     0.510 
#>  7 head         6 1085.  5.77     0.835 
#>  8 head         7 1084.  4.83     0.662 
#>  9 head         8 1084.  4.90     0.461 
#> 10 head         9 1084.  3.85     0.934 
#> 11 stinger      0 1084.  7.24     0.0737
#> 12 stinger      1 1083.  7.09     0.0329
#> 13 stinger      2 1083.  6.94     0.0102
#> 14 stinger      3 1082.  2.87     0.173 
#> 15 stinger      4 1079.  1.34     0.269 
#> 16 stinger      5 1078.  1.65     0.284 
#> 17 stinger      6 1077.  1.25     0.802 
#> 18 stinger      7 1076.  1.75     0.621 
#> 19 stinger      8 1076.  2.13     0.351 
#> 20 stinger      9 1076.  0        0.942