paradigma 1.0.4__py3-none-any.whl → 1.1.0__py3-none-any.whl

paradigma/segmenting.py

@@ -1,5 +1,3 @@
-from typing import List
-
 import numpy as np
 import pandas as pd
 
@@ -9,19 +7,21 @@ from paradigma.util import deprecated
 
 def tabulate_windows(
     df: pd.DataFrame,
-    columns: List[str],
+    columns: list[str],
     window_length_s: float,
     window_step_length_s: float,
     fs: int,
 ) -> np.ndarray:
     """
-    Split the given DataFrame into overlapping windows of specified length and step size.
+    Split the given DataFrame into overlapping windows of specified length
+    and step size.
 
-    This function extracts windows of data from the specified columns of the DataFrame, based on
-    the window length and step size provided in the configuration. The windows are returned in
-    a 3D NumPy array, where the first dimension represents the window index, the second dimension
-    represents the time steps within the window, and the third dimension represents the columns
-    of the data.
+    This function extracts windows of data from the specified columns of the
+    DataFrame, based on the window length and step size provided in the
+    configuration. The windows are returned in a 3D NumPy array, where the
+    first dimension represents the window index, the second dimension
+    represents the time steps within the window, and the third dimension
+    represents the columns of the data.
 
     Parameters
     ----------
@@ -40,17 +40,22 @@ def tabulate_windows(
     -------
     np.ndarray
         A 3D NumPy array of shape (n_windows, window_size, n_columns), where:
-        - `n_windows` is the number of windows that can be formed from the data.
-        - `window_size` is the length of each window in terms of the number of time steps.
-        - `n_columns` is the number of columns in the input DataFrame specified by `columns`.
+        - `n_windows` is the number of windows that can be formed from the
+          data.
+        - `window_size` is the length of each window in terms of the number
+          of time steps.
+        - `n_columns` is the number of columns in the input DataFrame
+          specified by `columns`.
 
-        If the length of the data is shorter than the specified window size, an empty array is returned.
+        If the length of the data is shorter than the specified window size,
+        an empty array is returned.
 
     Notes
     -----
-    This function uses `np.lib.stride_tricks.sliding_window_view` to generate sliding windows of data.
-    The step size is applied to extract windows at intervals.
-    If the data is insufficient for at least one window, an empty array will be returned.
+    This function uses `np.lib.stride_tricks.sliding_window_view` to
+    generate sliding windows of data. The step size is applied to extract
+    windows at intervals. If the data is insufficient for at least one
+    window, an empty array will be returned.
 
     Example
     -------
@@ -84,7 +89,8 @@ def tabulate_windows(
 
 def tabulate_windows_legacy(config, df, agg_func="first"):
     """
-    Efficiently creates a windowed dataframe from the input dataframe using vectorized operations.
+    Efficiently creates a windowed dataframe from the input dataframe using
+    vectorized operations.
 
     Parameters
     ----------
@@ -93,11 +99,13 @@ def tabulate_windows_legacy(config, df, agg_func="first"):
         - `window_length_s`: The number of seconds per window.
         - `window_step_length_s`: The number of seconds to shift between windows.
         - `sampling_frequency`: The sampling frequency in Hz.
-        - `single_value_colnames`: List of column names where a single value (e.g., mean) is needed.
-        - `list_value_colnames`: List of column names where all 600 values should be stored in a list.
+        - `single_value_colnames`: List of column names where a single value
+          (e.g., mean) is needed.
+        - `list_value_colnames`: List of column names where all 600 values
+          should be stored in a list.
     agg_func : str or callable, optional
-        Aggregation function for single-value columns. Can be 'mean', 'first', or a custom callable.
-        Default is 'first'.
+        Aggregation function for single-value columns. Can be 'mean',
+        'first', or a custom callable. Default is 'first'.
 
     Returns
     -------
@@ -122,7 +130,8 @@ def tabulate_windows_legacy(config, df, agg_func="first"):
     n_rows = len(df)
     if window_length > n_rows:
         raise ValueError(
-            f"Window size ({window_length}) cannot be greater than the number of rows ({n_rows}) in the dataframe."
+            f"Window size ({window_length}) cannot be greater than the "
+            f"number of rows ({n_rows}) in the dataframe."
         )
 
     # Create indices for window start positions
@@ -170,7 +179,8 @@ def tabulate_windows_legacy(config, df, agg_func="first"):
     # Convert result list into a DataFrame
     windowed_df = pd.DataFrame(result)
 
-    # Ensure the column order is as desired: window_nr, window_start, window_end, pre_or_post, and then the rest
+    # Ensure the column order is as desired: window_nr, window_start,
+    # window_end, pre_or_post, and then the rest
     desired_order = (
         ["window_nr", "window_start", "window_end"]
         + config.single_value_colnames
@@ -191,7 +201,7 @@ def create_segments(
     gap_exceeds = time_diff > max_segment_gap_s
 
     # Create the segment number based on the cumulative sum of the gap_exceeds mask
-    segments = gap_exceeds.cumsum()
+    segments = gap_exceeds.cumsum() + 1
 
     return segments
 
@@ -229,7 +239,8 @@ def discard_segments(
 
     Example
     -------
-    config = Config(min_segment_length_s=2, sampling_frequency=100, segment_nr_colname='segment')
+    config = Config(min_segment_length_s=2, sampling_frequency=100,
+                    segment_nr_colname='segment')
     df = pd.DataFrame({
         'segment': [1, 1, 2, 2, 2],
         'time': [0, 1, 2, 3, 4]
@@ -245,26 +256,26 @@ def discard_segments(
     """
     # Minimum segment size in number of samples
     if format == "timestamps":
-        min_samples = min_segment_length_s * fs
+        min_samples = int(min_segment_length_s * fs)
     elif format == "windows":
-        min_samples = min_segment_length_s
+        min_samples = int(min_segment_length_s)
     else:
         raise ValueError("Invalid format. Must be 'timestamps' or 'windows'.")
 
-    # Group by segment and filter out small segments in one step
-    valid_segment_mask = (
-        df.groupby(segment_nr_colname)[segment_nr_colname].transform("size")
-        >= min_samples
-    )
+    # Count samples per segment
+    segment_counts = df.groupby(segment_nr_colname).size()
 
-    df = df[valid_segment_mask].copy()
+    # Filter rows for valid segments (>= min samples)
+    counts_map = segment_counts.to_dict()
+    df = df[df[segment_nr_colname].map(counts_map) >= min_samples].copy()
 
     if df.empty:
-        raise ValueError("All segments were removed.")
+        raise ValueError(
+            f"All segments were removed: no segment ≥ {min_samples} samples."
+        )
 
-    # Reset segment numbers in a single step
-    unique_segments = pd.factorize(df[segment_nr_colname])[0] + 1
-    df[segment_nr_colname] = unique_segments
+    # Reset segment numbers
+    df[segment_nr_colname] = pd.factorize(df[segment_nr_colname])[0] + 1
 
     return df
 
@@ -313,7 +324,7 @@ def categorize_segments(df, fs, format="timestamps", window_step_length_s=None):
         d_max_duration = {k: v * fs for k, v in d_max_duration.items()}
 
     # Count rows per segment
-    segment_sizes = df[DataColumns.SEGMENT_NR].value_counts()
+    segment_sizes = df[DataColumns.GAIT_SEGMENT_NR].value_counts()
 
     # Convert segment sizes to duration in seconds
     if format == "windows":
@@ -332,7 +343,10 @@ def categorize_segments(df, fs, format="timestamps", window_step_length_s=None):
 
     # Apply categorization to the DataFrame
     return (
-        df[DataColumns.SEGMENT_NR].map(segment_sizes).map(categorize).astype("category")
+        df[DataColumns.GAIT_SEGMENT_NR]
+        .map(segment_sizes)
+        .map(categorize)
+        .astype("category")
     )
 
 
@@ -354,7 +368,7 @@ class WindowedDataExtractor:
         Returns a slice object for a range of consecutive column names.
     """
 
-    def __init__(self, windowed_colnames: List[str]):
+    def __init__(self, windowed_colnames: list[str]):
         """
         Initialize the WindowedDataExtractor.
 
@@ -395,7 +409,7 @@ class WindowedDataExtractor:
             raise ValueError(f"Column name '{colname}' not found in windowed_colnames.")
         return self.column_indices[colname]
 
-    def get_slice(self, colnames: List[str]) -> slice:
+    def get_slice(self, colnames: list[str]) -> slice:
         """
         Get a slice object for a range of consecutive columns.
 
@@ -412,7 +426,8 @@ class WindowedDataExtractor:
         Raises
         ------
         ValueError
-            If one or more columns in `colnames` are not found in the `windowed_colnames` list.
+            If one or more columns in `colnames` are not found in the
+            `windowed_colnames` list.
         """
         if not all(col in self.column_indices for col in colnames):
             missing = [col for col in colnames if col not in self.column_indices]

paradigma/testing.py

@@ -1,7 +1,6 @@
 import json
 import os
 from pathlib import Path
-from typing import List
 
 import numpy as np
 import pandas as pd
@@ -95,7 +94,8 @@ def preprocess_ppg_data_io(
     imu_config: IMUConfig,
 ) -> None:
     """
-    Preprocess PPG and IMU data by resampling, filtering, and aligning the data segments.
+    Preprocess PPG and IMU data by resampling, filtering, and aligning the
+    data segments.
 
     Parameters
     ----------
@@ -520,13 +520,15 @@ def extract_signal_quality_features_io(
     Parameters
     ----------
     input_path : str | Path
-        The path to the directory containing the preprocessed PPG and accelerometer data.
+        The path to the directory containing the preprocessed PPG and
+        accelerometer data.
     output_path : str | Path
         The path to the directory where the extracted features will be saved.
     ppg_config: PulseRateConfig
         The configuration for the signal quality feature extraction of the ppg signal.
     acc_config: PulseRateConfig
-        The configuration for the signal quality feature extraction of the accelerometer signal.
+        The configuration for the signal quality feature extraction of the
+        accelerometer signal.
 
     Returns
     -------
@@ -589,23 +591,26 @@ def extract_signal_quality_features_io(
 def aggregate_pulse_rate_io(
     full_path_to_input: str | Path,
     full_path_to_output: str | Path,
-    aggregates: List[str] = ["mode", "99p"],
+    aggregates: list[str] = ["mode", "99p"],
 ) -> None:
     """
-    Extract pulse rate from the PPG signal and save the aggregated pulse rate estimates to a file.
+    Extract pulse rate from the PPG signal and save the aggregated pulse rate
+    estimates to a file.
 
     Parameters
     ----------
     input_path : str | Path
         The path to the directory containing the pulse rate estimates.
     output_path : str | Path
-        The path to the directory where the aggregated pulse rate estimates will be saved.
+        The path to the directory where the aggregated pulse rate estimates
+        will be saved.
     aggregates : List[str]
-        The list of aggregation methods to be used for the pulse rate estimates. The default is ['mode', '99p'].
+        The list of aggregation methods to be used for the pulse rate
+        estimates. The default is ['mode', '99p'].
     """
 
     # Load the pulse rate estimates
-    with open(full_path_to_input, "r") as f:
+    with open(full_path_to_input) as f:
         df_pr = json.load(f)
 
     # Aggregate the pulse rate estimates

paradigma/util.py

@@ -2,7 +2,6 @@ import functools
 import os
 import warnings
 from datetime import datetime, timedelta
-from typing import List, Optional, Tuple
 
 import numpy as np
 import pandas as pd
@@ -16,12 +15,14 @@ from paradigma.constants import DataColumns, TimeUnit
 
 def deprecated(reason: str = ""):
     """
-    Decorator to mark functions as deprecated. It will show a warning when the function is used.
+    Decorator to mark functions as deprecated. It will show a warning when the
+    function is used.
 
     Parameters
     ----------
     reason : str, optional
-        Additional message to explain why it is deprecated and what to use instead.
+        Additional message to explain why it is deprecated and what to use
+        instead.
     """
 
     def decorator(func):
@@ -155,7 +156,7 @@ def write_df_data(
 
 def read_metadata(
     input_path: str, meta_filename: str, time_filename: str, values_filename: str
-) -> Tuple[TSDFMetadata, TSDFMetadata]:
+) -> tuple[TSDFMetadata, TSDFMetadata]:
     metadata_dict = tsdf.load_metadata_from_path(
         os.path.join(input_path, meta_filename)
     )
@@ -186,8 +187,8 @@ def load_tsdf_dataframe(
 
 
 def load_metadata_list(
-    dir_path: str, meta_filename: str, filenames: List[str]
-) -> List[TSDFMetadata]:
+    dir_path: str, meta_filename: str, filenames: list[str]
+) -> list[TSDFMetadata]:
     """
     Load the metadata objects from a metadata file according to the specified binaries.
 
@@ -216,7 +217,8 @@ def transform_time_array(
     start_time: float = 0.0,
 ) -> np.ndarray:
     """
-    Transforms the time array to relative time (when defined in delta time) and scales the values.
+    Transforms the time array to relative time (when defined in delta time)
+    and scales the values.
 
     Parameters
     ----------
@@ -225,7 +227,8 @@ def transform_time_array(
     input_unit_type : str
         The time unit type of the input time array.
     output_unit_type : str
-        The time unit type of the output time array. ParaDigMa expects `TimeUnit.RELATIVE_S`.
+        The time unit type of the output time array. ParaDigMa expects
+        `TimeUnit.RELATIVE_S`.
     start_time : float, optional
         The start time of the time array in UNIX seconds (default is 0.0)
 
@@ -236,9 +239,13 @@ def transform_time_array(
 
     Notes
     -----
-    - The function handles different time units (`TimeUnit.RELATIVE_MS`, `TimeUnit.RELATIVE_S`, `TimeUnit.ABSOLUTE_MS`, `TimeUnit.ABSOLUTE_S`, `TimeUnit.DIFFERENCE_MS`, `TimeUnit.DIFFERENCE_S`).
-    - The transformation allows for scaling of the time array, converting between time unit types (e.g., relative, absolute, or difference).
-    - When converting to `TimeUnit.RELATIVE_MS`, the function calculates the relative time starting from the provided or default start time.
+    - The function handles different time units (`TimeUnit.RELATIVE_MS`,
+      `TimeUnit.RELATIVE_S`, `TimeUnit.ABSOLUTE_MS`, `TimeUnit.ABSOLUTE_S`,
+      `TimeUnit.DIFFERENCE_MS`, `TimeUnit.DIFFERENCE_S`).
+    - The transformation allows for scaling of the time array, converting
+      between time unit types (e.g., relative, absolute, or difference).
+    - When converting to `TimeUnit.RELATIVE_MS`, the function calculates the
+      relative time starting from the provided or default start time.
     """
     input_units = input_unit_type.split("_")[-1].lower()
     output_units = output_unit_type.split("_")[-1].lower()
@@ -259,7 +266,8 @@ def transform_time_array(
         input_unit_type == TimeUnit.DIFFERENCE_MS
         or input_unit_type == TimeUnit.DIFFERENCE_S
     ):
-        # Convert a series of differences into cumulative sum to reconstruct original time series.
+        # Convert a series of differences into cumulative sum to
+        # reconstruct original time series.
         time_array = np.cumsum(np.double(time_array))
     elif (
         input_unit_type == TimeUnit.ABSOLUTE_MS
@@ -271,7 +279,8 @@ def transform_time_array(
         # Convert absolute time stamps into a time series relative to start_time.
         time_array = time_array - start_time
 
-    # Transform the time array from `TimeUnit.RELATIVE_MS` to the specified time unit type
+    # Transform the time array from `TimeUnit.RELATIVE_MS` to the
+    # specified time unit type
     if (
         output_unit_type == TimeUnit.ABSOLUTE_MS
         or output_unit_type == TimeUnit.ABSOLUTE_S
@@ -282,7 +291,8 @@ def transform_time_array(
         output_unit_type == TimeUnit.DIFFERENCE_MS
         or output_unit_type == TimeUnit.DIFFERENCE_S
     ):
-        # Creates a new array starting with 0, followed by the differences between consecutive elements.
+        # Creates a new array starting with 0, followed by the
+        # differences between consecutive elements.
         time_array = np.diff(np.insert(time_array, 0, start_time))
     elif (
         output_unit_type == TimeUnit.RELATIVE_MS
@@ -383,7 +393,7 @@ def invert_watch_side(df: pd.DataFrame, side: str, sensor="both") -> np.ndarray:
 def aggregate_parameter(
     parameter: np.ndarray,
     aggregate: str,
-    evaluation_points: Optional[np.ndarray] = None,
+    evaluation_points: np.ndarray | None = None,
 ) -> np.ndarray | int:
     """
     Aggregate a parameter based on the specified method.
@@ -398,7 +408,8 @@ def aggregate_parameter(
 
     evaluation_points : np.ndarray, optional
         Should be specified if the mode is derived for a continuous parameter.
-        Defines the evaluation points for the kernel density estimation function, from which the maximum is derived as the mode.
+        Defines the evaluation points for the kernel density estimation
+        function, from which the maximum is derived as the mode.
 
     Returns
     -------
@@ -445,8 +456,9 @@ def merge_predictions_with_timestamps(
     fs: int,
 ) -> pd.DataFrame:
     """
-    Merges prediction probabilities with timestamps by expanding overlapping windows
-    into individual timestamps and averaging probabilities per unique timestamp.
+    Merges prediction probabilities with timestamps by expanding overlapping
+    windows into individual timestamps and averaging probabilities per unique
+    timestamp.
 
     Parameters:
     ----------
@@ -455,10 +467,11 @@ def merge_predictions_with_timestamps(
         Must include the timestamp column specified in `DataColumns.TIME`.
 
     df_predictions : pd.DataFrame
-        DataFrame containing prediction windows with start times and probabilities.
-        Must include:
+        DataFrame containing prediction windows with start times and
+        probabilities. Must include:
         - A column for window start times (defined by `DataColumns.TIME`).
-        - A column for prediction probabilities (defined by `DataColumns.PRED_GAIT_PROBA`).
+        - A column for prediction probabilities (defined by
+          `DataColumns.PRED_GAIT_PROBA`).
 
     pred_proba_colname : str
         The column name for the prediction probabilities in `df_predictions`.
@@ -559,7 +572,8 @@ def select_days(df: pd.DataFrame, min_hours_per_day: int) -> pd.DataFrame:
         Input data with column 'time_dt' in which the date is stored.
 
     min_hours_per_day: int
-        The minimum number of hours per day required for including the day in the aggregation step.
+        The minimum number of hours per day required for including the day
+        in the aggregation step.
 
 
     Returns

paradigma-1.1.0.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: paradigma
+Version: 1.1.0
+Summary: ParaDigMa - A toolbox for deriving Parkinson's disease Digital Markers from real-life wrist sensor data
+License: Apache-2.0
+License-File: LICENSE
+Author: Erik Post
+Author-email: erik.post@radboudumc.nl
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: avro (>=1.12.1,<2.0.0)
+Requires-Dist: nbconvert (>=7.16.6,<8.0.0)
+Requires-Dist: pandas (>=2.1.4,<3.0.0)
+Requires-Dist: pyarrow (>=22.0.0,<23.0.0)
+Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
+Requires-Dist: scikit-learn (>=1.3.2,<1.6.1)
+Requires-Dist: tsdf (>=0.6.1,<0.7.0)
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/biomarkersParkinson/paradigma/main/docs/source/_static/img/paradigma-logo-banner.png" alt="ParaDigMa logo"/>
+</p>
+
+| Badges | |
+|:----:|----|
+| **Packages and Releases** | [![Latest release](https://img.shields.io/github/release/biomarkersparkinson/paradigma.svg)](https://github.com/biomarkersparkinson/paradigma/releases/latest) [![PyPI](https://img.shields.io/pypi/v/paradigma.svg)](https://pypi.python.org/pypi/paradigma/)  [![Static Badge](https://img.shields.io/badge/RSD-paradigma-lib)](https://research-software-directory.org/software/paradigma) |
+| **DOI** | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13838392.svg)](https://doi.org/10.5281/zenodo.13838392) |
+| **Build Status** | [![](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![Build and test](https://github.com/biomarkersParkinson/paradigma/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/biomarkersParkinson/paradigma/actions/workflows/build-and-test.yml) [![pages-build-deployment](https://github.com/biomarkersParkinson/paradigma/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/biomarkersParkinson/paradigma/actions/workflows/pages/pages-build-deployment) |
+| **License** |  [![GitHub license](https://img.shields.io/github/license/biomarkersParkinson/paradigma)](https://github.com/biomarkersparkinson/paradigma/blob/main/LICENSE) |
+
+## Overview
+
+ParaDigMa (Parkinson's disease Digital Markers) is a Python toolbox for extracting validated digital biomarkers from wrist sensor data in Parkinson's disease. It processes accelerometer, gyroscope, and PPG signals collected during passive monitoring in daily life.
+
+**Key Features:**
+- Arm swing during gait analysis
+- Tremor analysis
+- Pulse rate analysis
+- Scientifically validated in peer-reviewed publications
+- Modular, extensible architecture for custom analyses
+
+## Quick Start
+
+### Installation
+
+**For regular use:**
+
+```bash
+pip install paradigma
+```
+
+Requires Python 3.11+.
+
+**For development or running tutorials:**
+
+Example data requires git-lfs. See the [installation guide](https://biomarkersparkinson.github.io/paradigma/guides/installation.html) for setup instructions.
+
+### Basic Usage
+
+```python
+from paradigma.orchestrator import run_paradigma
+
+# Example 1: Single DataFrame with default output directory
+results = run_paradigma(
+    dfs=df,
+    pipelines=['gait', 'tremor'],
+    watch_side='left',  # Required for gait pipeline
+    save_intermediate=['quantification', 'aggregation']  # Saves to ./output by default
+)
+
+# Example 2: Multiple DataFrames as list (assigned to 'df_1', 'df_2', etc.)
+results = run_paradigma(
+    dfs=[df1, df2, df3],
+    pipelines=['gait', 'tremor'],
+    output_dir="./results",  # Custom output directory
+    watch_side='left',
+    save_intermediate=['quantification', 'aggregation']
+)
+
+# Example 3: Dictionary of DataFrames (custom segment/file names)
+results = run_paradigma(
+    dfs={'morning_session': df1, 'evening_session': df2},
+    pipelines=['gait', 'tremor'],
+    watch_side='right',
+    save_intermediate=[]  # No files saved - results only in memory
+)
+
+# Example 4: Load from data directory
+results = run_paradigma(
+    data_path='./my_data',
+    pipelines=['gait', 'tremor'],
+    watch_side='left',
+    file_pattern='*.parquet',
+    save_intermediate=['quantification', 'aggregation']
+)
+
+# Access results (nested by pipeline)
+gait_measures = results['quantifications']['gait']
+tremor_measures = results['quantifications']['tremor']
+gait_aggregates = results['aggregations']['gait']
+tremor_aggregates = results['aggregations']['tremor']
+
+# Check for errors
+if results['errors']:
+    print(f"Warning: {len(results['errors'])} error(s) occurred")
+```
+
+**See our [tutorials](https://biomarkersparkinson.github.io/paradigma/tutorials/index.html) for complete examples.**
+
+## Pipelines
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/biomarkersParkinson/paradigma/main/docs/source/_static/img/pipeline-architecture.png" alt="Pipeline architeecture"/>
+</p>
+
+### Validated Processing Pipelines
+
+| Pipeline | Input sensors | Output week-level aggregation | Publications | Tutorial |
+| ---- | ---- | ------- | ---- | ---- |
+| **Arm swing during gait** | Accelerometer + Gyroscope | Typical, maximum & variability of arm swing range of motion | [Post 2025](https://doi.org/10.1186/s12984-025-01578-z), [Post 2026*](https://doi.org/10.64898/2026.01.06.26343500) | [Guide](https://biomarkersparkinson.github.io/paradigma/tutorials/gait_analysis) |
+| **Tremor** | Gyroscope | % tremor time, typical & maximum tremor power | [Timmermans 2025a](https://doi.org/10.1038/s41531-025-01056-2), [Timmermans 2025b*](https://www.medrxiv.org/content/10.64898/2025.12.23.25342892v1) | [Guide](https://biomarkersparkinson.github.io/paradigma/tutorials/tremor_analysis) |
+| **Pulse rate** | PPG (+ Accelerometer) | Resting & maximum pulse rate | [Veldkamp 2025*](https://doi.org/10.1101/2025.08.15.25333751) | [Guide](https://biomarkersparkinson.github.io/paradigma/tutorials/pulse_rate_analysis) |
+
+*\* Indicates pre-print*
+
+### Pipeline Architecture
+
+ParaDigMa can best be understood by categorizing the sequential processes:
+| Process | Description |
+| ---- | ---- |
+| **Preprocessing** | Preparing raw sensor signals for further processing |
+| **Feature extraction** | Extracting features based on windowed sensor signals |
+| **Classification** | Detecting segments of interest using validated classifiers (e.g., gait segments) |
+| **Quantification** | Extracting specific measures from the detected segments (e.g., arm swing measures) |
+| **Aggregation** | Aggregating the measures over a specific time period (e.g., week-level aggregates)
+
+## Usage
+### Documentation
+
+- **[Tutorials](https://biomarkersparkinson.github.io/paradigma/tutorials/index.html)** - Step-by-step usage examples
+- **[Installation Guide](https://biomarkersparkinson.github.io/paradigma/guides/installation.html)** - Setup and troubleshooting
+- **[Sensor Requirements](https://biomarkersparkinson.github.io/paradigma/guides/sensor_requirements.html)** - Data specifications and compliance
+- **[Supported Devices](https://biomarkersparkinson.github.io/paradigma/guides/supported_devices.html)** - Validated hardware
+- **[Input Formats Guide](https://biomarkersparkinson.github.io/paradigma/guides/input_formats.html)** - Input format options and data loading
+- **[Configuration Guide](https://biomarkersparkinson.github.io/paradigma/guides/config.html)** - Pipeline configuration
+- **[Scientific Validation](https://biomarkersparkinson.github.io/paradigma/guides/validation.html)** - Validation studies and publications
+- **[API Reference](https://biomarkersparkinson.github.io/paradigma/autoapi/paradigma/index.html)** - Complete API documentation
+
+### Sensor Requirements & Supported Devices
+
+ParaDigMa is designed for wrist sensor data collected during passive monitoring in persons with Parkinson's disease. While designed to work with any compliant device, it has been empirically validated on:
+
+- **Verily Study Watch** (gait, tremor, pulse rate)
+- **Axivity AX6** (gait, tremor)
+- **Gait-up Physilog 4** (gait, tremor)
+- **Empatica EmbracePlus** (data loading)
+
+Please check before running the pipelines whether your sensor data complies with the requirements for the sensor configuration and context of use. See the [sensor requirements guide](https://biomarkersparkinson.github.io/paradigma/guides/sensor_requirements.html) for data specifications and the [supported devices guide](https://biomarkersparkinson.github.io/paradigma/guides/supported_devices.html) for device-specific setup instructions.
+
+### Data Formats
+
+ParaDigMa supports the following data formats:
+
+- In-memory (recommended): **Pandas DataFrames** (see examples above)
+- Data loading file extensions: **TSDF, Parquet, CSV, Pickle** and **several device-specific formats** (AVRO (Empatica), CWA (Axivity))
+
+### Troubleshooting
+
+For installation issues, see the [installation guide troubleshooting section](https://biomarkersparkinson.github.io/paradigma/guides/installation.html#troubleshooting).
+
+For other issues, check our [issue tracker](https://github.com/biomarkersParkinson/paradigma/issues) or contact paradigma@radboudumc.nl.
+
+## Scientific Validation
+
+ParaDigMa pipelines are validated in peer-reviewed publications:
+
+| Pipeline | Publication |
+|----------|-------------|
+| **Arm swing during gait** | Post et al. (2025, 2026) |
+| **Tremor** | Timmermans et al. (2025a, 2025b) |
+| **Pulse rate** | Veldkamp et al. (2025) |
+
+See the [validation guide](https://biomarkersparkinson.github.io/paradigma/guides/validation.html) for full publication details.
+
+## Contributing
+
+We welcome contributions! Please see:
+
+- [Contributing Guidelines](https://biomarkersparkinson.github.io/paradigma/contributing.html)
+- [Code of Conduct](https://biomarkersparkinson.github.io/paradigma/conduct.html)
+
+## Citation
+
+If you use ParaDigMa in your research, please cite:
+
+```bibtex
+@software{paradigma2024,
+  author = {Post, Erik and Veldkamp, Kars and Timmermans, Nienke and
+            Soriano, Diogo Coutinho and Kasalica, Vedran and
+            Kok, Peter and Evers, Luc},
+  title = {ParaDigMa: Parkinson's disease Digital Markers},
+  year = {2024},
+  doi = {10.5281/zenodo.13838392},
+  url = {https://github.com/biomarkersParkinson/paradigma}
+}
+```
+
+## License
+
+Licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.
+
+## Acknowledgements
+
+**Core Team**: Erik Post, Kars Veldkamp, Nienke Timmermans, Diogo Coutinho Soriano, Vedran Kasalica, Peter Kok, Twan van Laarhoven, Luc Evers
+
+**Advisors**: Max Little, Jordan Raykov, Hayriye Cagnan, Bas Bloem
+
+**Funding**: the initial release was funded by the Michael J Fox Foundation (grant #020425) and the Dutch Research Council (grants #ASDI.2020.060, #2023.010)
+
+## Contact
+
+- Email: paradigma@radboudumc.nl
+- [Issue Tracker](https://github.com/biomarkersParkinson/paradigma/issues)
+