Renaming load_poses and save_poses to load_dataset and save_dataset

docs/source/blog/movement-v0_0_21.md

@@ -20,7 +20,7 @@ install the latest version or upgrade from an existing installation.
 
 __Input/Output__
 
-- We have added the {func}`movement.io.load_poses.from_multiview_files` function to support loading pose tracking data from multiple camera views.
+- We have added the {func}`movement.io.load_dataset.from_multiview_files` function to support loading pose tracking data from multiple camera views.
 - We have made several small improvements to reading bounding box tracks. See our new {ref}`example <sphx_glr_examples_load_and_upsample_bboxes.py>` to learn more about working with bounding boxes.
 - We have added a new {ref}`example <sphx_glr_examples_convert_file_formats.py>` on using `movement` to convert pose tracking data between different file formats.
 

docs/source/user_guide/input_output.md

@@ -26,12 +26,16 @@ included with the package.
 ## Loading pose tracks
 
 The pose tracks loading functionalities are provided by the
-{mod}`movement.io.load_poses` module, which can be imported as follows:
+{mod}`movement.io.load_dataset` module, which can be imported as follows:
 
 ```python
-from movement.io import load_poses
+from movement.io import load_dataset
 ```
 
+:::{warning}
+The old module names `movement.io.load_poses` and `movement.io.save_poses` are deprecated and will be removed in a future version. Please use `movement.io.load_dataset` and `movement.io.save_dataset` instead.
+:::
+
 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 `from_numpy()` method, with which we can build a [movement poses dataset](target-poses-and-bboxes-dataset) from a set of NumPy arrays.
 
 ::::{tab-set}
@@ -40,46 +44,46 @@ To read a pose tracks file into a [movement poses dataset](target-poses-and-bbox
 
 To load [SLEAP analysis files](sleap:tutorials/analysis) in .h5 format (recommended):
 ```python
-ds = load_poses.from_sleap_file("/path/to/file.analysis.h5", fps=30)
+ds = load_dataset.from_sleap_file("/path/to/file.analysis.h5", fps=30)
 
 # or equivalently
-ds = load_poses.from_file(
+ds = load_dataset.from_file(
     "/path/to/file.analysis.h5", source_software="SLEAP", fps=30
 )
 ```
-To load [SLEAP analysis files](sleap:tutorials/analysis) in .slp format (experimental, see notes in {func}`movement.io.load_poses.from_sleap_file`):
+To load [SLEAP analysis files](sleap:tutorials/analysis) in .slp format (experimental, see notes in {func}`movement.io.load_dataset.from_sleap_file`):
 
 ```python
-ds = load_poses.from_sleap_file("/path/to/file.predictions.slp", fps=30)
+ds = load_dataset.from_sleap_file("/path/to/file.predictions.slp", fps=30)
 ```
 :::
 
 :::{tab-item} DeepLabCut
 
 To load DeepLabCut files in .h5 format:
 ```python
-ds = load_poses.from_dlc_file("/path/to/file.h5", fps=30)
+ds = load_dataset.from_dlc_file("/path/to/file.h5", fps=30)
 
 # or equivalently
-ds = load_poses.from_file(
+ds = load_dataset.from_file(
     "/path/to/file.h5", source_software="DeepLabCut", fps=30
 )
 ```
 
 To load DeepLabCut files in .csv format:
 ```python
-ds = load_poses.from_dlc_file("/path/to/file.csv", fps=30)
+ds = load_dataset.from_dlc_file("/path/to/file.csv", fps=30)
 ```
 :::
 
 :::{tab-item} LightningPose
 
 To load LightningPose files in .csv format:
 ```python
-ds = load_poses.from_lp_file("/path/to/file.analysis.csv", fps=30)
+ds = load_dataset.from_lp_file("/path/to/file.analysis.csv", fps=30)
 
 # or equivalently
-ds = load_poses.from_file(
+ds = load_dataset.from_file(
     "/path/to/file.analysis.csv", source_software="LightningPose", fps=30
 )
 ```
@@ -89,15 +93,14 @@ ds = load_poses.from_file(
 
 To load Anipose files in .csv format:
 ```python
-ds = load_poses.from_anipose_file(
+ds = load_dataset.from_anipose_file(
     "/path/to/file.analysis.csv", fps=30, individual_name="individual_0"
 )  # We can optionally specify the individual name, by default it is "individual_0"
 
 # or equivalently
-ds = load_poses.from_file(
+ds = load_dataset.from_file(
     "/path/to/file.analysis.csv", source_software="Anipose", fps=30, individual_name="individual_0"
 )
-
 ```
 :::
 
@@ -109,7 +112,7 @@ with three keypoints each: ``snout``, ``centre``, and ``tail_base``. These keypo
 ```python
 import numpy as np
 
-ds = load_poses.from_numpy(
+ds = load_dataset.from_numpy(
     position_array=np.random.rand(100, 2, 3, 2),
     confidence_array=np.ones((100, 3, 2)),
     individual_names=["Alice", "Bob"],
@@ -185,10 +188,10 @@ For more information on the bounding boxes data structure, see the [movement bou
 formats, including DeepLabCut-style files (.h5 or .csv) and
 [SLEAP-style analysis files](sleap:tutorials/analysis) (.h5).
 
-To export pose tracks from `movement`, first import the {mod}`movement.io.save_poses` module:
+To export pose tracks from `movement`, first import the {mod}`movement.io.save_dataset` module:
 
 ```python
-from movement.io import save_poses
+from movement.io import save_dataset
 ```
 
 Then, depending on the desired format, use one of the following functions:
@@ -199,7 +202,7 @@ Then, depending on the desired format, use one of the following functions:
 
 To save as a SLEAP analysis file in .h5 format:
 ```python
-save_poses.to_sleap_analysis_file(ds, "/path/to/file.h5")
+save_dataset.to_sleap_analysis_file(ds, "/path/to/file.h5")
 ```
 
 :::{note}
@@ -218,11 +221,11 @@ each attribute and data variable represents, see the
 
 To save as a DeepLabCut file, in .h5 or .csv format:
 ```python
-save_poses.to_dlc_file(ds, "/path/to/file.h5")  # preferred format
-save_poses.to_dlc_file(ds, "/path/to/file.csv")
+save_dataset.to_dlc_file(ds, "/path/to/file.h5")  # preferred format
+save_dataset.to_dlc_file(ds, "/path/to/file.csv")
 ```
 
-The {func}`movement.io.save_poses.to_dlc_file` function also accepts
+The {func}`movement.io.save_dataset.to_dlc_file` function also accepts
 a `split_individuals` boolean argument. If set to `True`, the function will
 save the data as separate single-animal DeepLabCut-style files.
 
@@ -232,13 +235,13 @@ save the data as separate single-animal DeepLabCut-style files.
 
 To save as a LightningPose file in .csv format:
 ```python
-save_poses.to_lp_file(ds, "/path/to/file.csv")
+save_dataset.to_lp_file(ds, "/path/to/file.csv")
 ```
 :::{note}
 Because LightningPose follows the single-animal
 DeepLabCut .csv format, the above command is equivalent to:
 ```python
-save_poses.to_dlc_file(ds, "/path/to/file.csv", split_individuals=True)
+save_dataset.to_dlc_file(ds, "/path/to/file.csv", split_individuals=True)
 ```
 :::
 

docs/source/user_guide/movement_dataset.md

@@ -139,7 +139,7 @@ file containing pose or bounding box tracks.
 
 In some cases, you may encounter or create datasets with extra
 **dimensions**. For example, the
-{func}`movement.io.load_poses.from_multiview_files()` function
+{func}`movement.io.load_dataset.from_multiview_files()` function
 creates an additional `views` **dimension**,
 with the **coordinates** being the names given to each camera view.
 :::

examples/convert_file_formats.py

@@ -28,7 +28,7 @@
 from pathlib import Path
 
 from movement import sample_data
-from movement.io import load_poses, save_poses
+from movement.io import load_dataset, save_dataset
 
 # %%
 # Load the dataset
@@ -54,7 +54,7 @@
 # :ref:`movement poses dataset<target-poses-and-bboxes-dataset>`,
 # which we can then modify to our liking.
 
-ds = load_poses.from_sleap_file(file_path, fps=30)
+ds = load_dataset.from_sleap_file(file_path, fps=30)
 print(ds, "\n")
 print("Individuals:", ds.coords["individuals"].values)
 print("Keypoints:", ds.coords["keypoints"].values)
@@ -166,7 +166,7 @@ def reorder_keypoints(ds, ordered_keypoints):
 target_dir = tempfile.mkdtemp()
 dest_path = Path(target_dir) / f"{file_path.stem}_dlc.csv"
 
-save_poses.to_dlc_file(ds_reordered, dest_path, split_individuals=False)
+save_dataset.to_dlc_file(ds_reordered, dest_path, split_individuals=False)
 print(f"Saved modified dataset to {dest_path}.")
 
 # %%
@@ -215,13 +215,13 @@ def convert_all(data_dir, target_dir, suffix=".slp"):
         if file_path.exists():
             print(f"Processing: {file_path}")
             # load the data from SLEAP file
-            ds = load_poses.from_sleap_file(file_path)
+            ds = load_dataset.from_sleap_file(file_path)
             # modify the data
             ds_renamed = rename_keypoints(ds, rename_dict)
             ds_deleted = delete_keypoints(ds_renamed, keypoints_to_delete)
             ds_reordered = reorder_keypoints(ds_deleted, ordered_keypoints)
             # save modified data to a DeepLabCut file
-            save_poses.to_dlc_file(
+            save_dataset.to_dlc_file(
                 ds_reordered, dest_path, split_individuals=False
             )
         else:

examples/load_and_explore_poses.py

@@ -9,7 +9,7 @@
 # -------
 
 from movement import sample_data
-from movement.io import load_poses
+from movement.io import load_dataset
 from movement.plots import plot_centroid_trajectory
 
 # %%
@@ -35,7 +35,7 @@
 # Load the data into movement
 # ---------------------------
 
-ds = load_poses.from_sleap_file(file_path, fps=50)
+ds = load_dataset.from_sleap_file(file_path, fps=50)
 print(ds)
 
 # %%