Merge branch 'main' into feat/bidirectional-displacement-filter

Author: demoncoder-crypto

CONTRIBUTING.md

@@ -3,7 +3,6 @@
 ## Contributing code
 
 ### Creating a development environment
-
 It is recommended to use [conda](conda:)
 or [mamba](mamba:) to create a
 development environment for movement. In the following we assume you have
@@ -34,7 +33,6 @@ pre-commit install
 ```
 
 ### Pull requests
-
 In all cases, please submit code to the main repository via a pull request (PR).
 We recommend, and adhere, to the following conventions:
 
@@ -62,7 +60,6 @@ A typical PR workflow would be:
 ## Development guidelines
 
 ### Formatting and pre-commit hooks
-
 Running `pre-commit install` will set up [pre-commit hooks](https://pre-commit.com/) to ensure a consistent formatting style. Currently, these include:
 * [ruff](https://github.com/astral-sh/ruff) does a number of jobs, including code linting and auto-formatting.
 * [mypy](https://mypy.readthedocs.io/en/stable/index.html) as a static type checker.
@@ -109,7 +106,6 @@ Make sure to provide docstrings for all public functions, classes, and methods.
 This is important as it allows for [automatic generation of the API reference](#updating-the-api-reference).
 
 ### Testing
-
 We use [pytest](https://docs.pytest.org/en/latest/) for testing and aim for
 ~100% test coverage (as far as is reasonable).
 All new features should be tested.
@@ -120,6 +116,31 @@ Do not include these data in the repository, especially if they are large.
 We store several sample datasets in an external data repository.
 See [sample data](#sample-data) for more information.
 
+### Logging
+We use the {mod}`loguru<loguru._logger>`-based {class}`MovementLogger<movement.utils.logging.MovementLogger>` for logging.
+The logger is configured to write logs to a rotating log file at the `DEBUG` level and to {obj}`sys.stderr` at the `WARNING` level.
+
+To import the logger:
+```python
+from movement.utils.logging import logger
+```
+
+Once the logger is imported, you can log messages with the appropriate [severity levels](inv:loguru#levels) using the same syntax as {mod}`loguru<loguru._logger>` (e.g. `logger.debug("Debug message")`, `logger.warning("Warning message")`).
+
+#### Logging and raising exceptions
+Both {meth}`logger.error()<movement.utils.logging.MovementLogger.error>` and {meth}`logger.exception()<movement.utils.logging.MovementLogger.exception>` can be used to log [](inv:python#tut-errors), with the difference that the latter will include the traceback in the log message.
+As these methods will return the logged Exception, you can log and raise the Exception in a single line:
+```python
+raise logger.error(ValueError("message"))
+raise logger.exception(ValueError("message")) # with traceback
+```
+
+#### When to use `print`, `warnings.warn`, and `logger.warning`
+We aim to adhere to the [When to use logging guide](inv:python#logging-basic-tutorial) to ensure consistency in our logging practices.
+In general:
+* Use {func}`print` for simple, non-critical messages that do not need to be logged.
+* Use {func}`warnings.warn` for user input issues that are non-critical and can be addressed within movement, e.g. deprecated function calls that are redirected, invalid `fps` number in {class}`ValidPosesDataset<movement.validators.datasets.ValidPosesDataset>` that is implicitly set to `None`; or when processing data containing excessive NaNs, which the user can potentially address using appropriate methods, e.g. {func}`interpolate_over_time()<movement.filtering.interpolate_over_time>`
+* Use {meth}`logger.warning()<loguru._logger.Logger.warning>` for non-critical issues where default values are assigned to optional parameters, e.g. `individual_names`, `keypoint_names` in {class}`ValidPosesDataset<movement.validators.datasets.ValidPosesDataset>`.
 
 ### Continuous integration
 All pushes and pull requests will be built by [GitHub actions](github-docs:actions).
@@ -155,7 +176,6 @@ The addition of a GitHub tag triggers the package's deployment to PyPI.
 The version number is automatically determined from the latest tag on the _main_ branch.
 
 ## Contributing documentation
-
 The documentation is hosted via [GitHub pages](https://pages.github.com/) at
 [movement.neuroinformatics.dev](target-movement).
 Its source files are located in the `docs` folder of this repository.
@@ -173,7 +193,6 @@ ensuring that the documentation is published in sync with each PyPI release.
 
 
 ### Editing the documentation
-
 To edit the documentation, first clone the repository, and install `movement` in a
 [development environment](#creating-a-development-environment).
 
@@ -279,7 +298,6 @@ For example, to reference the {meth}`xarray.Dataset.update` method, use:
 :::
 ::::
 
-
 ### Building the documentation locally
 We recommend that you build and view the documentation website locally, before you push your proposed changes.
 
@@ -338,7 +356,6 @@ make clean html linkcheck
 :::
 
 ## Sample data
-
 We maintain some sample datasets to be used for testing, examples and tutorials on an
 [external data repository](gin:neuroinformatics/movement-test-data).
 Our hosting platform of choice is called [GIN](gin:) and is maintained
@@ -409,8 +426,6 @@ To add a new file, you will need to:
 
 9. Upload the committed changes to the GIN repository by running `gin upload`. Latest changes to the repository can be pulled via `gin download`. `gin sync` will synchronise the latest changes bidirectionally.
 
-
-
 ### `metadata.yaml` example entry
 ```yaml
 "SLEAP_three-mice_Aeon_proofread.analysis.h5":

docs/source/community/roadmaps.md

@@ -19,7 +19,16 @@ The following features are being considered for the first stable version `v1.0`.
 navigation, social interactions, etc.
 - __Integrate with neurophysiological data analysis tools__. We eventually aim to facilitate combined analysis of motion and neural data.
 
-## Short-term milestone - `v0.1`
+## Focus areas for 2025
+
+- Annotate space by defining regions of interest programmatically and via our [GUI](target-gui).
+- Annotate time by defining events of interest programmatically and via our [GUI](target-gui).
+- Enable workflows for aligning motion tracks with concurrently recorded neurophysiological signals.
+- Enrich the interactive visualisation of motion tracks in `napari`, providing more customisation options.
+- Enable the saving of filtered tracks and derived kinematic variables to disk.
+- Implement metrics useful for analysing spatial navigation, social interactions, and collective behaviour.
+
+## Version 0.1
 We've released version `v0.1` of `movement` in March 2025, providing a basic set of features to demonstrate the project's potential and to gather feedback from users. Our minimum requirements for this milestone were:
 
 - [x] Ability to import pose tracks from [DeepLabCut](dlc:), [SLEAP](sleap:) and [LightningPose](lp:) into a common `xarray.Dataset` structure.

docs/source/conf.py

@@ -211,6 +211,8 @@
     "xarray": ("https://docs.xarray.dev/en/stable/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "python": ("https://docs.python.org/3", None),
+    "loguru": ("https://loguru.readthedocs.io/en/stable/", None),
 }
 
 

movement/__init__.py

@@ -1,10 +1,10 @@
 from importlib.metadata import PackageNotFoundError, version
 
-from movement.utils.logging import configure_logging
+from movement.utils.logging import logger
 
 try:
     __version__ = version("movement")
-except PackageNotFoundError:
+except PackageNotFoundError:  # pragma: no cover
     # package is not installed
     pass
 
@@ -13,5 +13,5 @@
 
 xr.set_options(keep_attrs=True, display_expand_data=False)
 
-# initialize logger upon import
-configure_logging()
+# Configure logging to stderr and a file
+logger.configure()

movement/filtering.py

@@ -6,8 +6,12 @@
 import xarray as xr
 from scipy import signal
 
+
 from movement.kinematics import compute_displacement
 from movement.utils.logging import log_to_attrs
+
+from movement.utils.logging import log_to_attrs, logger
+
 from movement.utils.reports import report_nan_values
 from movement.utils.vector import compute_norm
 
@@ -273,10 +277,16 @@ def rolling_filter(
 
     # Compute the statistic over each window
     allowed_statistics = ["mean", "median", "max", "min"]
-    if statistic not in allowed_statistics:
         raise ValueError(
             f"Invalid statistic '{statistic}'. "
             f"Must be one of {allowed_statistics}.",
+
+        raise logger.error(
+            ValueError(
+                f"Invalid statistic '{statistic}'. "
+                f"Must be one of {allowed_statistics}."
+            )
+
         )
 
     data_rolled = getattr(data_windows, statistic)(skipna=True)
@@ -343,7 +353,13 @@ def savgol_filter(
 
     """
     if "axis" in kwargs:
+
         raise ValueError("The 'axis' argument may not be overridden.")
+
+        raise logger.error(
+            ValueError("The 'axis' argument may not be overridden.")
+        )
+
     data_smoothed = data.copy()
     data_smoothed.values = signal.savgol_filter(
         data,

movement/io/load_bboxes.py

@@ -1,7 +1,6 @@
 """Load bounding boxes tracking data into ``movement``."""
 
 import ast
-import logging
 import re
 from collections.abc import Callable
 from pathlib import Path
@@ -11,16 +10,14 @@
 import pandas as pd
 import xarray as xr
 
-from movement.utils.logging import log_error
+from movement.utils.logging import logger
 from movement.validators.datasets import ValidBboxesDataset
 from movement.validators.files import (
     DEFAULT_FRAME_REGEXP,
     ValidFile,
     ValidVIATracksCSV,
 )
 
-logger = logging.getLogger(__name__)
-
 
 def from_numpy(
     position_array: np.ndarray,
@@ -229,8 +226,8 @@ def from_file(
             frame_regexp=frame_regexp,
         )
     else:
-        raise log_error(
-            ValueError, f"Unsupported source software: {source_software}"
+        raise logger.error(
+            ValueError(f"Unsupported source software: {source_software}")
         )
 
 
@@ -337,7 +334,7 @@ def from_via_tracks_file(
 
     # Specific VIA-tracks .csv file validation
     via_file = ValidVIATracksCSV(file.path, frame_regexp=frame_regexp)
-    logger.debug(f"Validated VIA tracks .csv file {via_file.path}.")
+    logger.info(f"Validated VIA tracks .csv file {via_file.path}.")
 
     # Create an xarray.Dataset from the data
     bboxes_arrays = _numpy_arrays_from_via_tracks_file(
@@ -363,8 +360,7 @@ def from_via_tracks_file(
     ds.attrs["source_software"] = "VIA-tracks"
     ds.attrs["source_file"] = file.path.as_posix()
 
-    logger.info(f"Loaded tracks of the bounding boxes from {via_file.path}:")
-    logger.info(ds)
+    logger.info(f"Loaded bounding boxes tracks from {via_file.path}:\n{ds}")
     return ds
 
 

movement/io/load_poses.py

@@ -1,6 +1,5 @@
 """Load pose tracking data from various frameworks into ``movement``."""
 
-import logging
 from pathlib import Path
 from typing import Literal
 
@@ -11,7 +10,7 @@
 from sleap_io.io.slp import read_labels
 from sleap_io.model.labels import Labels
 
-from movement.utils.logging import log_error, log_warning
+from movement.utils.logging import logger
 from movement.validators.datasets import ValidPosesDataset
 from movement.validators.files import (
     ValidAniposeCSV,
@@ -20,8 +19,6 @@
     ValidHDF5,
 )
 
-logger = logging.getLogger(__name__)
-
 
 def from_numpy(
     position_array: np.ndarray,
@@ -151,8 +148,8 @@ def from_file(
     elif source_software == "Anipose":
         return from_anipose_file(file_path, fps, **kwargs)
     else:
-        raise log_error(
-            ValueError, f"Unsupported source software: {source_software}"
+        raise logger.error(
+            ValueError(f"Unsupported source software: {source_software}")
         )
 
 
@@ -291,8 +288,7 @@ def from_sleap_file(
         ds = _ds_from_sleap_labels_file(file.path, fps=fps)
     # Add metadata as attrs
     ds.attrs["source_file"] = file.path.as_posix()
-    logger.info(f"Loaded pose tracks from {file.path}:")
-    logger.info(ds)
+    logger.info(f"Loaded pose tracks from {file.path}:\n{ds}")
     return ds
 
 
@@ -436,8 +432,7 @@ def _ds_from_lp_or_dlc_file(
     ds = from_dlc_style_df(df=df, fps=fps, source_software=source_software)
     # Add metadata as attrs
     ds.attrs["source_file"] = file.path.as_posix()
-    logger.info(f"Loaded pose tracks from {file.path}:")
-    logger.info(ds)
+    logger.info(f"Loaded pose tracks from {file.path}:\n{ds}")
     return ds
 
 
@@ -469,7 +464,7 @@ def _ds_from_sleap_analysis_file(
         scores = np.full(tracks.shape[:1] + tracks.shape[2:], np.nan)
         individual_names = [n.decode() for n in f["track_names"][:]] or None
         if individual_names is None:
-            log_warning(
+            logger.warning(
                 f"Could not find SLEAP Track in {file.path}. "
                 "Assuming single-individual dataset and assigning "
                 "default individual name."
@@ -513,7 +508,7 @@ def _ds_from_sleap_labels_file(
     tracks_with_scores = _sleap_labels_to_numpy(labels)
     individual_names = [track.name for track in labels.tracks] or None
     if individual_names is None:
-        log_warning(
+        logger.warning(
             f"Could not find SLEAP Track in {file.path}. "
             "Assuming single-individual dataset and assigning "
             "default individual name."

movement/io/save_poses.py

@@ -1,6 +1,5 @@
 """Save pose tracking data from ``movement`` to various file formats."""
 
-import logging
 from pathlib import Path
 from typing import Literal
 
@@ -9,12 +8,10 @@
 import pandas as pd
 import xarray as xr
 
-from movement.utils.logging import log_error
+from movement.utils.logging import logger
 from movement.validators.datasets import ValidPosesDataset
 from movement.validators.files import ValidFile
 
-logger = logging.getLogger(__name__)
-
 
 def _ds_to_dlc_style_df(
     ds: xr.Dataset, columns: pd.MultiIndex
@@ -201,10 +198,11 @@ def to_dlc_file(
         split_individuals = _auto_split_individuals(ds)
 
     elif not isinstance(split_individuals, bool):
-        raise log_error(
-            ValueError,
-            "Expected 'split_individuals' to be a boolean or 'auto', but got "
-            f"{type(split_individuals)}.",
+        raise logger.error(
+            ValueError(
+                "Expected 'split_individuals' to be a boolean or 'auto', "
+                f"but got {type(split_individuals)}."
+            )
         )
 
     if split_individuals:
@@ -417,7 +415,7 @@ def _validate_file_path(
         )
     except (OSError, ValueError) as error:
         logger.error(error)
-        raise error
+        raise
     return file
 
 
@@ -438,8 +436,8 @@ def _validate_dataset(ds: xr.Dataset) -> None:
 
     """
     if not isinstance(ds, xr.Dataset):
-        raise log_error(
-            TypeError, f"Expected an xarray Dataset, but got {type(ds)}."
+        raise logger.error(
+            TypeError(f"Expected an xarray Dataset, but got {type(ds)}.")
         )
 
     missing_vars = set(ValidPosesDataset.VAR_NAMES) - set(ds.data_vars)