biosignal-simulator 0.1.3

A classical signal processing library for generating synthetic physiological signals with realistic noise.

🌟 BioSignal Simulator (BSS)

Stress-test biomedical ML models and digital signal processing (DSP) filters under highly realistic physical noise.

Don't train physiological classifiers on pristine clinical databases and expect them to succeed in the wild. BSS generates clinical-grade clean bio-signals (ECG, EEG, EMG, PPG, EDA, respiration) and contaminates them with precise, parameterized physical noise engines (colored noise, electrode drift, motion artifacts, wearable packet loss).

---

⚡ Quick Start (Copy-Paste)

pip install biosignal-simulator

Generate a clean PPG signal, contaminate it with a ramping pink noise drift and motion artifacts, and export it to a clinical EDF file in under 10 lines of code:

import biosignal_simulator as bss

# 1. Configure and instantiate PPG generator
ppg_config = bss.PPGConfig(fs=125.0, duration_s=10.0, heart_rate=72.0)
ppg_generator = bss.PPGGenerator(ppg_config)

# 2. Schedule a ramping Pink (1/f) noise drift
pink_noise = bss.NoiseScheduler(
    noise_model=bss.ColoredNoise(exponent=1.0),
    schedule=bss.RampSchedule(control_times=[0.0, 10.0], levels=[0.0, 0.4])
)

# 3. Mix targeting exactly 12 dB SNR
mixed = bss.SignalMixer(
    signal_generator=ppg_generator,
    noise_models=[pink_noise],
    target_snr_db=12.0
).mix()

# 4. Symmetrically export to European Data Format (EDF)
bss.BiosignalExporter.export_edf(mixed, "ppg_stress_test.edf")

---

🎨 Interactive Visual Previews

1. Signal Composition Pipeline

The SignalMixer dynamically scales physical noise templates using scheduling envelopes (Ramps, Steps, Sigmoids) to meet your target SNR decibel constraint:

2. Contaminating Physical Noise Gallery

BSS models 10 distinct physical noise categories, including pink/brown flicker noise, electrode popcorn pops, motion transients, and wearable packet loss:

3. Interactive Metrics Dashboard

BSS automatically generates beautiful, diagnostic HTML dashboards with zoomable charts and Pan-Tompkins peak analysis to verify your DSP filters:

4. Clean Bio-Signal Waveform Showcase

BSS includes high-fidelity mathematical models and dynamical ODE systems for 6 core biosignal categories, generating clean, realistic baseline templates:

ECG (McSharry 12-Lead standard projection)	EEG (Delta, Theta, Alpha, Beta, Sleep states)
EMG (MUAP activation firing & pathology library)	PPG (Dual-wavelength & arterial stiffness)
EDA (Tonic SCL + Phasic SCR sweat responses)	Respiration (Eupnea, deep, rapid breathing)

---

🚀 Key Highlights

• 🧠 6 BioSignals: Clinical-grade generators for ECG (McSharry ODE, 12-lead projection), EEG (resting state, sleep stages, seizures), EMG (MUAPs, muscle fatigue), PPG (dual-wavelength, arterial stiffness), EDA (SCL/SCR decomposition), and Respiration (pathological patterns).
• ⚡ 10 Physical Noise Engines: Additive white Gaussian, colored ($1/f^\alpha$ Pink/Brown/Blue/Violet), baseline wander, powerline harmonics, motion transient impact bursts, electrode contact popcorn/thermal drift, muscle activity contamination, impulse spikes, ADC quantization, and wearable packet loss/sensor detachment.
• 🎛️ Dynamic Composer: Envelopes (Ramp, Sigmoid, Periodic, Stochastic) to schedule time-varying noise levels and target SNR decibel scalers.
• 💾 Symmetrical Exporters: Symmetrical round-trip reads and writes for EDF, WFDB Format 16/212, HDF5, CSV comments, and JSON metadata.
• 📈 Diagnostic Metrics: Bandpass and Wavelet SNR, Spectral Edge Frequency, SSIM, Pearson correlation, and Percent Residual Difference (PRD).

---

📖 Comprehensive Documentation

For detailed guides, class APIs, configuration schemas, mathematical background, and CLI options:

• 📘 BSS User Guide: Standard pipelines, setups, quick examples, and configurations.
• 📕 BSS Technical Reference Manual: Deep dive into all mathematical models, equations, 10 physical noises, metrics, clinical binary specs, validation, and benchmarking.

---

🧪 Robustness & Test Verification

BSS comes with a production-grade test suite checking physical parameters, mathematical boundaries, file roundtrips, and fuzzed signal invariants:

# Run the complete test suite
python -m pytest tests/ -v

All 1,443 test cases pass cleanly:

tests\test_composer.py .                                                 [  0%]
tests\test_composer_exhaustive_mixes.py .                                [ 15%]
tests\test_core_abstractions.py .                                        [ 22%]
...
tests\test_validation_engine_exhaustive.py .                             [100%]

============================ 1443 passed in 36.78s ============================