Add documentation to specify Movement require identical keypoints (#150)

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()<movement.io.load_poses.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.

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
+    <https://deeplabcut.github.io/DeepLabCut/docs/maDLC_UserGuide.html#b-configure-the-project>`_),
+    this feature is not currently supported in ``movement``.
+
     """
     return _ds_from_lp_or_dlc_file(
         file_path=file_path, source_software="DeepLabCut", fps=fps