fix: update default individual name from 'individual_0' to 'id_0' acr… (#618)

* fix: update default individual name from 'individual_0' to 'id_0' across codebase and tests

* docs: update input_output guide and tests/tests_units to reflect id_0 default naming

* Fix: Add fallback for missing individual in plot function; minor doc improvements

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* removed printing error message casuing error

* removed error message provided

* fix: change default individual name to 'id_0' for missing metadata

* chore: clean trailing whitespace from Makefile

* reset -W for warnings

* finishing touches

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: niksirbi <[email protected]>

Author: 3 people

docs/source/user_guide/input_output.md

@@ -1,4 +1,5 @@
 (target-io)=
+
 # Input/Output
 
 ## Overview
@@ -17,32 +18,33 @@ It may be useful to think of `movement` supporting two types of data loading/sav
 You are also welcome to try `movement` by loading some [sample data](target-sample-data) included with the package.
 
 (target-supported-formats)=
+
 ## Supported third-party formats
 
 `movement` supports the analysis of trajectories of keypoints (_pose tracks_) and of bounding box centroids (_bounding box tracks_),
 which are represented as [movement datasets](target-poses-and-bboxes-dataset)
 and can be loaded from and saved to various third-party formats.
 
-| Source Software | Abbreviation | Source Format | Dataset Type | Supported Operations |
-|-----------------|--------------|-------------|--------------|-------------------|
-| [DeepLabCut](dlc:) | DLC | DLC-style .h5 or .csv file, or corresponding pandas DataFrame | Pose | Load & Save |
-| [SLEAP](sleap:) | SLEAP | [analysis](sleap:tutorials/analysis) .h5 or .slp file | Pose | Load & Save |
-| [LightningPose](lp:) | LP | DLC-style .csv file, or corresponding pandas DataFrame | Pose | Load & Save |
-| [Anipose](anipose:) | | triangulation .csv file, or corresponding pandas DataFrame | Pose | Load |
-| [VGG Image Annotator](via:) | VIA | .csv file for [tracks annotation](via:docs/face_track_annotation.html) | Bounding box | Load |
-| [Neurodata Without Borders](https://nwb-overview.readthedocs.io/en/latest/) | NWB | .nwb file or NWBFile object with the [ndx-pose extension](https://github.com/rly/ndx-pose) | Pose | Load & Save |
-| Any |  | Numpy arrays | Pose or Bounding box | Load & Save* |
+| Source Software                                                             | Abbreviation | Source Format                                                                              | Dataset Type         | Supported Operations |
+| --------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------ | -------------------- | -------------------- |
+| [DeepLabCut](dlc:)                                                          | DLC          | DLC-style .h5 or .csv file, or corresponding pandas DataFrame                              | Pose                 | Load & Save          |
+| [SLEAP](sleap:)                                                             | SLEAP        | [analysis](sleap:tutorials/analysis) .h5 or .slp file                                      | Pose                 | Load & Save          |
+| [LightningPose](lp:)                                                        | LP           | DLC-style .csv file, or corresponding pandas DataFrame                                     | Pose                 | Load & Save          |
+| [Anipose](anipose:)                                                         |              | triangulation .csv file, or corresponding pandas DataFrame                                 | Pose                 | Load                 |
+| [VGG Image Annotator](via:)                                                 | VIA          | .csv file for [tracks annotation](via:docs/face_track_annotation.html)                     | Bounding box         | Load                 |
+| [Neurodata Without Borders](https://nwb-overview.readthedocs.io/en/latest/) | NWB          | .nwb file or NWBFile object with the [ndx-pose extension](https://github.com/rly/ndx-pose) | Pose                 | Load & Save          |
+| Any                                                                         |              | Numpy arrays                                                                               | Pose or Bounding box | Load & Save\*        |
 
-*Exporting any `movement` DataArray to a NumPy array is as simple as calling xarray's built-in {meth}`xarray.DataArray.to_numpy()` method, so no specialised "Export/Save As" function is needed, see [xarray's documentation](xarray:user-guide/duckarrays.html) for more details.
+\*Exporting any `movement` DataArray to a NumPy array is as simple as calling xarray's built-in {meth}`xarray.DataArray.to_numpy()` method, so no specialised "Export/Save As" function is needed, see [xarray's documentation](xarray:user-guide/duckarrays.html) for more details.
 
 :::{note}
 Currently, `movement` only works with tracked data: either keypoints or bounding boxes whose identities are known from one frame to the next, across consecutive frames. For pose estimation, this means it only supports the predictions output by the supported software packages listed above. Loading manually labelled data—often defined over a non-continuous set of frames—is not currently supported.
 :::
 
 Below, we explain how to load pose and bounding box tracks from these supported formats, as well as how to save pose tracks back to some of them.
 
-
 (target-loading-pose-tracks)=
+
 ### Loading pose tracks
 
 The pose tracks loading functionalities are provided by the
@@ -58,6 +60,7 @@ To read a pose tracks file into a [movement poses dataset](target-poses-and-bbox
 
 :::{tab-item} DeepLabCut
 To load DeepLabCut files in .h5 format:
+
 ```python
 ds = load_poses.from_dlc_file("/path/to/file.h5", fps=30)
 
@@ -66,13 +69,16 @@ ds = load_poses.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)
 ```
 
 You can also directly load any pandas DataFrame `df` that's
 formatted in the DeepLabCut style:
+
 ```python
 ds = load_poses.from_dlc_style_df(df, fps=30)
 ```
@@ -81,6 +87,7 @@ ds = load_poses.from_dlc_style_df(df, fps=30)
 
 :::{tab-item} SLEAP
 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)
 
@@ -89,14 +96,18 @@ ds = load_poses.from_file(
     "/path/to/file.analysis.h5", source_software="SLEAP", fps=30
 )
 ```
+
 To load SLEAP files in .slp format (experimental, see notes in {func}`movement.io.load_poses.from_sleap_file`):
+
 ```python
 ds = load_poses.from_sleap_file("/path/to/file.predictions.slp", 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)
 
@@ -108,38 +119,44 @@ ds = load_poses.from_file(
 
 Because LightningPose follows the DeepLabCut dataframe format, you can also
 directly load an appropriately formatted pandas DataFrame `df`:
+
 ```python
 ds = load_poses.from_dlc_style_df(df, fps=30, source_software="LightningPose")
 ```
+
 :::
 
 :::{tab-item} Anipose
 To load Anipose files in .csv format:
+
 ```python
 ds = load_poses.from_anipose_file(
-    "/path/to/file.analysis.csv", fps=30, individual_name="individual_0"
-)  # Optionally specify the individual name; defaults to "individual_0"
+    "/path/to/file.analysis.csv", fps=30, individual_name="id_0"
+)  # Optionally specify the individual name; defaults to "id_0"
 
 # or equivalently
 ds = load_poses.from_file(
     "/path/to/file.analysis.csv",
     source_software="Anipose",
     fps=30,
-    individual_name="individual_0",
+    individual_name="id_0",
 )
 ```
 
 You can also directly load any pandas DataFrame `df` that's
 formatted in the Anipose triangulation style:
+
 ```python
 ds = load_poses.from_anipose_style_df(
-    df, fps=30, individual_name="individual_0"
+    df, fps=30, individual_name="id_0"
 )
 ```
+
 :::
 
 :::{tab-item} NWB
 To load NWB files in .nwb format:
+
 ```python
 ds = load_poses.from_nwb_file(
     "path/to/file.nwb",
@@ -157,19 +174,23 @@ ds = load_poses.from_file(
     pose_estimation_key="PoseEstimation",
 )
 ```
+
 The above functions also accept an {class}`NWBFile<pynwb.file.NWBFile>` object as input:
+
 ```python
 with pynwb.NWBHDF5IO("path/to/file.nwb", mode="r") as io:
     nwb_file = io.read()
     ds = load_poses.from_nwb_file(
         nwb_file, pose_estimation_key="PoseEstimation"
     )
 ```
+
 :::
 
 :::{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.
+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.
+
 ```python
 import numpy as np
 
@@ -182,6 +203,7 @@ ds = load_poses.from_numpy(
     fps=30,
 )
 ```
+
 :::
 
 ::::
@@ -192,9 +214,10 @@ the pose estimation software.
 
 For more information on the poses data structure, see the [movement datasets](target-poses-and-bboxes-dataset) page.
 
-
 (target-loading-bbox-tracks)=
+
 ### Loading bounding box tracks
+
 To load bounding box tracks into a [movement bounding boxes dataset](target-poses-and-bboxes-dataset), we need the functions from the
 {mod}`movement.io.load_bboxes` module, which can be imported as follows:
 
@@ -207,6 +230,7 @@ We currently support loading bounding box tracks in the VGG Image Annotator (VIA
 ::::{tab-set}
 :::{tab-item} VGG Image Annotator
 To load a VIA tracks .csv file:
+
 ```python
 ds = load_bboxes.from_via_tracks_file("path/to/file.csv", fps=30)
 
@@ -217,12 +241,14 @@ ds = load_bboxes.from_file(
     fps=30,
 )
 ```
-Note that the x,y coordinates in the input VIA tracks .csv file represent the the top-left corner of each bounding box. Instead the corresponding ``movement`` dataset `ds` will hold in its `position` array the centroid of each bounding box.
+
+Note that the x,y coordinates in the input VIA tracks .csv file represent the the top-left corner of each bounding box. Instead the corresponding `movement` dataset `ds` will hold in its `position` array the centroid of each bounding box.
 :::
 
 :::{tab-item} From NumPy
-In the example below, we create random position data for two bounding boxes, ``id_0`` and ``id_1``,
+In the example below, we create random position data for two bounding boxes, `id_0` and `id_1`,
 both with the same width (40 pixels) and height (30 pixels). These are tracked in 2D space for 100 frames, which will be numbered in the resulting dataset from 0 to 99. The confidence score for all bounding boxes is set to 0.5.
+
 ```python
 import numpy as np
 
@@ -234,6 +260,7 @@ ds = load_bboxes.from_numpy(
     individual_names=["id_0", "id_1"]
 )
 ```
+
 :::
 
 ::::
@@ -242,8 +269,8 @@ The resulting data structure `ds` will include the centroid trajectories for eac
 
 For more information on the bounding boxes data structure, see the [movement datasets](target-poses-and-bboxes-dataset) page.
 
-
 (target-saving-pose-tracks)=
+
 ### Saving pose tracks
 
 To export [movement poses datasets](target-poses-and-bboxes-dataset) to any of the supported third-party formats,
@@ -259,20 +286,24 @@ Depending on the desired format, use one of the following functions:
 
 ::::{tab-item} DeepLabCut
 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")
 ```
+
 The {func}`movement.io.save_poses.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.
 ::::
 
 ::::{tab-item} SLEAP
 To save as a SLEAP analysis file in .h5 format:
+
 ```python
 save_poses.to_sleap_analysis_file(ds, "/path/to/file.h5")
 ```
+
 When saving to SLEAP-style files, only `track_names`, `node_names`, `tracks`, `track_occupancy`,
 and `point_scores` are saved. `labels_path` will only be saved if the source
 file of the dataset is a SLEAP .slp file. Otherwise, it will be an empty string.
@@ -285,44 +316,51 @@ each attribute and data variable represents, see the
 
 ::::{tab-item} LightningPose
 To save as a LightningPose file in .csv format:
+
 ```python
 save_poses.to_lp_file(ds, "/path/to/file.csv")
 ```
 
 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)
 ```
+
 ::::
 
 ::::{tab-item} NWB
 To convert a `movement` poses dataset to {class}`NWBFile<pynwb.file.NWBFile>` objects:
+
 ```python
 nwb_files = save_poses.to_nwb_file(ds)
 ```
+
 To allow adding additional data to NWB files before saving, {func}`to_nwb_file<movement.io.save_poses.to_nwb_file>` does not write to disk directly.
 Instead, it returns a list of {class}`NWBFile<pynwb.file.NWBFile>` objects---one per individual in the dataset---since NWB files are designed to represent data from a single individual.
 
 The {func}`to_nwb_file<movement.io.save_poses.to_nwb_file>` function also accepts
-a {class}`NWBFileSaveConfig<movement.io.nwb.NWBFileSaveConfig>` object as its ``config`` argument
+a {class}`NWBFileSaveConfig<movement.io.nwb.NWBFileSaveConfig>` object as its `config` argument
 for customising metadata such as session or subject information in the resulting NWBFiles
 (see {func}`the API reference<movement.io.save_poses.to_nwb_file>` for examples).
 
 These {class}`NWBFile<pynwb.file.NWBFile>` objects can then be saved to disk as .nwb files using {class}`pynwb.NWBHDF5IO`:
+
 ```python
 from pynwb import NWBHDF5IO
 
 for file in nwb_files:
     with NWBHDF5IO(f"{file.identifier}.nwb", "w") as io:
         io.write(file)
 ```
+
 ::::
 
 :::::
 
-
 (target-saving-bboxes-tracks)=
+
 ### Saving bounding box tracks
 
 We currently do not provide explicit methods to export a movement bounding boxes dataset in a specific format. However, you can save the bounding box tracks to a .csv file using the standard Python library `csv`.
@@ -349,9 +387,11 @@ with open(filepath, mode="w", newline="") as file:
             writer.writerow([frame, individual, x, y, width, height, confidence])
 
 ```
+
 Alternatively, we can convert the `movement` bounding boxes dataset to a pandas DataFrame with the {meth}`xarray.DataArray.to_dataframe` method, wrangle the dataframe as required, and then apply the {meth}`pandas.DataFrame.to_csv` method to save the data as a .csv file.
 
 (target-netcdf)=
+
 ## Native saving and loading with netCDF
 
 Because `movement` datasets are {class}`xarray.Dataset` objects, we can rely on
@@ -367,7 +407,7 @@ To save any xarray dataset `ds` to a netCDF file:
 
 ```python
 ds.to_netcdf("/path/to/my_data.nc")
-````
+```
 
 To load the dataset back:
 
@@ -416,8 +456,8 @@ ds["speed"] = compute_speed(ds["position_smooth"])
 ds.to_netcdf("my_data_processed.nc")
 ```
 
-
 (target-sample-data)=
+
 ## Sample data
 
 `movement` includes some sample data files that you can use to
@@ -444,6 +484,7 @@ To load one of the sample files as a
 filename = "SLEAP_three-mice_Aeon_proofread.analysis.h5"
 ds = sample_data.fetch_dataset(filename)
 ```
+
 Some sample datasets also have an associated video file
 (the video for which the data was predicted). You can request
 to download the sample video by setting `with_video=True`:

examples/smooth.py

@@ -49,11 +49,14 @@
 def plot_raw_and_smooth_timeseries_and_psd(
     ds_raw,
     ds_smooth,
-    individual="individual_0",
+    individual=None,
     keypoint="stinger",
     space="x",
     time_range=None,
 ):
+    # If no individual is specified, use the first one
+    if individual is None:
+        individual = ds_raw.individuals[0]
     # If no time range is specified, plot the entire time series
     if time_range is None:
         time_range = slice(0, ds_raw.time[-1])