paradigma 0.4.2__py3-none-any.whl → 0.4.3__py3-none-any.whl

paradigma/config.py

@@ -195,11 +195,12 @@ class TremorConfig(IMUConfig):
         # Feature extraction
         # -----------------
         self.window_type = 'hann'
-
-        # Power spectral density
         self.overlap_fraction: float = 0.8
-        self.segment_length_s: float = 3
+        self.segment_length_psd_s: float = 3
+        self.segment_length_spectrogram_s: float = 2
         self.spectral_resolution: float = 0.25
+        
+        # PSD based features
         self.fmin_peak_search: float = 1
         self.fmax_peak_search: float = 25
         self.fmin_below_rest_tremor: float = 0.5

paradigma/feature_extraction.py

@@ -416,11 +416,13 @@ def compute_spectral_entropy(
 def compute_mfccs(
         total_power_array: np.ndarray, 
         config, 
+        total_power_type: str = 'psd',
         mel_scale: bool = True,
-        multiplication_factor: float = 1
+        multiplication_factor: float = 1,
+        rounding_method: str = 'floor'       
     ) -> np.ndarray:
     """
-    Generate Mel Frequency Cepstral Coefficients (MFCCs) from the total power spectral density of the signal.
+    Generate Mel Frequency Cepstral Coefficients (MFCCs) from the total power spectral density or spectrogram of the signal.
 
     MFCCs are commonly used features in signal processing for tasks like audio and 
     vibration analysis. In this version, we adjusted the MFFCs to the human activity
@@ -434,6 +436,9 @@ def compute_mfccs(
     total_power_array : np.ndarray
         2D array of shape (n_windows, n_frequencies) containing the total power 
         of the signal for each window.
+        OR
+        3D array of shape (n_windows, n_frequencies, n_segments) containing the total spectrogram
+        of the signal for each window.
     config : object
         Configuration object containing the following attributes:
         - window_length_s : int
@@ -448,11 +453,15 @@ def compute_mfccs(
             Number of triangular filters in the filterbank (default: 20).
         - mfcc_n_coefficients : int
             Number of coefficients to extract (default: 12).
+    total_power_type : str, optional
+        The type of the total power array. Supported values are 'psd' and 'spectrogram' (default: 'psd').
     mel_scale : bool, optional
         Whether to use the mel scale for the filterbank (default: True).
     multiplication_factor : float, optional
         Multiplication factor for the Mel scale conversion (default: 1). For tremor, the recommended
         value is 1. For gait, this is 4.
+    rounding_method : str, optional
+        The method used to round the filter points. Supported values are 'round' and 'floor' (default: 'floor').
 
     Returns
     -------
@@ -466,9 +475,19 @@ def compute_mfccs(
     - The function includes filterbank normalization to ensure proper scaling.
     - DCT filters are constructed to minimize spectral leakage.
     """
+    
+    # Check if total_power_type is either 'psd' or 'spectrogram'
+    if total_power_type not in ['psd', 'spectrogram']:
+        raise ValueError("total_power_type should be set to either 'psd' or 'spectrogram'")
+
     # Compute window length in samples
     window_length = config.window_length_s * config.sampling_frequency
     
+    # Determine the length of subwindows used in the spectrogram computation
+    if total_power_type == 'spectrogram':
+        nr_subwindows = total_power_array.shape[2]
+        window_length = int(window_length/(nr_subwindows - (nr_subwindows - 1) * config.overlap_fraction))
+
     # Generate filter points
     if mel_scale:
         freqs = np.linspace(
@@ -483,10 +502,16 @@ def compute_mfccs(
             config.mfcc_high_frequency, 
             num=config.mfcc_n_dct_filters + 2
         )
+    
+    if rounding_method == 'round':
+        filter_points = np.round(
+            window_length / config.sampling_frequency * freqs
+        ).astype(int)  + 1
 
-    filter_points = np.floor(
-        window_length / config.sampling_frequency * freqs
-    ).astype(int)  + 1
+    elif rounding_method == 'floor':
+        filter_points = np.floor(
+            window_length / config.sampling_frequency * freqs
+        ).astype(int) + 1
 
     # Construct triangular filterbank
     filters = np.zeros((len(filter_points) - 2, int(window_length / 2 + 1)))
@@ -500,8 +525,11 @@ def compute_mfccs(
         ) 
 
     # Apply filterbank to total power
-    power_filtered = np.dot(total_power_array, filters.T) 
-    
+    if total_power_type == 'spectrogram':
+        power_filtered = np.tensordot(total_power_array, filters.T, axes=(1,0))
+    elif total_power_type == 'psd':
+        power_filtered = np.dot(total_power_array, filters.T)
+        
     # Convert power to logarithmic scale
     log_power_filtered = np.log10(power_filtered + 1e-10)
 
@@ -519,6 +547,9 @@ def compute_mfccs(
     # Compute MFCCs
     mfccs = np.dot(log_power_filtered, dct_filters.T) 
 
+    if total_power_type == 'spectrogram':
+        mfccs = np.mean(mfccs, axis=1)
+
     return mfccs
 
 

paradigma/pipelines/gait_pipeline.py

@@ -350,31 +350,20 @@ def filter_gait(
 
 
 def quantify_arm_swing(
-        df_timestamps: pd.DataFrame, 
-        df_predictions: pd.DataFrame, 
-        classification_threshold: float, 
-        window_length_s: float,
+        df: pd.DataFrame, 
         max_segment_gap_s: float, 
         min_segment_length_s: float,
         fs: int,
-        dfs_to_quantify: List[str] | str = ['unfiltered', 'filtered'],
+        filtered: bool = False,
     ) -> Tuple[dict[str, pd.DataFrame], dict]:
     """
     Quantify arm swing parameters for segments of motion based on gyroscope data.
 
     Parameters
     ----------
-    df_timestamps : pd.DataFrame
-        A DataFrame containing the raw sensor data, including gyroscope columns.
-
-    df_predictions : pd.DataFrame
-        A DataFrame containing the predicted probabilities for no other arm activity per window.
-
-    classification_threshold : float
-        The threshold used to classify no other arm activity based on the predicted probabilities.
-
-    window_length_s : float
-        The length of the window used for feature extraction.
+    df : pd.DataFrame
+        A DataFrame containing the raw sensor data, including gyroscope columns. Should include a column
+        for predicted no other arm activity based on a fitted threshold if filtered is True.
 
     max_segment_gap_s : float
         The maximum gap allowed between segments.
@@ -385,45 +374,16 @@ def quantify_arm_swing(
     fs : int
         The sampling frequency of the sensor data.
 
-    dfs_to_quantify : List[str] | str, optional
-        The DataFrames to quantify arm swing parameters for. Options are 'unfiltered' and 'filtered', with 'unfiltered' being predicted gait, and 
-        'filtered' being predicted gait without other arm activities.
+    filtered : bool, optional, default=True
+        If `True`, the gyroscope data is filtered to only include predicted no other arm activity.
 
     Returns
     -------
-    Tuple[dict, dict]
-        A tuple containing a dictionary with quantified arm swing parameters for dfs_to_quantify, 
-        and a dictionary containing metadata for each segment.
+    Tuple[pd.DataFrame, dict]
+        A tuple containing a dataframe with quantified arm swing parameters and a dictionary containing 
+        metadata for each segment.
     """
-    if not any(df_predictions[DataColumns.PRED_NO_OTHER_ARM_ACTIVITY_PROBA] >= classification_threshold):
-        raise ValueError("No gait without other arm activity detected in the input data.")
-    
-    if isinstance(dfs_to_quantify, str):
-        dfs_to_quantify = [dfs_to_quantify]
-    elif not isinstance(dfs_to_quantify, list):
-        raise ValueError("dfs_to_quantify must be either 'unfiltered', 'filtered', or a list containing both.")
-
-    valid_values = {'unfiltered', 'filtered'}
-    if set(dfs_to_quantify) - valid_values:
-        raise ValueError(
-            f"Invalid value in dfs_to_quantify: {dfs_to_quantify}. "
-            f"Valid options are 'unfiltered', 'filtered', or both in a list."
-        ) 
     
-    # Merge arm activity predictions with timestamps
-    df = merge_predictions_with_timestamps(
-        df_ts=df_timestamps, 
-        df_predictions=df_predictions, 
-        pred_proba_colname=DataColumns.PRED_NO_OTHER_ARM_ACTIVITY_PROBA,
-        window_length_s=window_length_s, 
-        fs=fs
-    )
-
-    # Add a column for predicted no other arm activity based on a fitted threshold
-    df[DataColumns.PRED_NO_OTHER_ARM_ACTIVITY] = (
-        df[DataColumns.PRED_NO_OTHER_ARM_ACTIVITY_PROBA] >= classification_threshold
-    ).astype(int)
-
     # Group consecutive timestamps into segments, with new segments starting after a pre-specified gap.
     # Segments are made based on predicted gait
     df[DataColumns.SEGMENT_NR] = create_segments(
@@ -444,111 +404,98 @@ def quantify_arm_swing(
         raise ValueError("No segments found in the input data.")
 
     # If no arm swing data is remaining, return an empty dictionary
-    if df.loc[df[DataColumns.PRED_NO_OTHER_ARM_ACTIVITY]==1].empty:
+    if filtered and df.loc[df[DataColumns.PRED_NO_OTHER_ARM_ACTIVITY]==1].empty:
+        raise ValueError("No gait without other arm activities to quantify.")
         
-        if 'filtered' in dfs_to_quantify and len(dfs_to_quantify) == 1:
-            raise ValueError("No gait without other arm activities to quantify.")
-        
-        dfs_to_quantify = [x for x in dfs_to_quantify if x != 'filtered']
+    df[DataColumns.SEGMENT_CAT] = categorize_segments(df=df, fs=fs)
 
-    df[DataColumns.SEGMENT_CAT] = categorize_segments(
-        df=df,
-        fs=fs
-    )
+    # Group and process segments
+    arm_swing_quantified = []
+    segment_meta = {}
+
+    if filtered:
+        # Filter the DataFrame to only include predicted no other arm activity (1)
+        df = df.loc[df[DataColumns.PRED_NO_OTHER_ARM_ACTIVITY]==1].reset_index(drop=True)
+
+        # Group consecutive timestamps into segments, with new segments starting after a pre-specified gap
+        # Now segments are based on predicted gait without other arm activity for subsequent processes
+        df[DataColumns.SEGMENT_NR] = create_segments(
+            time_array=df[DataColumns.TIME], 
+            max_segment_gap_s=max_segment_gap_s
+        )
+
+        pred_colname_pca = DataColumns.PRED_NO_OTHER_ARM_ACTIVITY
+    else:
+        pred_colname_pca = None
 
     df[DataColumns.VELOCITY] = pca_transform_gyroscope(
         df=df,
         y_gyro_colname=DataColumns.GYROSCOPE_Y,
         z_gyro_colname=DataColumns.GYROSCOPE_Z,
-        pred_colname=DataColumns.PRED_NO_OTHER_ARM_ACTIVITY
+        pred_colname=pred_colname_pca
     )
 
-    # Group and process segments
-    arm_swing_quantified = {}
-    segment_meta = {}
+    for segment_nr, group in df.groupby(DataColumns.SEGMENT_NR, sort=False):
+        segment_cat = group[DataColumns.SEGMENT_CAT].iloc[0]
+        time_array = group[DataColumns.TIME].to_numpy()
+        velocity_array = group[DataColumns.VELOCITY].to_numpy()
 
-    # If both unfiltered and filtered gait are to be quantified, start with the unfiltered data
-    # and subset to get filtered data afterwards.
-    dfs_to_quantify = sorted(dfs_to_quantify, reverse=True)
-
-    for df_name in dfs_to_quantify:    
-        if df_name == 'filtered':
-            # Filter the DataFrame to only include predicted no other arm activity (1)
-            df_focus = df.loc[df[DataColumns.PRED_NO_OTHER_ARM_ACTIVITY]==1].copy().reset_index(drop=True)
-
-            # Group consecutive timestamps into segments, with new segments starting after a pre-specified gap
-            # Now segments are based on predicted gait without other arm activity for subsequent processes
-            df_focus[DataColumns.SEGMENT_NR] = create_segments(
-                time_array=df_focus[DataColumns.TIME], 
-                max_segment_gap_s=max_segment_gap_s
-            )
-        else:
-            df_focus = df.copy()
-
-        arm_swing_quantified[df_name] = []
-        segment_meta[df_name] = {}
+        # Integrate the angular velocity to obtain an estimation of the angle
+        angle_array = compute_angle(
+            time_array=time_array,
+            velocity_array=velocity_array,
+        )
 
-        for segment_nr, group in df_focus.groupby(DataColumns.SEGMENT_NR, sort=False):
-            segment_cat = group[DataColumns.SEGMENT_CAT].iloc[0]
-            time_array = group[DataColumns.TIME].to_numpy()
-            velocity_array = group[DataColumns.VELOCITY].to_numpy()
+        # Detrend angle using moving average
+        angle_array = remove_moving_average_angle(
+            angle_array=angle_array,
+            fs=fs,
+        )
 
-            # Integrate the angular velocity to obtain an estimation of the angle
-            angle_array = compute_angle(
-                time_array=time_array,
-                velocity_array=velocity_array,
-            )
+        segment_meta[segment_nr] = {
+            'time_s': len(angle_array) / fs,
+            DataColumns.SEGMENT_CAT: segment_cat
+        }
 
-            # Detrend angle using moving average
-            angle_array = remove_moving_average_angle(
+        if angle_array.size > 0:  
+            angle_extrema_indices, _, _ = extract_angle_extremes(
                 angle_array=angle_array,
-                fs=fs,
+                sampling_frequency=fs,
+                max_frequency_activity=1.75
             )
 
-            segment_meta[df_name][segment_nr] = {
-                'time_s': len(angle_array) / fs,
-                DataColumns.SEGMENT_CAT: segment_cat
-            }
-
-            if angle_array.size > 0:  
-                angle_extrema_indices, _, _ = extract_angle_extremes(
-                    angle_array=angle_array,
-                    sampling_frequency=fs,
-                    max_frequency_activity=1.75
-                )
-
-                if len(angle_extrema_indices) > 1:  # Requires at minimum 2 peaks
-                    try:
-                        rom = compute_range_of_motion(
-                            angle_array=angle_array,
-                            extrema_indices=angle_extrema_indices,
-                        )
-                    except Exception as e:
-                        # Handle the error, set RoM to NaN, and log the error
-                        print(f"Error computing range of motion for segment {segment_nr}: {e}")
-                        rom = np.array([np.nan])
-
-                    try:
-                        pav = compute_peak_angular_velocity(
-                            velocity_array=velocity_array,
-                            angle_extrema_indices=angle_extrema_indices
-                        )
-                    except Exception as e:
-                        # Handle the error, set pav to NaN, and log the error
-                        print(f"Error computing peak angular velocity for segment {segment_nr}: {e}")
-                        pav = np.array([np.nan])
-
-                    df_params_segment = pd.DataFrame({
-                        DataColumns.SEGMENT_NR: segment_nr,
-                        DataColumns.RANGE_OF_MOTION: rom,
-                        DataColumns.PEAK_VELOCITY: pav
-                    })
-
-                    arm_swing_quantified[df_name].append(df_params_segment)
-
-        arm_swing_quantified[df_name] = pd.concat(arm_swing_quantified[df_name], ignore_index=True)
+            if len(angle_extrema_indices) > 1:  # Requires at minimum 2 peaks
+                try:
+                    rom = compute_range_of_motion(
+                        angle_array=angle_array,
+                        extrema_indices=angle_extrema_indices,
+                    )
+                except Exception as e:
+                    # Handle the error, set RoM to NaN, and log the error
+                    print(f"Error computing range of motion for segment {segment_nr}: {e}")
+                    rom = np.array([np.nan])
+
+                try:
+                    pav = compute_peak_angular_velocity(
+                        velocity_array=velocity_array,
+                        angle_extrema_indices=angle_extrema_indices
+                    )
+                except Exception as e:
+                    # Handle the error, set pav to NaN, and log the error
+                    print(f"Error computing peak angular velocity for segment {segment_nr}: {e}")
+                    pav = np.array([np.nan])
+
+                df_params_segment = pd.DataFrame({
+                    DataColumns.SEGMENT_NR: segment_nr,
+                    DataColumns.RANGE_OF_MOTION: rom,
+                    DataColumns.PEAK_VELOCITY: pav
+                })
+
+                arm_swing_quantified.append(df_params_segment)
+
+    arm_swing_quantified = pd.concat(arm_swing_quantified, ignore_index=True)
             
-    return {df_name: arm_swing_quantified[df_name] for df_name in dfs_to_quantify}, segment_meta
+    return arm_swing_quantified, segment_meta
 
 
 def aggregate_arm_swing_params(df_arm_swing_params: pd.DataFrame, segment_meta: dict, aggregates: List[str] = ['median']) -> dict:

paradigma/pipelines/tremor_pipeline.py

@@ -1,5 +1,3 @@
-import tsdf
-import json
 import pandas as pd
 import numpy as np
 from pathlib import Path
@@ -12,7 +10,7 @@ from paradigma.config import TremorConfig
 from paradigma.feature_extraction import compute_mfccs, compute_power_in_bandwidth, compute_total_power, extract_frequency_peak, \
     extract_tremor_power
 from paradigma.segmenting import tabulate_windows, WindowedDataExtractor
-from paradigma.util import get_end_iso8601, write_df_data, read_metadata, aggregate_parameter
+from paradigma.util import aggregate_parameter
 
 
 def extract_tremor_features(df: pd.DataFrame, config: TremorConfig) -> pd.DataFrame:
@@ -182,25 +180,38 @@ def aggregate_tremor(df: pd.DataFrame, config: TremorConfig):
     df_filtered = df.loc[df.pred_arm_at_rest == 1]
     nr_windows_rest = df_filtered.shape[0] # number of windows without non-tremor arm movement
 
+    if nr_windows_rest == 0: # if no windows without non-tremor arm movement are detected
+        raise Warning('No windows without non-tremor arm movement are detected.')
+
     # calculate tremor time
-    perc_windows_tremor= np.sum(df_filtered['pred_tremor_checked']) / nr_windows_rest * 100 # as percentage of total measured time without non-tremor arm movement
+    n_windows_tremor = np.sum(df_filtered['pred_tremor_checked'])
+    perc_windows_tremor = n_windows_tremor / nr_windows_rest * 100 # as percentage of total measured time without non-tremor arm movement
 
-    # calculate aggregated tremor power measures
-    tremor_power = df_filtered.loc[df_filtered['pred_tremor_checked'] == 1, 'tremor_power']
-    tremor_power = np.log10(tremor_power+1) # convert to log scale
-    aggregated_tremor_power = {}
+    aggregated_tremor_power = {} # initialize dictionary to store aggregated tremor power measures
     
-    for aggregate in config.aggregates_tremor_power:
-        aggregate_name = f"{aggregate}_tremor_power"
-        if aggregate == 'mode':
-            # calculate modal tremor power
-            bin_edges = np.linspace(0, 6, 301)
-            kde = gaussian_kde(tremor_power)
-            kde_values = kde(bin_edges)
-            max_index = np.argmax(kde_values)
-            aggregated_tremor_power['modal_tremor_power'] = bin_edges[max_index]
-        else: # calculate te other aggregates (e.g. median and 90th percentile) of tremor power
-            aggregated_tremor_power[aggregate_name] = aggregate_parameter(tremor_power, aggregate)
+    if n_windows_tremor == 0: # if no tremor is detected, the tremor power measures are set to NaN
+
+        aggregated_tremor_power['median_tremor_power'] = np.nan
+        aggregated_tremor_power['modal_tremor_power'] = np.nan
+        aggregated_tremor_power['90p_tremor_power'] = np.nan
+
+    else:
+        
+        # calculate aggregated tremor power measures
+        tremor_power = df_filtered.loc[df_filtered['pred_tremor_checked'] == 1, 'tremor_power']
+        tremor_power = np.log10(tremor_power+1) # convert to log scale
+        
+        for aggregate in config.aggregates_tremor_power:
+            aggregate_name = f"{aggregate}_tremor_power"
+            if aggregate == 'mode':
+                # calculate modal tremor power
+                bin_edges = np.linspace(0, 6, 301)
+                kde = gaussian_kde(tremor_power)
+                kde_values = kde(bin_edges)
+                max_index = np.argmax(kde_values)
+                aggregated_tremor_power['modal_tremor_power'] = bin_edges[max_index]
+            else: # calculate te other aggregates (e.g. median and 90th percentile) of tremor power
+                aggregated_tremor_power[aggregate_name] = aggregate_parameter(tremor_power, aggregate)
     
     # store aggregates in json format
     d_aggregates = {
@@ -246,13 +257,14 @@ def extract_spectral_domain_features(data: np.ndarray, config) -> pd.DataFrame:
 
     # Initialize parameters
     sampling_frequency = config.sampling_frequency
-    segment_length_s = config.segment_length_s
+    segment_length_psd_s = config.segment_length_psd_s
+    segment_length_spectrogram_s = config.segment_length_spectrogram_s
     overlap_fraction = config.overlap_fraction
     spectral_resolution = config.spectral_resolution
     window_type = 'hann'
 
     # Compute the power spectral density
-    segment_length_n = sampling_frequency * segment_length_s
+    segment_length_n = sampling_frequency * segment_length_psd_s
     overlap_n = segment_length_n * overlap_fraction
     window = signal.get_window(window_type, segment_length_n, fftbins=False)
     nfft = sampling_frequency / spectral_resolution
@@ -269,8 +281,24 @@ def extract_spectral_domain_features(data: np.ndarray, config) -> pd.DataFrame:
         axis=1
     )
 
-    # Compute total power in the PSD (over the three axes)
+    # Compute the spectrogram
+    segment_length_n = sampling_frequency * segment_length_spectrogram_s
+    overlap_n = segment_length_n * overlap_fraction
+    window = signal.get_window(window_type, segment_length_n)
+
+    f, t, S1 = signal.stft(
+        x=data, 
+        fs=sampling_frequency, 
+        window=window, 
+        nperseg=segment_length_n, 
+        noverlap=overlap_n,
+        boundary=None,
+        axis=1
+    )
+
+    # Compute total power in the PSD and the total spectrogram (summed over the three axes)
     total_psd = compute_total_power(psd)
+    total_spectrogram = np.sum(np.abs(S1)*sampling_frequency, axis=2)
 
     # Compute the MFCC's
     config.mfcc_low_frequency = config.fmin_mfcc
@@ -279,8 +307,10 @@ def extract_spectral_domain_features(data: np.ndarray, config) -> pd.DataFrame:
     config.mfcc_n_coefficients = config.n_coefficients_mfcc
 
     mfccs = compute_mfccs(
-        total_power_array=total_psd,
+        total_power_array=total_spectrogram,
         config=config,
+        total_power_type='spectrogram',
+        rounding_method='round',
         multiplication_factor=1
     )
 

paradigma/preprocessing.py

@@ -191,7 +191,7 @@ def preprocess_imu_data(df: pd.DataFrame, config: IMUConfig, sensor: str, watch_
     )
 
     # Invert the IMU data if the watch was worn on the right wrist
-    df = invert_watch_side(df, watch_side)
+    df = invert_watch_side(df, watch_side, sensor)
     
     if sensor in ['accelerometer', 'both']:
       

paradigma/util.py

@@ -285,7 +285,7 @@ def convert_units_gyroscope(data: np.ndarray, units: str) -> np.ndarray:
         raise ValueError(f"Unsupported unit: {units}")
     
 
-def invert_watch_side(df: pd.DataFrame, side: str) -> np.ndarray:
+def invert_watch_side(df: pd.DataFrame, side: str, sensor='both') -> np.ndarray:
     """
     Invert the data based on the watch side.
 
@@ -295,6 +295,8 @@ def invert_watch_side(df: pd.DataFrame, side: str) -> np.ndarray:
         The data.
     side : str
         The watch side (left or right).
+    sensor: str
+        The sensor(s) to invert: 'accelerometer', 'gyroscope', or 'both'
 
     Returns
     -------
@@ -304,10 +306,15 @@ def invert_watch_side(df: pd.DataFrame, side: str) -> np.ndarray:
     """
     if side not in ["left", "right"]:
         raise ValueError(f"Unsupported side: {side}")
+    if sensor not in ['accelerometer', 'gyroscope', 'both']:
+        raise ValueError(f"Unsupported sensor: {sensor}")
+
     elif side == "right":
-        df[DataColumns.GYROSCOPE_Y] *= -1
-        df[DataColumns.GYROSCOPE_Z] *= -1
-        df[DataColumns.ACCELEROMETER_X] *= -1
+        if sensor in ['gyroscope', 'both']:
+            df[DataColumns.GYROSCOPE_Y] *= -1
+            df[DataColumns.GYROSCOPE_Z] *= -1
+        if sensor in ['accelerometer', 'both']:
+            df[DataColumns.ACCELEROMETER_X] *= -1
 
     return df
 

{paradigma-0.4.2.dist-info → paradigma-0.4.3.dist-info}/LICENSE

@@ -1,3 +1,5 @@
+# License
+
 Apache License
 Version 2.0, January 2004
 http://www.apache.org/licenses/

paradigma-0.4.3.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.3
+Name: paradigma
+Version: 0.4.3
+Summary: Paradigma - a toolbox for Digital Biomarkers for Parkinson's Disease
+License: Apache-2.0
+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
+Requires-Dist: pandas (>=2.1.4,<3.0.0)
+Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
+Requires-Dist: pytype (>=2024.4.11,<2025.0.0)
+Requires-Dist: scikit-learn (>=1.3.2,<1.6.1)
+Requires-Dist: tsdf (>=0.5.2,<0.6.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.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) |
+<!-- | **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) | --> 
+
+## Overview
+The Parkinson's disease Digital Markers (ParaDigMa) toolbox is a Python
+software package designed for processing real-life wrist sensor data
+to extract digital measures of motor and non-motor signs of Parkinson's disease (PD).  
+
+Specifically, the toolbox is designed to process accelerometer, gyroscope and 
+photoplethysmography (PPG) signals, collected during passive monitoring in daily life. 
+It contains three data processing pipelines: (1) arm swing during gait, (2) tremor, 
+and (3) pulse rate. These pipelines are scientifically validated for their 
+use in persons with PD. Furthermore, the toolbox contains general functionalities for 
+signal processing and feature extraction, such as filtering, peak detection, and 
+spectral analysis. 
+
+The toolbox is accompanied by a set of example scripts and notebooks for 
+each processing pipeline that demonstrate how to use the toolbox for extracting 
+digital measures. In addition, the toolbox is designed to be modular, enabling
+researchers to easily extend the toolbox with new algorithms and functionalities. 
+
+## Features
+The components of ParaDigMa are shown in the diagram below.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/biomarkersParkinson/paradigma/main/docs/source/_static/img/pipeline-architecture.png" alt="Pipeline architeecture"/>
+</p>
+The three colored, shaded columns represent the individual pipelines. Processes of the pipelines are represented by blue ellipses, and input/output data by rectangular boxes. The input/output of each step is indicated by yellow horizontal bars denoting the type of data (e.g., 3. Extracted features). Arrows indicate the sequential order of the processes of the pipeline. <br/> <br/>
+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) |
+
+<br/>
+ParaDigMa contains the following validated processing pipelines (each using the processes described above): 
+
+| Pipeline | Input | Output classification | Output quantification | Output week-level aggregation | 
+| ---- | ---- | ---- | ---- | ---- |
+| **Arm swing during gait** | Wrist accelerometer and gyroscope data | Gait probability, gait without other arm activities probability | Arm swing range of motion (RoM) | Typical & maximum arm swing RoM | 
+| **Tremor** | Wrist gyroscope data | Tremor probability | Tremor power | % tremor time, typical & maximum tremor power |   
+| **Pulse rate** | Wrist PPG and accelerometer data | PPG signal quality | Pulse rate | Resting & maximum pulse rate | 
+
+## Installation
+
+The package is available in PyPI and requires [Python 3.11](https://www.python.org/downloads/) or higher. It can be installed using:
+
+```bash
+pip install paradigma
+```
+
+## Usage
+
+### Tutorials & documentation
+See our tutorials for example scripts on how to use the toolbox to extract digital measures from wrist sensor signals.
+The API reference contains detailed documentation of all toolbox modules and functions.
+The user guides provide additional information about specific topics (e.g. the required orientation of the wrist sensor).
+
+### Sensor data requirements
+The ParaDigMa toolbox is designed for the analysis of passive monitoring data collected using a wrist sensor in persons with PD. 
+
+Specific requirements include: 
+| Pipeline               | Sensor Configuration                                                                                                       | Context of Use                                                                                             |
+|------------------------|--------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
+| **All**               | - Sensor position: wrist-band on most or least affected side (validated for both, but different sensitivity for measuring disease progression for tremor and arm swing during gait).  <br> - Sensor orientation: orientation as described in [Coordinate System](https://biomarkersparkinson.github.io/paradigma/guides/coordinate_system.html). | - Population: persons with PD. <br> - Data collection protocol: passive monitoring in daily life. |
+| **Arm swing during gait** | - Accelerometer: minimum sampling rate of 100 Hz, minimum range of ± 4 g. <br> - Gyroscope: minimum sampling rate of 100 Hz, minimum range of ± 1000 degrees/sec. | - Population: no walking aid, no severe dyskinesia in the watch-sided arm. <br> - Compliance: for weekly measures: at least three compliant days (with ≥10 hours of data between 8 am and 10 pm), and at least 2 minutes of arm swing. |
+| **Tremor**            | - Gyroscope: minimum sampling rate of 100 Hz, minimum range of ± 1000 degrees/sec. | - Compliance: for weekly measures: at least three compliant days (with ≥10 hours of data between 8 am and 10 pm). |
+| **Pulse rate**        | - PPG*: minimum sampling rate of 30 Hz, green LED. <br> - Accelerometer: minimum sampling rate of 100 Hz, minimum range of ± 4 g. | - Population: no rhythm disorders (e.g. atrial fibrillation, atrial flutter). <br> - Compliance: for weekly measures: minimum average of 12 hours of data per day. |
+
+\* The processing of PPG signals is currently based on the blood volume pulse (arbitrary units) obtained from the Verily Study Watch, and we are currently testing the applicability of the pipeline to other PPG devices.
+
+> [!WARNING]
+> While the toolbox is designed to work on any wrist sensor device which fulfills the requirements, 
+we have currently verified its performance on data from the Gait-up Physilog 4 (arm swing during gait & tremor) and the Verily Study Watch (all pipelines). Furthermore, the specifications above are the minimally validated requirements. For example, while ParaDigMa works with accelerometer and gyroscope data sampled at 50 Hz, its effect on subsequent processes has not been empirically validated. 
+<br/>
+
+We have included support for [TSDF](https://biomarkersparkinson.github.io/tsdf/) as format for loading and storing sensor data. TSDF enables efficient data storage with added metadata. However, ParaDigMa does not require a particular method of data storage and retrieval. Please see our tutorial [Data preparation](https://biomarkersparkinson.github.io/paradigma/tutorials/data_preparation.html) for examples of loading TSDF and other data formats into memory, and for preparing raw sensor data as input for the processing pipelines.
+
+## Scientific validation
+
+The pipelines were developed and validated using data from the Parkinson@Home Validation study [[Evers et al. 2020]](https://pmc.ncbi.nlm.nih.gov/articles/PMC7584982/) 
+and the Personalized Parkinson Project [[Bloem et al. 2019]](https://pubmed.ncbi.nlm.nih.gov/31315608/). Details and validation of the different pipelines shall be shared in upcoming scientific publications.
+
+## Contributing
+
+We welcome contributions! Please check out our [contributing guidelines](https://biomarkersparkinson.github.io/paradigma/contributing.html). 
+Please note that this project is released with a [Code of Conduct](https://biomarkersparkinson.github.io/paradigma/conduct.html). By contributing to this project, you agree to abide by its terms.
+
+## License
+
+It is licensed under the terms of the Apache License 2.0 license. See [License](https://biomarkersparkinson.github.io/paradigma/license.html) for more details.
+
+## Acknowledgements
+
+The core team of ParaDigMa consists of Erik Post, Kars Veldkamp, Nienke Timmermans, Diogo Coutinho Soriano, Peter Kok, Vedran Kasalica and Luc Evers. 
+Advisors to the project are Max Little, Jordan Raykov, Twan van Laarhoven, Hayriye Cagnan, and Bas Bloem. 
+The initial release of ParaDigMa was funded by the Michael J Fox Foundation (grant #020425) and the Dutch Research Council (grant #ASDI.2020.060 & grant #2023.010).
+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).
+
+## Contact
+Questions, issues or suggestions about ParaDigMa? Please reach out to erik.post@radboudumc.nl, or open an issue in the GitHub repository.
+

{paradigma-0.4.2.dist-info → paradigma-0.4.3.dist-info}/RECORD

@@ -2,21 +2,21 @@ paradigma/__init__.py,sha256=vCLqo7vOEgcnYs10gUVYvEFfi8y-jBi7w1YKRoqn95k,127
 paradigma/assets/gait_detection_clf_package.pkl,sha256=8jCbuM_4dkilSjOEk9ss7bJbSppgzXe72y0X4BCnzCU,11497247
 paradigma/assets/gait_filtering_clf_package.pkl,sha256=lAaLyhmXdV4X_drmYt0EM6wGwSo80yhpxtncWGq4RfQ,3915
 paradigma/assets/ppg_quality_clf_package.pkl,sha256=vUcM4v8gZwWAmDVK7E4UcHhVnhlEg27RSB71oPGloSc,1292
-paradigma/assets/tremor_detection_clf_package.pkl,sha256=bZ7xrqTsCLg0CKBxVejgnnh8hnKSqNsf-bSQG7D2aqY,1613
+paradigma/assets/tremor_detection_clf_package.pkl,sha256=S-KsK1EcUBJX6oGGBo8GqU0AhNZThA6Qe-cs0QPcWw4,1475
 paradigma/classification.py,sha256=sBJSePvwHZNPUQuLdx-pncfnDzMq-1naomsCxSJneWY,2921
-paradigma/config.py,sha256=4F6FsY5HI6d-L_vB6zehyTAJK3X-U0F6IrLwxN9M-dw,11102
+paradigma/config.py,sha256=72KkIEVV1v5dD9ZJDPI-mFNvorA8nBADEcA0A-jviHU,11163
 paradigma/constants.py,sha256=JlrD4Zx66g7myQALYAc4Gw_y6yW5EipZuvwj9_fjjpI,3543
-paradigma/feature_extraction.py,sha256=pXfVoiuElrMzLCCZu1gj1uYT5v7vb3vULUjkxeJNWXQ,34566
+paradigma/feature_extraction.py,sha256=v_AwbBmvYo21XbULkOV6Ob_sZ1iboyXdDRRAsmCBh-Q,36061
 paradigma/pipelines/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-paradigma/pipelines/gait_pipeline.py,sha256=2mk7Tyfd5rXV2jGZamX5awpRnyJAsrq4kiJoeZVn4fM,29064
+paradigma/pipelines/gait_pipeline.py,sha256=guz6RZlM0muarxG_GtOMf117XqV0YMNPrK2KlyIP4Jg,26426
 paradigma/pipelines/heart_rate_pipeline.py,sha256=0-D9KcW9nwE5sgXsWHONkeKrsX6qZ5BYqjDttoffwL8,17726
 paradigma/pipelines/heart_rate_utils.py,sha256=aV2mTMWrFWHZD0KpHqy3IIC1onZykbppyp7_OUWxFTU,26764
-paradigma/pipelines/tremor_pipeline.py,sha256=hPqLf26MRperwlqpNgrwayByoP3aWwnWc-tQMSJNZGw,13314
-paradigma/preprocessing.py,sha256=DQ-lgmta1tng0neuWftwmXG3yesW6dxOsYvjSV2OFRk,13498
+paradigma/pipelines/tremor_pipeline.py,sha256=B5uZB3IP5pwb30PE4xztRbdYmZt4JQj193BRksC9N94,14590
+paradigma/preprocessing.py,sha256=-Vt_awvJe8MGqXACqWp7R6LWq6XFOcAVUyd0anNaytc,13506
 paradigma/segmenting.py,sha256=Jrz2JQX5eSfR9jBfpBhc6QV0SFmPVT5O6T8MyL0sdSw,13874
 paradigma/testing.py,sha256=DSbWeYl5HuZ-bNyOKwgwMHQGG8KlTabvGTR1Yzd-9CY,17955
-paradigma/util.py,sha256=6G-z6OXv8T2PS8RFjkd6IfDywdzTjvSl1pfNwqnT8i0,14431
-paradigma-0.4.2.dist-info/LICENSE,sha256=Lda8kIVC2kbmlSeYaUWwUwV75Q-q31idYvo18HUTfiw,9807
-paradigma-0.4.2.dist-info/METADATA,sha256=6fv07UQ2NQxQB8aE9vE3ECHIYqc65Ps8vl4KUPZCgIc,6416
-paradigma-0.4.2.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-paradigma-0.4.2.dist-info/RECORD,,
+paradigma/util.py,sha256=MEoe0zWigxwqy6aVd8zKdHifiuUTc9Mqyrh4xsy1oHY,14759
+paradigma-0.4.3.dist-info/LICENSE,sha256=bKdwckQhMGrkC7Ug3zvZpI556dNG0vQiPYZWPDRD7rs,9818
+paradigma-0.4.3.dist-info/METADATA,sha256=RFKmsnr-p0coG1lDKJVpFXP2Wca9O_8WPKlUenmW0_E,11288
+paradigma-0.4.3.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
+paradigma-0.4.3.dist-info/RECORD,,

{paradigma-0.4.2.dist-info → paradigma-0.4.3.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.0.1
+Generator: poetry-core 2.1.1
 Root-Is-Purelib: true
 Tag: py3-none-any

paradigma-0.4.2.dist-info/METADATA

@@ -1,138 +0,0 @@
-Metadata-Version: 2.3
-Name: paradigma
-Version: 0.4.2
-Summary: Paradigma - a toolbox for Digital Biomarkers for Parkinson's Disease
-License: Apache-2.0
-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
-Requires-Dist: pandas (>=2.1.4,<3.0.0)
-Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
-Requires-Dist: pytype (>=2024.4.11,<2025.0.0)
-Requires-Dist: scikit-learn (>=1.3.2,<1.6.1)
-Requires-Dist: tsdf (>=0.5.2,<0.6.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.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) |
-<!-- | **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
-The Parkinsons Disease Digital Markers (ParaDigMa) toolbox is a Python
-software package designed for processing passively collected wrist 
-sensor data to extract digital measures of motor and non-motor signs
-of Parkinson's disease (PD).  
-
-Specifically, the toolbox contains three data processing pipelines: 
-(1) arm swing during gait, (2) tremor, and (3) heart rate analysis.
-Furthermore, the toolbox contains general functionalities for signal
-processing and feature extraction, such as filtering, peak detection,
-and spectral analysis. The toolbox is designed to be user-friendly and
-modular, enabling researchers to easily extend the toolbox with new
-algorithms and functionalities. The toolbox is accompanied by a set of
-example scripts and notebooks for each domain that demonstrate how to use
-the toolbox for processing sensor data and extracting digital measures.
-
-It contains functionalities for processing the following sensor types:
-
-- Inertial Measurement Units (accelerometer, gyroscope)
-- Photoplethysmogram (PPG)
-
-## More about ParaDigMa
-The components of ParaDigMa are visually shown in the diagram below.
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/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:
-
-| Process | Description |
-| ---- | ---- |
-| Preprocessing | Ensuring that the sensor data is ready for further processing | 
-| Feature extraction | Creating features based on windowed views of the timestamps |
-| Classification | Making predictions using developed and validated classifiers | 
-| Quantification | Selecting specific features of interest |
-| Aggregation | Aggregating the features at a specified time-level |
-
-#### Domain requirements
-ParaDigMa can be used to extract aggregations related to a single or multiple domain(s). Each domain has its specific data requirements. Strict requirements for the domain are marked by X, soft requirements (for some additional functionalities) are marked by O.
-
-| | Gait | Tremor | Heart Rate |
-|----------|:-----------:|:-----------:|:-----------:|
-| **Accelerometer** | X | | O | 
-| **Gyroscope** | X | X | | 
-| **PPG** | | | X | 
-
-
-
-## 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.11 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
-```
-
-### Type checking
-
-```bash
-poetry run pytype .
-```
-
-### 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
-
-The core team of ParaDigMa consists of Erik Post, Kars Veldkamp, Nienke Timmermans, Diogo Coutinho Soriano, Luc Evers, 
-Peter Kok and Vedran Kasalica. Advisors to the project are Max Little, Jordan Raykov, Twan van Laarhoven, Hayriye Cagnan, and Bas Bloem. 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).
-
-## Contact
-
-For more information or questions about ParaDigMa, please reach out to erik.post@radboudumc.nl.