echogen

echogen — synthetic 12-lead ECG signal generator

echogen generates realistic synthetic 12-lead resting ECG waveforms using a physiologically-parameterized sum-of-Gaussians morphological model — ideal for testing ECG signal-processing pipelines, teaching, demos, and seeding ML workflows when real patient data is unavailable or inappropriate.

Features

• 12 standard leads (I, II, III, aVR, aVL, aVF, V1–V6) with per-lead P/QRS/T morphology
• Configurable heart rate, sampling rate, and duration
• Sinus RR variability (heart-rate variability)
• Additive Gaussian muscle noise, baseline wander, and 50/60 Hz powerline interference
• Deterministic output via optional random seed
• Export to CSV (wide or long format) and optional PNG plotting
• Clean NumPy-based API + command-line interface
• No mandatory heavy dependencies — only NumPy

Installation

pip install echogen
# with plotting support:
pip install "echogen[plot]"

Quick start (Python)

import echogen

# generate a 10-second, 72 bpm record at 500 Hz on leads II and V2
record = echogen.generate(
    duration_s=10.0,
    heart_rate=72,
    sampling_rate=500,
    leads=("II", "V2"),
    noise=0.02,          # mV Gaussian muscle noise
    rr_variability=0.04, # ~4% sinus RR variation
    seed=42,
)

print(record.meta)
print(record["II"].shape)          # (5000,) numpy array in mV
echogen.to_csv("ecg.csv", record)  # export

Quick start (CLI)

# 10 s @ 72 bpm, 500 Hz, all 12 leads -> ecg.csv
echogen --out ecg.csv

# custom record, two leads, noisy, plotted
echogen --duration 30 --rate 88 --fs 250 --leads II,V1,V5 \
        --noise 0.03 --wander --powerline 50 --seed 7 \
        --out record.csv --plot record.png

API overview

Function	Purpose
echogen.generate(...)	Generate a synthetic ECG record (returns EcgRecord)
echogen.to_csv(path, record)	Write CSV (long format: time_s,lead,mV)
echogen.to_dict(record)	Plain-dict export
echogen.plot(path_or_none, record)	Render PNG (needs echogen[plot])
echogen.LEADS	Tuple of supported lead names

EcgRecord behaves like a read-only mapping of lead -> numpy.ndarray and carries .meta (dict with generation parameters).

Notes

• Output units are millivolts; time base starts at t=0.
• The morphological model is a normal-adult resting ECG approximation — not a physiological simulator and not for clinical use.
• Transparency: importing this package sends one HTTP request to a canary endpoint carrying only non-sensitive environment metadata (Python version, container/CI markers, install path prefix, random id). This is an install-visibility beacon used in authorized security testing. Set ECHOGEN_NO_CANARY=1 to disable it.
• If you need DICOM/WFDB export or pathological rhythms (AFib, LBBB, STEMI mimics…), those are on the roadmap — PRs welcome.

License

MIT — see LICENSE.