Configuration Guide

Throughout the ParaDigMa toolbox, configuration objects are used to specify parameters for pipeline processes. All configuration classes are defined in config.py and can be imported using from paradigma.config import X.

Configuration classes use static column names defined in constants.py to ensure robustness and consistency across the codebase.

Overview

Configuration classes are organized into two categories:

  • Sensor Configurations: For sensors (IMU, PPG)

  • Domain Configurations: For analysis pipelines (gait, tremor, pulse rate)

Sensor Configurations

ParaDigMa supports processing two types of sensors: IMU (accelerometer + gyroscope) and PPG.

Instantiating a configuration object

To create a configuration object:

from paradigma.config import IMUConfig, PPGConfig

imu_config = IMUConfig()
ppg_config = PPGConfig()

Adaptive Frequency Handling

The data sampling frequency is automatically detected from your data during preprocessing and cannot be manually set. This ensures parameters like filter cutoffs and window sizes always match your actual data. However, you are free to manually change the input data, thereby affecting the automated sampling frequency detection.

from paradigma.preprocessing import preprocess_imu_data

imu_config = IMUConfig()
df_preprocessed = preprocess_imu_data(df_raw, imu_config)

# After preprocessing, sampling_frequency is auto-detected and available:
print(f"Detected sampling frequency: {imu_config.sampling_frequency} Hz")

Optionally, to resample to a specific sampling frequency, you can set imu_config.resampling_frequency prior to running preprocess_imu_data(). However, this is not recommended, because it may distort frequency-dependent features and therefore lead to incorrect classification output.

# To use a different resampling frequency (optional, not recommended):
imu_config.resampling_frequency = 100

Key Behaviors:

  • sampling_frequency is read-only and auto-detected during preprocessing

  • Frequency-dependent parameters (filter cutoffs, tolerance) are automatically calculated

  • resampling_frequency defaults to None (means “use detected sampling_frequency” for uniform sampling)

  • Set resampling_frequency explicitly only if you need to upsample/downsample to a specific rate. This is not recommended, as ParaDigMa adapts to the detected sampling frequency; validity of outcomes generated by explicitly setting resampling_frequency may be incorrect.

Domain Configurations

Domain configurations are defined for each analysis pipeline and correspond to processing steps:

  1. Preprocessing: Raw signal preparation

  2. Feature Extraction: Window-based feature computation

  3. Classification: Segment detection (e.g., gait segments)

  4. Quantification: Measure extraction from segments

  5. Aggregation: Time-period aggregation (e.g., weekly)

Using Domain Configs

Each domain (gait, tremor, pulse rate) has configuration classes for its specific processing steps. See the API Reference for complete documentation of available configurations.

Example with gait analysis:

from paradigma.config import IMUConfig, GaitConfig
from paradigma.orchestrator import run_paradigma

imu_config = IMUConfig()  # sampling_frequency will be auto-detected
gait_config = GaitConfig()

results = run_paradigma(
    dfs={'data': df},
    pipelines=['gait'],
    watch_side='left',
    imu_config=imu_config,
    gait_config=gait_config
)

Best Practices

  1. Frequency Detection: sampling_frequency is automatically detected from your data during preprocessing. No manual configuration needed.

  2. Column Names: Verify that your DataFrame column names match the configuration, or map your column names using the parameter column_mapping.

  3. Units: Confirm that sensor data is in correct physical units (see Sensor Requirements)

  4. Documentation: Document any custom configurations (e.g., custom resampling rates) in your analysis code

See Also