fixed docstirngs and API reference

movement/datasets.py

@@ -42,12 +42,17 @@
 
 
 def find_pose_data() -> List[str]:
-    """Find available sample pose data."""
+    """Find available sample pose data in the *movement* data repository.
+
+    Returns
+    -------
+    filenames : list of str
+        List of filenames for available pose data."""
     return list(POSE_DATA.registry.keys())
 
 
 def fetch_pose_data_path(filename: str) -> Path:
-    """Fetch sample pose data from the remote repository.
+    """Fetch sample pose data from the *movement* data repository.
 
     The data are downloaded to the user's local machine the first time they are
     used and are stored in a local cache directory. The function returns the

movement/io/load_poses.py

@@ -21,7 +21,7 @@
 
 
 def from_dlc_df(df: pd.DataFrame, fps: Optional[float] = None) -> xr.Dataset:
-    """Create an xarray.Dataset from a DLC_style pandas DataFrame.
+    """Create an xarray.Dataset from a DeepLabCut-style pandas DataFrame.
 
     Parameters
     ----------
@@ -45,6 +45,10 @@ def from_dlc_df(df: pd.DataFrame, fps: Optional[float] = None) -> xr.Dataset:
     The "coords" level contains the spatial coordinates "x", "y",
     as well as "likelihood" (point-wise confidence scores).
     The row index corresponds to the frame number.
+
+    See Also
+    --------
+    movement.io.load_poses.from_dlc_file : Load pose tracks directly from file.
     """
 
     # read names of individuals and keypoints from the DataFrame
@@ -78,8 +82,7 @@ def from_dlc_df(df: pd.DataFrame, fps: Optional[float] = None) -> xr.Dataset:
 def from_sleap_file(
     file_path: Union[Path, str], fps: Optional[float] = None
 ) -> xr.Dataset:
-    """Load pose tracking data from a SLEAP labels or analysis file
-    into an xarray Dataset.
+    """Load pose tracking data from a SLEAP file into an xarray Dataset.
 
     Parameters
     ----------
@@ -103,15 +106,15 @@ def from_sleap_file(
     from the ".slp" file, using either the command line tool `sleap-convert`
     (with the "--format analysis" option enabled) or the SLEAP GUI (Choose
     "Export Analysis HDF5…" from the "File" menu) [1]_. This is the
-    preferred format for loading pose tracks from SLEAP into `movement`.
+    preferred format for loading pose tracks from SLEAP into *movement*.
 
-    You can also try directly loading te ".slp" file, but this feature is
+    You can also try directly loading the ".slp" file, but this feature is
     experimental and doesnot work in all cases. If the ".slp" file contains
     both user-labeled and predicted instances, only the predicted ones will be
     loaded. If there are multiple videos in the file, only the first one will
     be used.
 
-    `movement` expects the tracks to be assigned and proofread before loading
+    *movement* expects the tracks to be assigned and proofread before loading
     them, meaning each track is interpreted as a single individual/animal.
     Follow the SLEAP guide for tracking and proofreading [2]_.
 
@@ -160,7 +163,7 @@ def from_dlc_file(
     Parameters
     ----------
     file_path : pathlib.Path or str
-        Path to the file containing the DLC poses, either in ".h5"
+        Path to the file containing the DLC predicted poses, either in ".h5"
         or ".csv" format.
     fps : float, optional
         The number of frames per second in the video. If None (default),
@@ -171,6 +174,10 @@ def from_dlc_file(
     xarray.Dataset
         Dataset containing the pose tracks, confidence scores, and metadata.
 
+    See Also
+    --------
+    movement.io.load_poses.from_dlc_df : Load pose tracks from a DataFrame.
+
     Examples
     --------
     >>> from movement.io import load_poses

movement/io/save_poses.py

@@ -31,6 +31,11 @@ def to_dlc_df(ds: xr.Dataset) -> pd.DataFrame:
     one individual present). Regardless of the provenance of the
     points-wise confidence scores, they will be referred to as
     "likelihood", and stored in the "coords" level (as DeepLabCut expects).
+
+    See Also
+    --------
+    to_dlc_file : Save the xarray dataset containing pose tracks directly
+        to a DeepLabCut-style ".h5" or ".csv" file.
     """
 
     if not isinstance(ds, xr.Dataset):
@@ -72,8 +77,8 @@ def to_dlc_df(ds: xr.Dataset) -> pd.DataFrame:
 
 
 def to_dlc_file(ds: xr.Dataset, file_path: Union[str, Path]) -> None:
-    """Export the xarray dataset containing pose tracks to a
-    DeepLabCut-style .h5 or .csv file.
+    """Save the xarray dataset containing pose tracks to a
+    DeepLabCut-style ".h5" or ".csv" file.
 
     Parameters
     ----------
@@ -82,6 +87,11 @@ def to_dlc_file(ds: xr.Dataset, file_path: Union[str, Path]) -> None:
     file_path : pathlib Path or str
         Path to the file to save the DLC poses to. The file extension
         must be either ".h5" (recommended) or ".csv".
+
+    See Also
+    --------
+    to_dlc_df : Convert an xarray dataset containing pose tracks into a
+        DeepLabCut-style pandas DataFrame with multi-index columns.
     """
 
     try:

movement/logging.py

@@ -22,7 +22,7 @@ def configure_logging(
         The logging level to use. Defaults to logging.INFO.
     logger_name : str, optional
         The name of the logger to configure.
-        Defaults to 'movement'.
+        Defaults to "movement".
     log_directory : pathlib.Path, optional
         The directory to store the log file in. Defaults to
         ~/.movement. A different directory can be specified,
@@ -71,7 +71,7 @@ def log_and_raise_error(error, message: str, logger_name: str = "movement"):
     message : str
         The error message.
     logger_name : str, optional
-        The name of the logger to use. Defaults to 'movement'.
+        The name of the logger to use. Defaults to "movement".
     """
     logger = logging.getLogger(logger_name)
     logger.error(message)
@@ -86,7 +86,7 @@ def log_warning(message: str, logger_name: str = "movement"):
     message : str
         The warning message.
     logger_name : str, optional
-        The name of the logger to use. Defaults to 'movement'.
+        The name of the logger to use. Defaults to "movement".
     """
     logger = logging.getLogger(logger_name)
     logger.warning(message)