gh-k-dense-ai-claude-scientific-skills-scientific-skills/skills/neurokit2/references/bio_module.md

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.

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:

# 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.

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:

# 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.

bio_signals, bio_info = nk.bio_process(ecg=ecg, rsp=rsp, sampling_rate=1000)
results = nk.bio_analyze(bio_signals, sampling_rate=1000)

rsa = results['RSA']  # Automatically included

Computation:

• High-frequency HRV modulation by breathing
• Requires synchronized ECG R-peaks and respiratory signal
• Methods: Porges-Bohrer or peak-to-trough

Interpretation:

• Higher RSA: greater parasympathetic (vagal) influence
• Marker of cardiac-respiratory coupling
• Health indicator and emotion regulation capacity

ECG-Derived Respiration (EDR)

If respiratory signal unavailable, NeuroKit2 can estimate from ECG:

ecg_signals, ecg_info = nk.ecg_process(ecg, sampling_rate=1000)

# Extract EDR
edr = nk.ecg_rsp(ecg_signals['ECG_Clean'], sampling_rate=1000)

Use case:

• Estimate respiration when direct measurement unavailable
• Cross-validate respiratory measurements

Cardio-EDA Integration

Synchronized cardiac and electrodermal activity:

bio_signals, bio_info = nk.bio_process(ecg=ecg, eda=eda, sampling_rate=1000)

# Both signals available for integrated analysis
ecg_rate = bio_signals['ECG_Rate']
eda_phasic = bio_signals['EDA_Phasic']

# Compute correlations or coupling metrics
correlation = ecg_rate.corr(eda_phasic)

Practical Workflows

Complete Multi-Modal Recording Analysis

import neurokit2 as nk
import pandas as pd

# 1. Load multi-modal physiological data
ecg = load_ecg()        # Your data loading function
rsp = load_rsp()
eda = load_eda()
emg = load_emg()

# 2. Process all signals simultaneously
bio_signals, bio_info = nk.bio_process(
    ecg=ecg,
    rsp=rsp,
    eda=eda,
    emg=emg,
    sampling_rate=1000
)

# 3. Visualize processed signals
import matplotlib.pyplot as plt

fig, axes = plt.subplots(4, 1, figsize=(15, 12), sharex=True)

# ECG
axes[0].plot(bio_signals.index / 1000, bio_signals['ECG_Clean'])
axes[0].set_ylabel('ECG')
axes[0].set_title('Multi-Modal Physiological Recording')

# Respiration
axes[1].plot(bio_signals.index / 1000, bio_signals['RSP_Clean'])
axes[1].set_ylabel('Respiration')

# EDA
axes[2].plot(bio_signals.index / 1000, bio_signals['EDA_Phasic'])
axes[2].set_ylabel('EDA (Phasic)')

# EMG
axes[3].plot(bio_signals.index / 1000, bio_signals['EMG_Amplitude'])
axes[3].set_ylabel('EMG Amplitude')
axes[3].set_xlabel('Time (s)')

plt.tight_layout()
plt.show()

# 4. Analyze all signals
results = nk.bio_analyze(bio_signals, sampling_rate=1000)

# 5. Extract key metrics
print("Heart Rate (mean):", results['ECG_Rate_Mean'])
print("HRV (RMSSD):", results['HRV_RMSSD'])
print("Breathing Rate:", results['RSP_Rate_Mean'])
print("SCRs (count):", results['SCR_Peaks_N'])
print("RSA:", results['RSA'])

Event-Related Multi-Modal Analysis

# 1. Process signals
bio_signals, bio_info = nk.bio_process(ecg=ecg, rsp=rsp, eda=eda, sampling_rate=1000)

# 2. Detect events
events = nk.events_find(trigger_channel, threshold=0.5)

# 3. Create epochs for all signals
epochs = nk.epochs_create(bio_signals, events, sampling_rate=1000,
                          epochs_start=-1.0, epochs_end=10.0,
                          event_labels=event_labels,
                          event_conditions=event_conditions)

# 4. Signal-specific event-related analysis
ecg_eventrelated = nk.ecg_eventrelated(epochs)
rsp_eventrelated = nk.rsp_eventrelated(epochs)
eda_eventrelated = nk.eda_eventrelated(epochs)

# 5. Merge results
all_results = pd.merge(ecg_eventrelated, rsp_eventrelated,
                       left_index=True, right_index=True)
all_results = pd.merge(all_results, eda_eventrelated,
                       left_index=True, right_index=True)

# 6. Statistical comparison by condition
all_results['Condition'] = event_conditions
condition_means = all_results.groupby('Condition').mean()

Different Sampling Rates

Handle signals with different native sampling rates:

# ECG at 1000 Hz, EDA at 100 Hz
bio_signals, bio_info = nk.bio_process(
    ecg=ecg_1000hz,
    eda=eda_100hz,
    sampling_rate=1000  # Target sampling rate
)
# EDA will be automatically resampled to 1000 Hz internally

Or process separately and merge:

# Process at native sampling rates
ecg_signals, ecg_info = nk.ecg_process(ecg, sampling_rate=1000)
eda_signals, eda_info = nk.eda_process(eda, sampling_rate=100)

# Resample to common rate
eda_resampled = nk.signal_resample(eda_signals, sampling_rate=100,
                                   desired_sampling_rate=1000)

# Merge manually
bio_signals = pd.concat([ecg_signals, eda_resampled], axis=1)

Use Cases and Applications

Comprehensive Psychophysiology Research

Capture multiple dimensions of physiological arousal:

• Cardiac: Orienting, attention, emotional valence
• Respiratory: Arousal, stress, emotion regulation
• EDA: Sympathetic arousal, emotional intensity
• EMG: Muscle tension, facial expression, startle

Example: Emotional picture viewing

• ECG: Heart rate deceleration during picture viewing (attention)
• EDA: SCRs reflect emotional arousal intensity
• RSP: Breath-holding or changes reflect emotional engagement
• Facial EMG: Corrugator (frown), zygomaticus (smile) for valence

Stress and Relaxation Assessment

Multi-modal markers provide convergent evidence:

• Increased stress: ↑ HR, ↓ HRV, ↑ EDA, ↑ respiration rate, ↑ muscle tension
• Relaxation: ↓ HR, ↑ HRV, ↓ EDA, ↓ respiration rate, slow breathing, ↓ muscle tension

Intervention effectiveness:

• Compare multi-modal indices before vs. after intervention
• Identify which modalities respond to specific techniques

Clinical Assessment

Anxiety disorders:

• Heightened baseline EDA, HR
• Exaggerated responses to stressors
• Reduced HRV, respiratory variability

Depression:

• Altered autonomic balance (↓ HRV)
• Blunted EDA responses
• Irregular respiratory patterns

PTSD:

• Hyperarousal (↑ HR, ↑ EDA baseline)
• Exaggerated startle (EMG)
• Altered RSA

Human-Computer Interaction

Unobtrusive user state assessment:

• Cognitive load: ↓ HRV, ↑ EDA, suppressed blinks
• Frustration: ↑ HR, ↑ EDA, ↑ muscle tension
• Engagement: Moderate arousal, synchronized responses
• Boredom: Low arousal, irregular patterns

Athletic Performance and Recovery

Monitor training load and recovery:

• Resting HRV: Daily monitoring for overtraining
• EDA: Sympathetic activation and stress
• Respiration: Breathing patterns during exercise/recovery
• Multi-modal integration: Comprehensive recovery assessment

Advantages of Multi-Modal Recording

Convergent validity:

• Multiple indices converge on same construct (e.g., arousal)
• More robust than single measure

Discriminant validity:

• Different signals dissociate under certain conditions
• ECG reflects both sympathetic and parasympathetic
• EDA reflects primarily sympathetic

System integration:

• Understand whole-body physiological coordination
• Cross-signal coupling metrics (RSA, coherence)

Redundancy and robustness:

• If one signal quality poor, others available
• Cross-validate findings across modalities

Richer interpretation:

• HR deceleration + SCR increase = orienting with arousal
• HR acceleration + no SCR = cardiac response without sympathetic arousal

Considerations

Hardware and Synchronization

• Same device: Signals inherently synchronized
• Different devices: Requires common trigger/timestamp
  • Use hardware trigger to mark simultaneous events
  • Software alignment based on event markers
  • Verify synchronization quality (cross-correlate redundant signals)

Signal Quality Across Modalities

• Not all signals may have equal quality
• Prioritize based on research question
• Document quality issues per signal

Computational Cost

• Processing multiple signals increases computation time
• Consider processing in batches for large datasets
• Downsample appropriately to reduce load

Analysis Complexity

• More signals = more variables = more statistical comparisons
• Risk of Type I error (false positives) without correction
• Use multivariate approaches or pre-registered analyses

Interpretation

• Avoid over-interpretation of complex multi-modal patterns
• Ground in physiological theory
• Replicate findings before strong claims

References

• Berntson, G. G., Cacioppo, J. T., & Quigley, K. S. (1993). Respiratory sinus arrhythmia: autonomic origins, physiological mechanisms, and psychophysiological implications. Psychophysiology, 30(2), 183-196.
• Cacioppo, J. T., Tassinary, L. G., & Berntson, G. (Eds.). (2017). Handbook of psychophysiology (4th ed.). Cambridge University Press.
• Kreibig, S. D. (2010). Autonomic nervous system activity in emotion: A review. Biological psychology, 84(3), 394-421.
• Laborde, S., Mosley, E., & Thayer, J. F. (2017). Heart rate variability and cardiac vagal tone in psychophysiological research–recommendations for experiment planning, data analysis, and data reporting. Frontiers in psychology, 8, 213.