diff --git a/docs/source/user_guide/input_output.md b/docs/source/user_guide/input_output.md index 3abe81996..0b4907806 100644 --- a/docs/source/user_guide/input_output.md +++ b/docs/source/user_guide/input_output.md @@ -56,9 +56,9 @@ from movement.io import load_poses To read a pose tracks file into a [movement poses dataset](target-poses-and-bboxes-dataset), we provide specific functions for each of the supported formats. We additionally provide a more general {func}`from_numpy()` function, with which we can build a [movement poses dataset](target-poses-and-bboxes-dataset) from a set of NumPy arrays. -::::{tab-set} +:::::{tab-set} -:::{tab-item} DeepLabCut +::::{tab-item} DeepLabCut To load DeepLabCut files in .h5 format: ```python @@ -83,7 +83,11 @@ formatted in the DeepLabCut style: ds = load_poses.from_dlc_style_df(df, fps=30) ``` +:::{note} +In `movement`, pose data can only be loaded if all individuals have the same set of keypoints (i.e., the same labeled body parts). While DeepLabCut supports assigning keypoints that are not shared across individuals (see the [DeepLabCut documentation for multi-animal projects](https://deeplabcut.github.io/DeepLabCut/docs/maDLC_UserGuide.html#b-configure-the-project)), this feature is not currently supported in `movement`. ::: +:::: + :::{tab-item} SLEAP To load [SLEAP analysis files](sleap-docs:learnings/export-analysis/) in .h5 format (recommended): @@ -103,9 +107,9 @@ To load SLEAP files in .slp format (experimental, see notes in {func}`movement.i ds = load_poses.from_sleap_file("/path/to/file.predictions.slp", fps=30) ``` -::: +:::: -:::{tab-item} LightningPose +::::{tab-item} LightningPose To load LightningPose files in .csv format: ```python @@ -124,9 +128,9 @@ directly load an appropriately formatted pandas DataFrame `df`: ds = load_poses.from_dlc_style_df(df, fps=30, source_software="LightningPose") ``` -::: +:::: -:::{tab-item} Anipose +::::{tab-item} Anipose To load Anipose files in .csv format: ```python @@ -152,9 +156,9 @@ ds = load_poses.from_anipose_style_df( ) ``` -::: +:::: -:::{tab-item} NWB +::::{tab-item} NWB To load NWB files in .nwb format: ```python @@ -185,9 +189,9 @@ with pynwb.NWBHDF5IO("path/to/file.nwb", mode="r") as io: ) ``` -::: +:::: -:::{tab-item} From NumPy +::::{tab-item} From NumPy In the example below, we create random position data for two individuals, `Alice` and `Bob`, with three keypoints each: `snout`, `centre`, and `tail_base`. These keypoints are tracked in 2D space for 100 frames, at 30 fps. The confidence scores are set to 1 for all points. @@ -204,10 +208,10 @@ ds = load_poses.from_numpy( ) ``` -::: - :::: +::::: + The resulting poses data structure `ds` will include the predicted trajectories for each individual and keypoint, as well as the associated point-wise confidence values reported by the pose estimation software. diff --git a/movement/io/load_poses.py b/movement/io/load_poses.py index 6f661be69..0cf85b4b5 100644 --- a/movement/io/load_poses.py +++ b/movement/io/load_poses.py @@ -134,6 +134,7 @@ def from_file( ``movement`` dataset containing the pose tracks, confidence scores, and associated metadata. + See Also -------- movement.io.load_poses.from_dlc_file @@ -370,6 +371,15 @@ def from_dlc_file( >>> from movement.io import load_poses >>> ds = load_poses.from_dlc_file("path/to/file.h5", fps=30) + Notes + ----- + In ``movement``, pose data can only be loaded if all individuals have + the same set of keypoints (i.e., the same labeled body parts). + While DeepLabCut supports assigning keypoints that are not shared across + individuals (see the `DeepLabCut documentation for multi-animal projects + `_), + this feature is not currently supported in ``movement``. + """ return _ds_from_lp_or_dlc_file( file_path=file_path, source_software="DeepLabCut", fps=fps