refactoring & documentation

André Böni · André Böni · commit 984624ff5b70 · 2025-01-06T15:06:43.000+01:00
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -2,6 +2,13 @@
 Changelog
 =========
 
+0.2.2
+------------------
+- Added better support for extensions and custom metrics
+- Refine implementation of MoS metric according to the the latest findings
+- Fixed bug resolving dependencies with conda main channel
+
+
 0.2.1
 ------------------
 - Added minimal toe clearance metric
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -21,6 +21,7 @@ gaitalytics could always use more documentation, whether as part of the
 official gaitalytics docs, in docstrings, or even on the web in blog posts,
 articles, and such.
 
+
 Feature requests and feedback
 =============================
 
@@ -32,6 +33,8 @@ If you are proposing a feature:
 * Keep the scope as narrow as possible, to make it easier to implement.
 * Remember that this is a volunteer-driven project, and that code contributions are welcome :)
 
+.. _Development:
+
 Development
 ===========
 
diff --git a/README.rst b/README.rst
@@ -69,9 +69,6 @@ Fast install with anaconda:
     conda install gaitalytics -c DartLab-LLUI
 ..
 
-.. warning::
-        | To avoid dependencies issues, make sure conda-forge is the first channel in your conda configuration.
-
 Or with pip:
 
 .. code:: shell
@@ -170,4 +167,6 @@ Simple Pipeline
 Documentation
 -------------
 https://python-gaitalytics.readthedocs.org
-
+https://github.com/DART-Lab-LLUI/python-gaitalytics
+https://pypi.org/project/gaitalytics/
+https://anaconda.org/dartlab-llui/gaitalytics
diff --git a/docs/conf.py b/docs/conf.py
@@ -20,7 +20,8 @@
 extensions = ['sphinx.ext.autodoc',
               'sphinx_codeautolink',
               'sphinxcontrib.bibtex',
-              'sphinx.ext.napoleon',]
+              'sphinx.ext.napoleon',
+              'sphinxcontrib.mermaid',]
 
 bibtex_bibfiles = ['_static/Gaitalytics.bib']
 
diff --git a/docs/extend/features.rst b/docs/extend/features.rst
@@ -0,0 +1,46 @@
+.. meta::
+   :description: Gaitalytics Feature.
+   :keywords: gaitalytics, gait-analysis, mocap, c3d, gait-metrics, biomechanics, time-series, data-analysis, data, gait, references
+
+Extend features
+===============
+
+.. warning::
+    Gaitalytics is build to be independent on marker-models and modelling mechanisms through :ref:`configurations <Configuration>`.
+    In this Tutorial we will not cover the creation of new :ref:`mapping configurations <Config Mapping>` since it will alter core functionality of the library.
+    Your new features therefore may not work within different setups. To make your features available to the community and integrated to gaitalytics,
+    please consider :ref:`contributing <Development>` to the project and our staff will take care of the integration.
+
+Before you start creating new features, you should think about the following questions:
+
+     - Will my feature be calculated for each gait cycle?
+     - Are all the needed markers defined through the :ref:`mappings  <Config Mapping>`?
+
+If you have answered all the questions, you can start creating your new feature.
+
+Class inheritance
+-----------------
+
+With with your answers in mind, you can now decide which class you want to inherit from. The following classes are available in the library:
+
+    - :class:`gaitalytics.features.FeatureCalculation`
+    - :class:`gaitalytics.features.CycleFeaturesCalculation`
+    - :class:`gaitalytics.features.PointDependentFeature`
+
+The following flowchart will help you to decide which class you should inherit from:
+
+.. mermaid::
+
+    flowchart LR
+        A{Per cycle?}---|Yes|B{Mapped markers?}
+        A---|No|FeatureCalculation
+        B---|Yes|PointDependentFeature
+        B---|No|CycleFeaturesCalculation
+
+..
+
+
+
+
+
+
diff --git a/docs/extend/index.rst b/docs/extend/index.rst
@@ -0,0 +1,22 @@
+.. meta::
+   :description: Gaitalytics Extensions.
+   :keywords: gaitalytics, gait-analysis, mocap, c3d, gait-metrics, biomechanics, time-series, data-analysis, data, gait, guide, extend
+
+Extend Functionality
+====================
+Gaitalytics is build to be extensible and flexible. You can extend the functionality of the framework by adding new features or new event detection algorithms.
+In the following pages, we will explain how you can extend the functionality of Gaitalytics for your specific needs.
+Additionally, you can also make your extensions available to the community by :ref:`contributing <Development>` to the project.
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   features
+
+..
+
+
+
+
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -18,6 +18,7 @@
    usage/index
    api
    reference/index
+   extend/index
    contributing
    authors
    changelog
diff --git a/docs/usage/data_loading.rst b/docs/usage/data_loading.rst
@@ -26,6 +26,7 @@ Here is an example of how to load a c3d file and the corresponding configuration
 
 ..
 
+.. _Configuration:
 
 Configuration
 -------------
diff --git a/gaitalytics/features.py b/gaitalytics/features.py
@@ -45,7 +45,7 @@ def calculate(self, trial: model.TrialCycles) -> xr.DataArray:
         raise NotImplementedError
 
 
-class _CycleFeaturesCalculation(FeatureCalculation, ABC):
+class CycleFeaturesCalculation(FeatureCalculation, ABC):
     def calculate(self, trial: model.TrialCycles) -> xr.DataArray:
         """Calculate the features for a trial.
 
@@ -87,6 +87,8 @@ def _calculate(self, trial: model.Trial) -> xr.DataArray:
 
         Returns:
             An xarray DataArray containing the calculated features.
+
+        :meta public:
         """
         raise NotImplementedError
 
@@ -211,7 +213,7 @@ def _flatten_features(features: xr.DataArray) -> xr.DataArray:
         return new_format
 
 
-class _PointDependentFeature(_CycleFeaturesCalculation, ABC):
+class PointDependentFeature(CycleFeaturesCalculation, ABC):
     def _get_marker_data(
         self, trial: model.Trial, marker: mapping.MappedMarkers
     ) -> xr.DataArray:
@@ -223,6 +225,8 @@ def _get_marker_data(
 
         Returns:
             An xarray DataArray containing the marker data.
+
+        :meta public:
         """
         return mocap.get_marker_data(trial, self._config, marker)
 
@@ -237,6 +241,8 @@ def _get_sacrum_marker(self, trial: model.Trial) -> xr.DataArray:
 
         Returns:
             An xarray DataArray containing the sacrum marker data.
+
+        :meta public:
         """
         return mocap.get_sacrum_marker(trial, self._config)
 
@@ -270,7 +276,9 @@ def _get_sagittal_vector(self, trial: model.Trial) -> xr.DataArray:
         return linalg.get_normal_vector(progression_vector, vertical_vector)
 
 
-class TimeSeriesFeatures(_CycleFeaturesCalculation):
+
+
+class TimeSeriesFeatures(CycleFeaturesCalculation):
     """Calculate time series features for a trial.
 
     This class calculates following time series features for a trial.
@@ -420,7 +428,7 @@ def _create_phase_trial(trial: model.Trial, time_slice: slice):
         return phase_trial
 
 
-class TemporalFeatures(_CycleFeaturesCalculation):
+class TemporalFeatures(CycleFeaturesCalculation):
     """Calculate temporal features for a trial.
 
     This class calculates following temporal features for a trial.
@@ -499,7 +507,7 @@ def _calculate_supports(
         return {"double_support": double_support, "single_support": single_support}
 
 
-class SpatialFeatures(_PointDependentFeature):
+class SpatialFeatures(PointDependentFeature):
     """Calculate spatial features for a trial.
 
     This class calculates following spatial features for a trial.
diff --git a/pixi.lock b/pixi.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -57,7 +57,8 @@ docs = ["sphinx",
     "sphinx-autodoc-typehints",
     "sphinx_github_changelog",
     "sphinx-codeautolink",
-    "sphinxcontrib-bibtex"]
+    "sphinxcontrib-bibtex",
+    "sphinxcontrib-mermaid",]
 
 [tool.pixi.project]
 channels = ["conda-forge"]
