paradigma 0.2.0__tar.gz → 0.3.1__tar.gz

paradigma-0.3.1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.1
+Name: paradigma
+Version: 0.3.1
+Summary: Paradigma - a toolbox for Digital Biomarkers for Parkinson's Disease
+License: Apache-2.0
+Author: Peter Kok
+Author-email: p.kok@esciencecenter.nl
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: pandas (>=2.1.4,<3.0.0)
+Requires-Dist: pytype (>=2024.4.11,<2025.0.0)
+Requires-Dist: scikit-learn (>=1.3.2,<2.0.0)
+Requires-Dist: tsdf (>=0.5.2,<0.6.0)
+Description-Content-Type: text/markdown
+
+# paradigma
+
+| 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) |
+| **Build Status** | [![](https://img.shields.io/badge/python-3.10+-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) |
+<!-- | **DOI** | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7867899.svg)](https://doi.org/10.5281/zenodo.7867899) | -->
+<!-- | **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) | -->
+
+Digital Biomarkers for Parkinson's Disease Toolbox
+
+A package ([documentation](https://biomarkersparkinson.github.io/paradigma/)) to process wearable sensor data for Parkinson's disease.
+
+## Installation
+
+The package is available in PyPi and requires [Python 3.10](https://www.python.org/downloads/) or higher. It can be installed using:
+
+```bash
+pip install paradigma
+```
+
+## Usage
+
+See our [extended documentation](https://biomarkersparkinson.github.io/paradigma/).
+
+
+## Development
+
+### Installation
+The package requires Python 3.10 or higher. Use [Poetry](https://python-poetry.org/docs/#installation) to set up the environment and install the dependencies:
+
+```bash
+poetry install
+```
+
+### Testing
+
+```bash
+poetry run pytest
+```
+
+### Building documentation
+
+```bash
+poetry run make html --directory docs/
+```
+
+## Contributing
+
+Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.
+
+## License
+
+`paradigma` was created by Peter Kok, Vedran Kasalica, Erik Post, Kars Veldkamp, Nienke Timmermans, Diogo Coutinho Soriano, Luc Evers. It is licensed under the terms of the Apache License 2.0 license.
+
+## Credits
+
+`paradigma` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).
+

paradigma-0.3.1/README.md

@@ -0,0 +1,59 @@
+# paradigma
+
+| 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) |
+| **Build Status** | [![](https://img.shields.io/badge/python-3.10+-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) |
+<!-- | **DOI** | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7867899.svg)](https://doi.org/10.5281/zenodo.7867899) | -->
+<!-- | **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) | -->
+
+Digital Biomarkers for Parkinson's Disease Toolbox
+
+A package ([documentation](https://biomarkersparkinson.github.io/paradigma/)) to process wearable sensor data for Parkinson's disease.
+
+## Installation
+
+The package is available in PyPi and requires [Python 3.10](https://www.python.org/downloads/) or higher. It can be installed using:
+
+```bash
+pip install paradigma
+```
+
+## Usage
+
+See our [extended documentation](https://biomarkersparkinson.github.io/paradigma/).
+
+
+## Development
+
+### Installation
+The package requires Python 3.10 or higher. Use [Poetry](https://python-poetry.org/docs/#installation) to set up the environment and install the dependencies:
+
+```bash
+poetry install
+```
+
+### Testing
+
+```bash
+poetry run pytest
+```
+
+### Building documentation
+
+```bash
+poetry run make html --directory docs/
+```
+
+## Contributing
+
+Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.
+
+## License
+
+`paradigma` was created by Peter Kok, Vedran Kasalica, Erik Post, Kars Veldkamp, Nienke Timmermans, Diogo Coutinho Soriano, Luc Evers. It is licensed under the terms of the Apache License 2.0 license.
+
+## Credits
+
+`paradigma` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).

{paradigma-0.2.0 → paradigma-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "paradigma"
-version = "0.2.0"
+version = "0.3.1"
 description = "Paradigma - a toolbox for Digital Biomarkers for Parkinson's Disease"
 authors = [ "Peter Kok <p.kok@esciencecenter.nl>",
             "Vedran Kasalica <v.kaslica@esciencecenter.nl>",
@@ -13,10 +13,13 @@ license = "Apache License 2.0"
 readme = "README.md"
 
 [tool.poetry.dependencies]
-python = "^3.9"
+python = "^3.10"
 pandas = "^2.1.4"
 scikit-learn = "^1.3.2"
 tsdf = "^0.5.2"
+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
 
 [tool.poetry.group.testing.dependencies]
 ipykernel = "^6.27.1"

paradigma-0.3.1/src/paradigma/constants.py

@@ -0,0 +1,65 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DataColumns():
+    """
+    Class containing the data channels in `tsdf`.
+    """
+    ACCELEROMETER_X : str = "accelerometer_x"
+    ACCELEROMETER_Y : str = "accelerometer_y"
+    ACCELEROMETER_Z : str = "accelerometer_z"
+    GYROSCOPE_X : str = "gyroscope_x"
+    GYROSCOPE_Y : str = "gyroscope_y"
+    GYROSCOPE_Z : str = "gyroscope_z"
+    PPG : str = "green"
+    TIME : str = "time"
+
+    # The following are used in gait analysis
+    GRAV_ACCELEROMETER_X : str = "grav_accelerometer_x"
+    GRAV_ACCELEROMETER_Y : str = "grav_accelerometer_y"
+    GRAV_ACCELEROMETER_Z : str = "grav_accelerometer_z"
+    PRED_GAIT : str = "pred_gait"
+    PRED_ARM_SWING : str = "pred_arm_swing"
+    ANGLE : str = "angle"
+    ANGLE_SMOOTH : str = "angle_smooth"
+    VELOCITY : str = "velocity"
+    SEGMENT_NR : str = "segment_nr"
+    
+@dataclass(frozen=True)
+class DataUnits():
+    """
+    Class containing the data channel unit types in `tsdf`.
+    """
+    ACCELERATION: str = "m/s^2"
+    """ The acceleration is in m/s^2. """
+    
+    ROTATION: str = "deg/s"
+    """ The rotation is in degrees per second. """
+    
+    GRAVITY: str = "g"
+    """ The acceleration due to gravity is in g. """
+    
+    POWER_SPECTRAL_DENSITY: str = "g^2/Hz"
+    """ The power spectral density is in g^2/Hz. """
+    
+    FREQUENCY: str = "Hz"
+    """ The frequency is in Hz. """
+
+    NONE: str = "none"
+    """ The data channel has no unit. """
+    
+
+@dataclass(frozen=True)
+class TimeUnit():
+    """
+    Class containing the `time` channel unit types in `tsdf`.
+    """
+    RELATIVE_MS : str = "relative_ms"
+    """ The time is relative to the start time in milliseconds. """
+    ABSOLUTE_MS : str = "absolute_ms"
+    """ The time is absolute in milliseconds. """
+    DIFFERENCE_MS : str = "difference_ms"
+    """ The time is the difference between consecutive samples in milliseconds. """
+
+UNIX_TICKS_MS: int = 1000

{paradigma-0.2.0 → paradigma-0.3.1}/src/paradigma/feature_extraction.py

@@ -1,3 +1,4 @@
+from typing import List
 import numpy as np
 import pandas as pd
 from sklearn.decomposition import PCA
@@ -6,6 +7,9 @@ from scipy import signal, fft
 from scipy.integrate import cumulative_trapezoid
 from scipy.signal import find_peaks
 
+from paradigma.constants import DataColumns
+from paradigma.gait_analysis_config import IMUConfig
+
 
 def generate_statistics(
         sensor_col: pd.Series,
@@ -39,7 +43,7 @@ def generate_statistics(
 
 def generate_std_norm(
         df: pd.DataFrame,
-        cols: list,
+        cols: List[str],
     ) -> pd.Series:
     """Generate the standard deviation of the norm of the accelerometer axes.
     
@@ -47,7 +51,7 @@ def generate_std_norm(
     ----------
     df: pd.DataFrame
         The dataframe containing the accelerometer axes
-    cols: list
+    cols: List[str]
         The names of the columns containing the accelerometer axes
         
     Returns
@@ -125,8 +129,8 @@ def signal_to_ffts(
 
 def compute_power_in_bandwidth(
         sensor_col: list,
-        fmin: int,
-        fmax: int,
+        fmin: float,
+        fmax: float,
         sampling_frequency: int = 100,
         window_type: str = 'hann',
     ) -> float:
@@ -140,9 +144,9 @@ def compute_power_in_bandwidth(
     sensor_col: list
         The sensor column to be transformed (e.g. x-axis of accelerometer). This corresponds to a single window, which is a single row of the dataframe, 
         and contains values of individual timestamps composing the window.
-    fmin: int
+    fmin: float
         The lower bound of the frequency band
-    fmax: int
+    fmax: float
         The upper bound of the frequency band
     sampling_frequency: int
         The sampling frequency of the signal (default: 100)
@@ -162,10 +166,10 @@ def compute_power_in_bandwidth(
 
 def compute_perc_power(
         sensor_col: list,
-        fmin_band: int,
-        fmax_band: int,
-        fmin_total: int = 0,
-        fmax_total: int = 100,
+        fmin_band: float,
+        fmax_band: float,
+        fmin_total: float = 0,
+        fmax_total: float = 100,
         sampling_frequency: int = 100,
         window_type: str = 'hann'
     ) -> float:
@@ -177,13 +181,13 @@ def compute_perc_power(
     ----------
     sensor_col: list
         The sensor column to be transformed (e.g. x-axis of accelerometer). This corresponds to a single window, which is a single row of the dataframe
-    fmin_band: int
+    fmin_band: float
         The lower bound of the frequency band
-    fmax_band: int
+    fmax_band: float
         The upper bound of the frequency band
-    fmin_total: int
+    fmin_total: float
         The lower bound of the frequency spectrum (default: 0)
-    fmax_total: int
+    fmax_total: float
         The upper bound of the frequency spectrum (default: 100)
     sampling_frequency: int
         The sampling frequency of the signal (default: 100)
@@ -217,8 +221,8 @@ def compute_perc_power(
 def get_dominant_frequency(
         signal_ffts: list,
         signal_freqs: list,
-        fmin: int,
-        fmax: int
+        fmin: float,
+        fmax: float
         ) -> float:
     """Note: signal_ffts and signal_freqs are single cells (which corresponds to a single window) of signal_ffts and signal_freqs, as it is used with apply function.
     
@@ -602,7 +606,28 @@ def extract_peak_angular_velocity(
     return
 
 
-def extract_temporal_domain_features(config, df_windowed, l_gravity_stats=['mean', 'std']):
+def extract_temporal_domain_features(config: IMUConfig, df_windowed:pd.DataFrame, l_gravity_stats=['mean', 'std']) -> pd.DataFrame:
+    """
+    Compute temporal domain features for the accelerometer signal. The features are added to the dataframe. Therefore the original dataframe is modified, and the modified dataframe is returned.
+
+    Parameters
+    ----------
+
+    config: GaitFeatureExtractionConfig
+        The configuration object containing the parameters for the feature extraction
+    
+    df_windowed: pd.DataFrame
+        The dataframe containing the windowed accelerometer signal
+
+    l_gravity_stats: list, optional
+        The statistics to be computed for the gravity component of the accelerometer signal (default: ['mean', 'std'])
+    
+    Returns
+    -------
+    pd.DataFrame
+        The dataframe with the added temporal domain features.
+    """
+    
     # compute the mean and standard deviation of the gravity component of the acceleration signal for each axis
     for col in config.l_gravity_cols:
         for stat in l_gravity_stats:

{paradigma-0.2.0 → paradigma-0.3.1}/src/paradigma/gait_analysis.py

@@ -1,6 +1,8 @@
 import os
 import numpy as np
 import pandas as pd
+from pathlib import Path
+from typing import Union
 
 import tsdf
 
@@ -16,7 +18,7 @@ from paradigma.windowing import tabulate_windows, create_segments, discard_segme
 from paradigma.util import get_end_iso8601, write_data, read_metadata
 
 
-def extract_gait_features(input_path: str, output_path: str, config: GaitFeatureExtractionConfig) -> None:
+def extract_gait_features(input_path: Union[str, Path], output_path: Union[str, Path], config: GaitFeatureExtractionConfig) -> None:
     # load data
     metadata_time, metadata_samples = read_metadata(input_path, config.meta_filename, config.time_filename, config.values_filename)
     df = tsdf.load_dataframe_from_binaries([metadata_time, metadata_samples], tsdf.constants.ConcatenationType.columns)
@@ -57,7 +59,7 @@ def extract_gait_features(input_path: str, output_path: str, config: GaitFeature
     write_data(metadata_time, metadata_samples, output_path, 'gait_meta.json', df_windowed)
 
 
-def detect_gait(input_path: str, output_path: str, path_to_classifier_input: str, config: GaitDetectionConfig) -> None:
+def detect_gait(input_path: Union[str, Path], output_path: Union[str, Path], path_to_classifier_input: Union[str, Path], config: GaitDetectionConfig) -> None:
     
     # Load the data
     metadata_time, metadata_samples = read_metadata(input_path, config.meta_filename, config.time_filename, config.values_filename)
@@ -69,12 +71,12 @@ def detect_gait(input_path: str, output_path: str, path_to_classifier_input: str
         threshold = float(f.read())
 
     # Prepare the data
-    clf.feature_names_in_ = [f'{x}_power_below_gait' for x in config.l_accel_cols] + \
-                            [f'{x}_power_gait' for x in config.l_accel_cols] + \
-                            [f'{x}_power_tremor' for x in config.l_accel_cols] + \
-                            [f'{x}_power_above_tremor' for x in config.l_accel_cols] + \
-                            ['std_norm_acc'] + [f'cc_{i}_accelerometer' for i in range(1, 13)] + [f'grav_{x}_{y}' for x in config.l_accel_cols for y in ['mean', 'std']] + \
-                            [f'{x}_dominant_frequency' for x in config.l_accel_cols]
+    clf.feature_names_in_ = [f'{x}_power_below_gait' for x in config.l_accelerometer_cols] + \
+                            [f'{x}_power_gait' for x in config.l_accelerometer_cols] + \
+                            [f'{x}_power_tremor' for x in config.l_accelerometer_cols] + \
+                            [f'{x}_power_above_tremor' for x in config.l_accelerometer_cols] + \
+                            ['std_norm_acc'] + [f'cc_{i}_accelerometer' for i in range(1, 13)] + [f'grav_{x}_{y}' for x in config.l_accelerometer_cols for y in ['mean', 'std']] + \
+                            [f'{x}_dominant_frequency' for x in config.l_accelerometer_cols]
     X = df.loc[:, clf.feature_names_in_]
 
     # Make prediction
@@ -98,7 +100,7 @@ def detect_gait(input_path: str, output_path: str, path_to_classifier_input: str
     write_data(metadata_time, metadata_samples, output_path, 'gait_meta.json', df)
 
 
-def extract_arm_swing_features(input_path: str, output_path: str, config: ArmSwingFeatureExtractionConfig) -> None:
+def extract_arm_swing_features(input_path: Union[str, Path], output_path: Union[str, Path], config: ArmSwingFeatureExtractionConfig) -> None:
     # load accelerometer and gyroscope data
     l_dfs = []
     for sensor in ['accelerometer', 'gyroscope']:
@@ -120,7 +122,7 @@ def extract_arm_swing_features(input_path: str, output_path: str, config: ArmSwi
     # perform principal component analysis on the gyroscope signals to obtain the angular velocity in the
     # direction of the swing of the arm 
     df[config.velocity_colname] = pca_transform_gyroscope(
-        df=df, 
+        df=df,
         y_gyro_colname=DataColumns.GYROSCOPE_Y,
         z_gyro_colname=DataColumns.GYROSCOPE_Z,
         pred_gait_colname=config.pred_gait_colname
@@ -281,7 +283,7 @@ def extract_arm_swing_features(input_path: str, output_path: str, config: ArmSwi
     write_data(metadata_time, metadata_samples, output_path, 'arm_swing_meta.json', df_windowed)
 
 
-def detect_arm_swing(input_path: str, output_path: str, path_to_classifier_input: str, config: ArmSwingDetectionConfig) -> None:
+def detect_arm_swing(input_path: Union[str, Path], output_path: Union[str, Path], path_to_classifier_input: Union[str, Path], config: ArmSwingDetectionConfig) -> None:
     # Load the data
     metadata_time, metadata_samples = read_metadata(input_path, config.meta_filename, config.time_filename, config.values_filename)
     df = tsdf.load_dataframe_from_binaries([metadata_time, metadata_samples], tsdf.constants.ConcatenationType.columns)
@@ -290,15 +292,15 @@ def detect_arm_swing(input_path: str, output_path: str, path_to_classifier_input
     clf = pd.read_pickle(os.path.join(path_to_classifier_input, config.classifier_file_name))
 
     # Prepare the data
-    clf.feature_names_in_ = ['std_norm_acc'] + [f'{x}_power_below_gait' for x in config.l_accel_cols] + \
-                            [f'{x}_power_gait' for x in config.l_accel_cols] + \
-                            [f'{x}_power_tremor' for x in config.l_accel_cols] + \
-                            [f'{x}_power_above_tremor' for x in config.l_accel_cols] + \
+    clf.feature_names_in_ = ['std_norm_acc'] + [f'{x}_power_below_gait' for x in config.l_accelerometer_cols] + \
+                            [f'{x}_power_gait' for x in config.l_accelerometer_cols] + \
+                            [f'{x}_power_tremor' for x in config.l_accelerometer_cols] + \
+                            [f'{x}_power_above_tremor' for x in config.l_accelerometer_cols] + \
                             [f'cc_{i}_accelerometer' for i in range(1, 13)] + [f'cc_{i}_gyroscope' for i in range(1, 13)] + \
-                            [f'grav_{x}_mean' for x in config.l_accel_cols] +  [f'grav_{x}_std' for x in config.l_accel_cols] + \
+                            [f'grav_{x}_mean' for x in config.l_accelerometer_cols] +  [f'grav_{x}_std' for x in config.l_accelerometer_cols] + \
                             ['range_of_motion', 'forward_peak_ang_vel_mean', 'backward_peak_ang_vel_mean', 'forward_peak_ang_vel_std', 
                             'backward_peak_ang_vel_std', 'angle_perc_power', 'angle_dominant_frequency'] + \
-                            [f'{x}_dominant_frequency' for x in config.l_accel_cols]
+                            [f'{x}_dominant_frequency' for x in config.l_accelerometer_cols]
                             
     X = df.loc[:, clf.feature_names_in_]
 
@@ -323,7 +325,7 @@ def detect_arm_swing(input_path: str, output_path: str, path_to_classifier_input
     write_data(metadata_time, metadata_samples, output_path, 'arm_swing_meta.json', df)
 
 
-def quantify_arm_swing(path_to_feature_input: str, path_to_prediction_input: str, output_path: str, config: ArmSwingQuantificationConfig) -> None:
+def quantify_arm_swing(path_to_feature_input: Union[str, Path], path_to_prediction_input: Union[str, Path], output_path: Union[str, Path], config: ArmSwingQuantificationConfig) -> None:
     # Load the features & predictions
     metadata_time, metadata_samples = read_metadata(path_to_feature_input, config.meta_filename, config.time_filename, config.values_filename)
     df_features = tsdf.load_dataframe_from_binaries([metadata_time, metadata_samples], tsdf.constants.ConcatenationType.columns)