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

paradigma/__init__.py

@@ -1,6 +1,15 @@
+"""
+ParaDigMa: Parkinson Digital Biomarker Analysis Toolbox
+"""
+
 # read version from installed package
 from importlib.metadata import version
 
 __version__ = version("paradigma")
 
-__all__ = []
+# Import main pipeline functions for easy access
+from .orchestrator import run_paradigma
+
+__all__ = [
+    "run_paradigma",
+]

paradigma/classification.py

@@ -1,14 +1,19 @@
-import numpy as np
 import pickle
-
 from pathlib import Path
+from typing import Any
+
+import numpy as np
 from sklearn.base import BaseEstimator
-from typing import Any, Optional
+from sklearn.preprocessing import StandardScaler
+
 
 class ClassifierPackage:
-    def __init__(self, classifier: Optional[BaseEstimator] = None, 
-                 threshold: Optional[float] = None, 
-                 scaler: Optional[Any] = None):
+    def __init__(
+        self,
+        classifier: BaseEstimator | None = None,
+        threshold: float | None = None,
+        scaler: Any | None = None,
+    ):
         """
         Initialize the ClassifierPackage with a classifier, threshold, and scaler.
 
@@ -25,13 +30,13 @@ class ClassifierPackage:
         self.threshold = threshold
         self.scaler = scaler
 
-    def transform_features(self, X) -> np.ndarray:
+    def transform_features(self, x) -> np.ndarray:
         """
         Transform the input features using the scaler.
 
         Parameters
         ----------
-        X : np.ndarray
+        x : np.ndarray
             The input features.
 
         Return
@@ -40,16 +45,28 @@ class ClassifierPackage:
             The transformed features.
         """
         if not self.scaler:
-            return X
-        return self.scaler.transform(X)
+            return x
+        return self.scaler.transform(x)
 
-    def predict_proba(self, X) -> float:
+    def update_scaler(self, x_train: np.ndarray) -> None:
+        """
+        Update the scaler used for feature transformation.
+
+        Parameters
+        ----------
+        x_train : np.ndarray
+            The training data to fit the scaler.
+        """
+        scaler = StandardScaler()
+        self.scaler = scaler.fit(x_train)
+
+    def predict_proba(self, x) -> float:
         """
         Make predictions using the classifier and apply the threshold.
 
         Parameters
         ----------
-        X : np.ndarray
+        x : np.ndarray
             The input features.
 
         Return
@@ -60,15 +77,15 @@ class ClassifierPackage:
         """
         if not self.classifier:
             raise ValueError("Classifier is not loaded.")
-        return self.classifier.predict_proba(X)[:, 1]
-    
-    def predict(self, X) -> int:
+        return self.classifier.predict_proba(x)[:, 1]
+
+    def predict(self, x) -> int:
         """
         Make predictions using the classifier and apply the threshold.
 
         Parameters
         ----------
-        X : np.ndarray
+        x : np.ndarray
             The input features.
 
         Return
@@ -79,8 +96,8 @@ class ClassifierPackage:
         """
         if not self.classifier:
             raise ValueError("Classifier is not loaded.")
-        return int(self.predict_proba(X) >= self.threshold)
-    
+        return int(self.predict_proba(x) >= self.threshold)
+
     def save(self, filepath: str | Path) -> None:
         """
         Save the ClassifierPackage to a file.
@@ -90,7 +107,7 @@ class ClassifierPackage:
         filepath : str
             The path to the file.
         """
-        with open(filepath, 'wb') as f:
+        with open(filepath, "wb") as f:
             pickle.dump(self, f)
 
     @classmethod
@@ -109,7 +126,7 @@ class ClassifierPackage:
             The loaded classifier package.
         """
         try:
-            with open(filepath, 'rb') as f:
+            with open(filepath, "rb") as f:
                 return pickle.load(f)
         except Exception as e:
-            raise ValueError(f"Failed to load classifier package: {e}") from e
+            raise ValueError(f"Failed to load classifier package: {e}") from e

paradigma/config.py

@@ -1,12 +1,16 @@
-from typing import Dict, List
-from paradigma.constants import DataColumns, DataUnits
+import warnings
+from dataclasses import asdict
+
 import numpy as np
 
+from paradigma.constants import DataColumns, DataUnits
+
+
 class BaseConfig:
     def __init__(self) -> None:
-        self.meta_filename = ''
-        self.values_filename = ''
-        self.time_filename = ''
+        self.meta_filename = ""
+        self.values_filename = ""
+        self.time_filename = ""
 
     def set_sensor(self, sensor: str) -> None:
         """Sets the sensor and derived filenames"""
@@ -14,8 +18,10 @@ class BaseConfig:
         self.set_filenames(sensor)
 
     def set_filenames(self, prefix: str) -> None:
-        """Sets the filenames based on the prefix. This method is duplicated from `gaits_analysis_config.py`.
-        
+        """Sets the filenames based on the prefix.
+
+        This method is duplicated from `gaits_analysis_config.py`.
+
         Parameters
         ----------
         prefix : str
@@ -25,79 +31,108 @@ class BaseConfig:
         self.time_filename = f"{prefix}_time.bin"
         self.values_filename = f"{prefix}_values.bin"
 
+
 class IMUConfig(BaseConfig):
+    """
+    IMU configuration that uses DataColumns() to dynamically map available channels.
+    Works even if only accelerometer or only gyroscope data is present.
+    """
 
-    def __init__(self) -> None:
+    def __init__(self, column_mapping: dict[str, str] | None = None) -> None:
         super().__init__()
-
-        self.set_filenames('IMU')
+        self.set_filenames("IMU")
 
         self.acceleration_units = DataUnits.ACCELERATION
         self.rotation_units = DataUnits.ROTATION
-
         self.axes = ["x", "y", "z"]
 
-        self.accelerometer_cols: List[str] = [
-            DataColumns.ACCELEROMETER_X,
-            DataColumns.ACCELEROMETER_Y,
-            DataColumns.ACCELEROMETER_Z,
-        ]
-        self.gyroscope_cols: List[str] = [
-            DataColumns.GYROSCOPE_X,
-            DataColumns.GYROSCOPE_Y,
-            DataColumns.GYROSCOPE_Z,
-        ]
-        self.gravity_cols: List[str] = [
-            DataColumns.GRAV_ACCELEROMETER_X,
-            DataColumns.GRAV_ACCELEROMETER_Y,
-            DataColumns.GRAV_ACCELEROMETER_Z,
+        # Generate a default mapping or override with user-provided mapping
+        default_mapping = asdict(DataColumns())
+        self.column_mapping = {**default_mapping, **(column_mapping or {})}
+
+        self.time_colname = self.column_mapping["TIME"]
+
+        self.accelerometer_colnames: list[str] = []
+        self.gyroscope_colnames: list[str] = []
+        self.gravity_colnames: list[str] = []
+
+        self.d_channels_accelerometer: dict[str, str] = {}
+        self.d_channels_gyroscope: dict[str, str] = {}
+
+        accel_keys = ["ACCELEROMETER_X", "ACCELEROMETER_Y", "ACCELEROMETER_Z"]
+        grav_keys = [
+            "GRAV_ACCELEROMETER_X",
+            "GRAV_ACCELEROMETER_Y",
+            "GRAV_ACCELEROMETER_Z",
         ]
+        gyro_keys = ["GYROSCOPE_X", "GYROSCOPE_Y", "GYROSCOPE_Z"]
 
-        self.d_channels_accelerometer = {
-            DataColumns.ACCELEROMETER_X: self.acceleration_units,
-            DataColumns.ACCELEROMETER_Y: self.acceleration_units,
-            DataColumns.ACCELEROMETER_Z: self.acceleration_units,
-        }
-        self.d_channels_gyroscope = {
-            DataColumns.GYROSCOPE_X: self.rotation_units,
-            DataColumns.GYROSCOPE_Y: self.rotation_units,
-            DataColumns.GYROSCOPE_Z: self.rotation_units,
+        if all(k in self.column_mapping for k in accel_keys):
+            self.accelerometer_colnames = [self.column_mapping[k] for k in accel_keys]
+
+            if all(k in self.column_mapping for k in grav_keys):
+                self.gravity_colnames = [self.column_mapping[k] for k in grav_keys]
+
+            self.d_channels_accelerometer = {
+                c: self.acceleration_units for c in self.accelerometer_colnames
+            }
+
+        if all(k in self.column_mapping for k in gyro_keys):
+            self.gyroscope_colnames = [self.column_mapping[k] for k in gyro_keys]
+
+            self.d_channels_gyroscope = {
+                c: self.rotation_units for c in self.gyroscope_colnames
+            }
+
+        self.d_channels_imu: dict[str, str] = {
+            **self.d_channels_accelerometer,
+            **self.d_channels_gyroscope,
         }
-        self.d_channels_imu = {**self.d_channels_accelerometer, **self.d_channels_gyroscope}
 
         self.sampling_frequency = 100
         self.resampling_frequency = 100
+        self.tolerance = 3 * 1 / self.sampling_frequency
         self.lower_cutoff_frequency = 0.2
         self.upper_cutoff_frequency = 3.5
         self.filter_order = 4
 
+        # Segmentation parameters for handling non-contiguous data
+        self.max_segment_gap_s = 1.5
+        self.min_segment_length_s = 1.5
+
 
 class PPGConfig(BaseConfig):
 
-    def __init__(self) -> None:
+    def __init__(self, column_mapping: dict[str, str] | None = None) -> None:
         super().__init__()
 
-        self.set_filenames('PPG')
+        self.set_filenames("PPG")
+
+        # Generate a default mapping or override with user-provided mapping
+        default_mapping = asdict(DataColumns())
+        self.column_mapping = {**default_mapping, **(column_mapping or {})}
 
-        self.ppg_colname = DataColumns.PPG
+        self.time_colname = self.column_mapping["TIME"]
+        self.ppg_colname = self.column_mapping["PPG"]
 
         self.sampling_frequency = 30
+        self.resampling_frequency = 30
+        self.tolerance = 3 * 1 / self.sampling_frequency
         self.lower_cutoff_frequency = 0.4
         self.upper_cutoff_frequency = 3.5
         self.filter_order = 4
 
-        self.d_channels_ppg = {
-            DataColumns.PPG: DataUnits.NONE
-        }
+        self.d_channels_ppg = {self.ppg_colname: DataUnits.NONE}
 
 
 # Domain base configs
 class GaitConfig(IMUConfig):
 
-    def __init__(self, step) -> None:
-        super().__init__()
+    def __init__(self, step, column_mapping: dict[str, str] | None = None) -> None:
+        # Pass column_mapping through to IMUConfig
+        super().__init__(column_mapping=column_mapping)
 
-        self.set_sensor('accelerometer')
+        self.set_sensor("accelerometer")
 
         # ----------
         # Segmenting
@@ -105,7 +140,7 @@ class GaitConfig(IMUConfig):
         self.max_segment_gap_s = 1.5
         self.min_segment_length_s = 1.5
 
-        if step == 'gait':
+        if step == "gait":
             self.window_length_s: float = 6
             self.window_step_length_s: float = 1
         else:
@@ -120,7 +155,7 @@ class GaitConfig(IMUConfig):
         self.spectrum_high_frequency: int = int(self.sampling_frequency / 2)
 
         # Power in specified frequency bands
-        self.d_frequency_bandwidths: Dict[str, List[float]] = {
+        self.d_frequency_bandwidths: dict[str, list[float]] = {
             "power_below_gait": [0.2, 0.7],
             "power_gait": [0.7, 3.5],
             "power_tremor": [3.5, 8],
@@ -140,7 +175,7 @@ class GaitConfig(IMUConfig):
         # -----------------
         # TSDF data storage
         # -----------------
-        self.d_channels_values: Dict[str, str] = {
+        self.d_channels_values: dict[str, str] = {
             "accelerometer_std_norm": DataUnits.GRAVITY,
             "accelerometer_x_grav_mean": DataUnits.GRAVITY,
             "accelerometer_y_grav_mean": DataUnits.GRAVITY,
@@ -148,29 +183,33 @@ class GaitConfig(IMUConfig):
             "accelerometer_x_grav_std": DataUnits.GRAVITY,
             "accelerometer_y_grav_std": DataUnits.GRAVITY,
             "accelerometer_z_grav_std": DataUnits.GRAVITY,
-            "accelerometer_x_power_below_gait": DataUnits.POWER_SPECTRAL_DENSITY,
-            "accelerometer_y_power_below_gait": DataUnits.POWER_SPECTRAL_DENSITY,
-            "accelerometer_z_power_below_gait": DataUnits.POWER_SPECTRAL_DENSITY,
-            "accelerometer_x_power_gait": DataUnits.POWER_SPECTRAL_DENSITY,
-            "accelerometer_y_power_gait": DataUnits.POWER_SPECTRAL_DENSITY,
-            "accelerometer_z_power_gait": DataUnits.POWER_SPECTRAL_DENSITY,
-            "accelerometer_x_power_tremor": DataUnits.POWER_SPECTRAL_DENSITY,
-            "accelerometer_y_power_tremor": DataUnits.POWER_SPECTRAL_DENSITY,
-            "accelerometer_z_power_tremor": DataUnits.POWER_SPECTRAL_DENSITY,
-            "accelerometer_x_power_above_tremor": DataUnits.POWER_SPECTRAL_DENSITY,
-            "accelerometer_y_power_above_tremor": DataUnits.POWER_SPECTRAL_DENSITY,
-            "accelerometer_z_power_above_tremor": DataUnits.POWER_SPECTRAL_DENSITY,
+            "accelerometer_x_power_below_gait": DataUnits.POWER_SPECTRAL_DENSITY_ACC,
+            "accelerometer_y_power_below_gait": DataUnits.POWER_SPECTRAL_DENSITY_ACC,
+            "accelerometer_z_power_below_gait": DataUnits.POWER_SPECTRAL_DENSITY_ACC,
+            "accelerometer_x_power_gait": DataUnits.POWER_SPECTRAL_DENSITY_ACC,
+            "accelerometer_y_power_gait": DataUnits.POWER_SPECTRAL_DENSITY_ACC,
+            "accelerometer_z_power_gait": DataUnits.POWER_SPECTRAL_DENSITY_ACC,
+            "accelerometer_x_power_tremor": DataUnits.POWER_SPECTRAL_DENSITY_ACC,
+            "accelerometer_y_power_tremor": DataUnits.POWER_SPECTRAL_DENSITY_ACC,
+            "accelerometer_z_power_tremor": DataUnits.POWER_SPECTRAL_DENSITY_ACC,
+            "accelerometer_x_power_above_tremor": DataUnits.POWER_SPECTRAL_DENSITY_ACC,
+            "accelerometer_y_power_above_tremor": DataUnits.POWER_SPECTRAL_DENSITY_ACC,
+            "accelerometer_z_power_above_tremor": DataUnits.POWER_SPECTRAL_DENSITY_ACC,
             "accelerometer_x_dominant_frequency": DataUnits.FREQUENCY,
             "accelerometer_y_dominant_frequency": DataUnits.FREQUENCY,
             "accelerometer_z_dominant_frequency": DataUnits.FREQUENCY,
         }
 
         for mfcc_coef in range(1, self.mfcc_n_coefficients + 1):
-            self.d_channels_values[f"accelerometer_mfcc_{mfcc_coef}"] = DataUnits.GRAVITY
+            self.d_channels_values[f"accelerometer_mfcc_{mfcc_coef}"] = (
+                DataUnits.GRAVITY
+            )
 
-        if step == 'arm_activity':
+        if step == "arm_activity":
             for mfcc_coef in range(1, self.mfcc_n_coefficients + 1):
-                self.d_channels_values[f"gyroscope_mfcc_{mfcc_coef}"] = DataUnits.GRAVITY
+                self.d_channels_values[f"gyroscope_mfcc_{mfcc_coef}"] = (
+                    DataUnits.GRAVITY
+                )
 
 
 class TremorConfig(IMUConfig):
@@ -184,7 +223,7 @@ class TremorConfig(IMUConfig):
         """
         super().__init__()
 
-        self.set_sensor('gyroscope')
+        self.set_sensor("gyroscope")
 
         # ----------
         # Segmenting
@@ -195,12 +234,12 @@ class TremorConfig(IMUConfig):
         # -----------------
         # Feature extraction
         # -----------------
-        self.window_type = 'hann'
+        self.window_type = "hann"
         self.overlap_fraction: float = 0.8
         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
@@ -223,95 +262,120 @@ class TremorConfig(IMUConfig):
         # -----------
         # Aggregation
         # -----------
-        self.aggregates_tremor_power: List[str] = ['mode_binned', 'median', '90p']
-        self.evaluation_points_tremor_power: np.ndarray = np.linspace(0, 6, 301) 
+        self.aggregates_tremor_power: list[str] = ["mode_binned", "median", "90p"]
+        self.evaluation_points_tremor_power: np.ndarray = np.linspace(0, 6, 301)
 
         # -----------------
         # TSDF data storage
         # -----------------
-        if step == 'features':
-            self.d_channels_values: Dict[str, str] = {}
+        if step == "features":
+            self.d_channels_values: dict[str, str] = {}
             for mfcc_coef in range(1, self.n_coefficients_mfcc + 1):
-                self.d_channels_values[f"mfcc_{mfcc_coef}"] = "unitless"
+                self.d_channels_values[f"mfcc_{mfcc_coef}"] = DataUnits.NONE
+
+            self.d_channels_values[DataColumns.FREQ_PEAK] = DataUnits.FREQUENCY
+            self.d_channels_values[DataColumns.BELOW_TREMOR_POWER] = (
+                DataUnits.POWER_ROTATION
+            )
+            self.d_channels_values[DataColumns.TREMOR_POWER] = DataUnits.POWER_ROTATION
 
-            self.d_channels_values["freq_peak"] = "Hz"
-            self.d_channels_values["below_tremor_power"] = "(deg/s)^2"
-            self.d_channels_values["tremor_power"] = "(deg/s)^2"
-        elif step == 'classification':
+        elif step == "classification":
             self.d_channels_values = {
                 DataColumns.PRED_TREMOR_PROBA: "probability",
                 DataColumns.PRED_TREMOR_LOGREG: "boolean",
                 DataColumns.PRED_TREMOR_CHECKED: "boolean",
-                DataColumns.PRED_ARM_AT_REST: "boolean"
+                DataColumns.PRED_ARM_AT_REST: "boolean",
             }
 
-        
+
 class PulseRateConfig(PPGConfig):
-    def __init__(self, sensor: str = 'ppg', min_window_length_s: int = 30) -> None:
+    def __init__(
+        self,
+        sensor: str = "ppg",
+        ppg_sampling_frequency: int = 30,
+        imu_sampling_frequency: int | None = None,
+        min_window_length_s: int = 30,
+        accelerometer_colnames: list[str] | None = None,
+    ) -> None:
         super().__init__()
 
-        # ----------
-        # Segmenting
-        # ----------
+        self.ppg_sampling_frequency = ppg_sampling_frequency
+
+        if sensor == "imu":
+            if imu_sampling_frequency is not None:
+                self.imu_sampling_frequency = imu_sampling_frequency
+            else:
+                self.imu_sampling_frequency = IMUConfig().sampling_frequency
+                warnings.warn(
+                    f"imu_sampling_frequency not provided, using default "
+                    f"of {self.imu_sampling_frequency} Hz"
+                )
+
+        # Windowing parameters
         self.window_length_s: int = 6
         self.window_step_length_s: int = 1
         self.window_overlap_s = self.window_length_s - self.window_step_length_s
 
-        self.accelerometer_cols = IMUConfig().accelerometer_cols
+        self.accelerometer_colnames = accelerometer_colnames
 
-        # -----------------------
-        # Signal quality analysis
-        # -----------------------
-        self.freq_band_physio = [0.75, 3] # Hz
-        self.bandwidth = 0.2   # Hz      
-        self.freq_bin_resolution = 0.05 # Hz
+        # Signal quality analysis parameters
+        self.freq_band_physio = [0.75, 3]  # Hz
+        self.bandwidth = 0.2  # Hz
+        self.freq_bin_resolution = 0.05  # Hz
 
-        # ---------------------
-        # Pulse rate estimation
-        # ---------------------
-        self.set_tfd_length(min_window_length_s)  # Set tfd length to default of 30 seconds
+        # Pulse rate estimation parameters
         self.threshold_sqa = 0.5
         self.threshold_sqa_accelerometer = 0.10
 
+        # Set initial sensor and update sampling-dependent params
+        self.set_sensor(sensor, min_window_length_s)
+
+    def set_sensor(self, sensor: str, min_window_length_s: int | None = None) -> None:
+        """Sets the active sensor and recomputes sampling-dependent parameters."""
+        if sensor not in ["ppg", "imu"]:
+            raise ValueError(f"Invalid sensor type: {sensor}")
+        self.sensor = sensor
+
+        # Decide which frequency to use
+        self.sampling_frequency = (
+            self.imu_sampling_frequency
+            if sensor == "imu"
+            else self.ppg_sampling_frequency
+        )
+
+        # Update all frequency-dependent parameters
+        if min_window_length_s is not None:
+            self._update_sampling_dependent_params(min_window_length_s)
+        else:
+            # Reuse previous tfd_length if it exists, else fallback to 30
+            self._update_sampling_dependent_params(getattr(self, "tfd_length", 30))
+
+    def _update_sampling_dependent_params(self, tfd_length: int):
+        """Compute attributes that depend on sampling frequency."""
+
+        # --- PPG-dependent parameters ---
+        self.tfd_length = tfd_length
+        self.min_pr_samples = int(round(self.tfd_length * self.ppg_sampling_frequency))
+
         pr_est_length = 2  # pulse rate estimation length in seconds
-        self.pr_est_samples = pr_est_length * self.sampling_frequency
+        self.pr_est_samples = pr_est_length * self.ppg_sampling_frequency
 
         # Time-frequency distribution parameters
-        self.kern_type = 'sep'
-        win_type_doppler = 'hamm'
-        win_type_lag = 'hamm'
+        win_type_doppler = "hamm"
+        win_type_lag = "hamm"
         win_length_doppler = 8
         win_length_lag = 1
-        doppler_samples = self.sampling_frequency * win_length_doppler
-        lag_samples = win_length_lag * self.sampling_frequency
+        doppler_samples = self.ppg_sampling_frequency * win_length_doppler
+        lag_samples = win_length_lag * self.ppg_sampling_frequency
+        self.kern_type = "sep"
         self.kern_params = {
-            'doppler': {
-                'win_length': doppler_samples,
-                'win_type': win_type_doppler,
-            },
-            'lag': {
-                'win_length': lag_samples,
-                'win_type': win_type_lag,
-            }
+            "doppler": {"win_length": doppler_samples, "win_type": win_type_doppler},
+            "lag": {"win_length": lag_samples, "win_type": win_type_lag},
         }
 
-        self.set_sensor(sensor)
-
-    def set_tfd_length(self, tfd_length: int):
-        self.tfd_length = tfd_length
-        self.min_pr_samples = int(round(self.tfd_length * self.sampling_frequency))
-
-    def set_sensor(self, sensor):
-        self.sensor = sensor 
-
-        if sensor not in ['ppg', 'imu']:
-            raise ValueError(f"Invalid sensor type: {sensor}")
-        
-        if sensor == 'imu':
-            self.sampling_frequency = IMUConfig().sampling_frequency
-        else:
-            self.sampling_frequency = PPGConfig().sampling_frequency
-
+        # --- Welch / FFT parameters based on current sensor frequency ---
         self.window_length_welch = 3 * self.sampling_frequency
         self.overlap_welch_window = self.window_length_welch // 2
-        self.nfft = len(np.arange(0, self.sampling_frequency/2, self.freq_bin_resolution))*2
+        self.nfft = (
+            len(np.arange(0, self.sampling_frequency / 2, self.freq_bin_resolution)) * 2
+        )