Neurokit2

# Multi-Signal Integration (Bio Module)

## Overview

The Bio module provides unified functions for processing and analyzing multiple physiological signals simultaneously. It acts as a wrapper that coordinates signal-specific processing functions and enables integrated multi-modal analysis.

## Multi-Signal Processing

### bio_process()

Process multiple physiological signals simultaneously with a single function call.

```python
bio_signals, bio_info = nk.bio_process(ecg=None, rsp=None, eda=None, emg=None,
                                       ppg=None, eog=None, sampling_rate=1000)
```

**Parameters:**
- `ecg`: ECG signal array (optional)
- `rsp`: Respiratory signal array (optional)
- `eda`: EDA signal array (optional)
- `emg`: EMG signal array (optional)
- `ppg`: PPG signal array (optional)
- `eog`: EOG signal array (optional)
- `sampling_rate`: Sampling rate in Hz (must be consistent across signals or specify per signal)

**Returns:**
- `bio_signals`: Unified DataFrame containing all processed signals with columns:
  - Signal-specific features (e.g., `ECG_Clean`, `ECG_Rate`, `EDA_Phasic`, `RSP_Rate`)
  - All detected events/peaks
  - Derived measures
- `bio_info`: Dictionary with signal-specific information (peak locations, parameters)

**Example:**
```python
# Process ECG, respiration, and EDA simultaneously
bio_signals, bio_info = nk.bio_process(
    ecg=ecg_signal,
    rsp=rsp_signal,
    eda=eda_signal,
    sampling_rate=1000
)

# Access processed signals
ecg_clean = bio_signals['ECG_Clean']
rsp_rate = bio_signals['RSP_Rate']
eda_phasic = bio_signals['EDA_Phasic']

# Access detected peaks
ecg_peaks = bio_info['ECG']['ECG_R_Peaks']
rsp_peaks = bio_info['RSP']['RSP_Peaks']
```

**Internal workflow:**
1. Each signal is processed by its dedicated processing function:
   - `ecg_process()` for ECG
   - `rsp_process()` for respiration
   - `eda_process()` for EDA
   - `emg_process()` for EMG
   - `ppg_process()` for PPG
   - `eog_process()` for EOG
2. Results are merged into unified DataFrame
3. Cross-signal features computed (e.g., RSA if both ECG and RSP present)

**Advantages:**
- Simplified API for multi-modal recording
- Unified time base for all signals
- Automatic cross-signal feature computation
- Consistent output format

## Multi-Signal Analysis

### bio_analyze()

Perform comprehensive analysis on processed multi-modal signals.

```python
bio_results = nk.bio_analyze(bio_signals, sampling_rate=1000)
```

**Parameters:**
- `bio_signals`: DataFrame from `bio_process()` or custom processed signals
- `sampling_rate`: Sampling rate (Hz)

**Returns:**
- DataFrame with analysis results for all detected signal types:
  - Interval-related metrics if duration ≥ 10 seconds
  - Event-related metrics if duration < 10 seconds
  - Cross-signal indices (e.g., RSA if ECG + RSP available)

**Computed metrics by signal:**
- **ECG**: Heart rate statistics, HRV indices (time, frequency, nonlinear domains)
- **RSP**: Respiratory rate statistics, RRV, amplitude measures
- **EDA**: SCR count, amplitude, tonic level, sympathetic indices
- **EMG**: Activation count, amplitude statistics
- **PPG**: Similar to ECG (heart rate, HRV)
- **EOG**: Blink count, blink rate

**Cross-signal metrics:**
- **RSA (Respiratory Sinus Arrhythmia)**: If ECG + RSP present
- **Cardiorespiratory coupling**: Phase synchronization indices
- **Multi-modal arousal**: Combined autonomic indices

**Example:**
```python
# Analyze processed signals
results = nk.bio_analyze(bio_signals, sampling_rate=1000)

# Access results
heart_rate_mean = results['ECG_Rate_Mean']
hrv_rmssd = results['HRV_RMSSD']
breathing_rate = results['RSP_Rate_Mean']
scr_count = results['SCR_Peaks_N']
rsa_value = results['RSA']  # If both ECG and RSP present
```

## Cross-Signal Features

When multiple signals are processed together, NeuroKit2 can compute integrated features:

### Respiratory Sinus Arrhythmia (RSA)

Automatically computed when both ECG and respiratory signals are present.

```pyth