echogen

Synthetic 12-lead ECG signal generator for testing, teaching, and ML workflows

PyPI

Version: 1.0.0

Weekly downloads: 8

Maintainers: 1

Created: 3 weeks ago

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.