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