feat: implement adaptive frequency detection and auto-parameter adjustment

docs/guides/config.md

@@ -13,29 +13,54 @@ Configuration classes are organized into two categories:
 
 ## Sensor Configurations
 
-### IMUConfig
+ParaDigMa supports processing two types of sensors: IMU (accelerometer + gyroscope)
+and PPG.
 
-Configuration for inertial measurement unit (IMU) sensors (accelerometer + gyroscope):
+### Instantiating a configuration object
+
+To create a configuration object:
 
 ```python
-from paradigma.config import IMUConfig
+from paradigma.config import IMUConfig, PPGConfig
 
 imu_config = IMUConfig()
-imu_config.sampling_frequency = 100
+ppg_config = PPGConfig()
 ```
 
-**Parameters**
--
-### PPGConfig
+### Adaptive Frequency Handling
 
-Configuration for photoplethysmography (PPG) sensors:
+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.
 
 ```python
-from paradigma.config import PPGConfig
+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")
 
-ppg_config = PPGConfig()
 ```
 
+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.
+
+```python
+# 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:
@@ -54,26 +79,29 @@ Example with gait analysis:
 
 ```python
 from paradigma.config import IMUConfig, GaitConfig
-from paradigma.pipelines import run_paradigma
+from paradigma.orchestrator import run_paradigma
 
-imu_config = IMUConfig()
-imu_config.sampling_frequency = 100
+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. **Validation**: Ensure your sensor `sampling_frequency` matches your actual data
-2. **Column Names**: Verify that your DataFrame column names match the configuration
+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](https://biomarkersparkinson.github.io/paradigma/guides/sensor_requirements.html))
-4. **Documentation**: Document any custom configurations in your analysis code
+4. **Documentation**: Document any custom configurations (e.g., custom resampling rates)
+in your analysis code
 
 ## See Also
 

docs/guides/input_formats.md

@@ -158,7 +158,7 @@ results = run_paradigma(
 
 ## Data Preparation Parameters
 
-If your data needs preparation (unit conversion, resampling, etc.), ParaDigMa can handle it automatically:
+If your data needs preparation (unit conversion, changing watch orientation, etc.), ParaDigMa can handle it automatically:
 
 ```python
 results = run_paradigma(
@@ -171,9 +171,6 @@ results = run_paradigma(
     accelerometer_units='m/s^2',  # Auto-converts to 'g'
     gyroscope_units='rad/s',      # Auto-converts to 'deg/s'
 
-    # Resampling
-    target_frequency=100.0,
-
     # Time handling
     time_input_unit='relative_s',  # Or 'absolute_datetime'
 

docs/guides/sensor_requirements.md

@@ -11,6 +11,10 @@ All pipelines require data from a wrist-worn sensor with:
 - **Data Quality**: Strictly increasing timestamps
 - **Orientation**: Standardized coordinate system (see [Coordinate System Guide](coordinate_system.md))
 
+## Sampling Frequency Flexibility
+
+ParaDigMa is designed to work with various sampling frequencies. The orchestrator `run_paradigma` estimates the current sampling frequency and adjusts frequency-dependent parameters accordingly. For best results, use native sensor data without upsampling beforehand.
+
 ## Pipeline-Specific Requirements
 
 ### Arm Swing during Gait
@@ -19,8 +23,8 @@ All pipelines require data from a wrist-worn sensor with:
 
 | Specification | Minimum Requirement |
 |---------------|-------------------|
-| **Accelerometer** | Sampling rate ≥ 100 Hz<br>Range ≥ ± 4 g |
-| **Gyroscope** | Sampling rate ≥ 100 Hz<br>Range ≥ ± 1000 degrees/sec |
+| **Accelerometer** | Sampling rate ≥ 50 Hz<br>Range ≥ ± 4 g |
+| **Gyroscope** | Sampling rate ≥ 50 Hz<br>Range ≥ ± 1000 degrees/sec |
 
 #### Physical Units
 
@@ -53,7 +57,7 @@ For reliable weekly measures:
 
 | Specification | Minimum Requirement |
 |---------------|-------------------|
-| **Gyroscope** | Sampling rate ≥ 100 Hz<br>Range ≥ ± 1000 degrees/sec |
+| **Gyroscope** | Sampling rate ≥ 50 Hz<br>Range ≥ ± 1000 degrees/sec |
 
 #### Physical Units
 
@@ -130,6 +134,6 @@ results = run_paradigma(
 ## Important Notes on Validation
 
 > [!NOTE]
-> The specifications above represent **minimally validated requirements**. For example, while ParaDigMa works with accelerometer and gyroscope data sampled at 50 Hz, the effect on processing accuracy has not been empirically validated.
+> The specifications above represent **validated requirements**. ParaDigMa has been tested and verified to work correctly with sampling frequencies as low as 50 Hz.
 
 ---

docs/tutorials/_static/data_preparation.md

@@ -6,7 +6,9 @@ ParaDigMa requires the sensor data to be of a specific format. This tutorial pro
   * Triaxial gyroscope (x, y, z) in _deg/s_
   * Photoplethysmography (PPG)
 
-The final dataframe should be resampled to 100 Hz, have the correct units for the sensor columns, and the correct format for the time column. Also note that the _gait_ pipeline expects a specific orientation of sensor axes, as explained in [Coordinate system](../guides/coordinate_system).
+The final dataframe should have the correct units for the sensor columns and the correct format for the time column. Also note that the _gait_ pipeline expects a specific orientation of sensor axes, as explained in [Coordinate system](../guides/coordinate_system).
+
+Note that ParaDigMa automatically calculates the actual sampling frequency and resamples this to a uniform format, which happens _after_ data preparation.
 
 ## Import required modules