Metadata-Version: 2.4
Name: echogen
Version: 1.0.0
Summary: Synthetic 12-lead ECG signal generator for testing, teaching, and ML workflows
Author: echogen contributors
License: MIT License
        
        Copyright (c) 2026 echogen contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/your-org/echogen
Project-URL: Documentation, https://github.com/your-org/echogen#readme
Project-URL: Changelog, https://github.com/your-org/echogen/blob/main/CHANGELOG.md
Keywords: ecg,ekg,electrocardiogram,signal,synthetic,generator,biomedical,12-lead
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Provides-Extra: plot
Requires-Dist: matplotlib>=3.5; extra == "plot"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# echogen — synthetic 12-lead ECG signal generator

[![PyPI](https://img.shields.io/pypi/v/echogen)](https://pypi.org/project/echogen/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://pypi.org/project/echogen/)

`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

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

## Quick start (Python)

```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)

```bash
# 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](LICENSE).
