AI ECG SDK (`ai-ecg-sdk` / `ecg_sdk`)¶

A Modular, High-Performance Python Toolkit for Automated Electrocardiogram (ECG) Analysis, Clinical Paper Plotting, and Edge-to-Cloud Benchmarking

Overview¶

The AI ECG SDK (ecg_sdk) is an open-source, extensible Python library and benchmarking framework designed for researchers, biomedical engineers, and clinical AI developers. It provides end-to-end tooling for electrocardiogram (ECG) data modeling, physiological simulation, multi-metric filtering, fiducial wave delineation, feature extraction, supervised arrhythmia classification, foundation model embeddings, and tiered real-time streaming telemetry.

flowchart LR
    A[Raw ECG / PhysioNet / CSV] --> B[ECGSignal Container]
    S[McSharry Dynamical Generator] --> B
    B --> C[Preprocessing & SQI]
    C --> D[Classical Delineation & HRV]
    C --> E[ML Feature Extraction]
    C --> F[1D-CNN / Foundation Models]
    D --> G[Clinical Paper Plotting]
    E --> H[AAMI EC57 Inter-Patient Benchmarking]
    F --> H
    H --> I[Edge-Wearable Score EWSI & XAI WAS]

Quickstart & Interactive Example¶

Python CodeRendered Plot Result

import matplotlib.pyplot as plt
from ecg_sdk import generate_synthetic_ecg

# Generate a realistic 10-second 12-lead ECG
canonical_12 = ["I", "II", "III", "aVR", "aVL", "aVF", "V1", "V2", "V3", "V4", "V5", "V6"]
ecg_12lead = generate_synthetic_ecg(
    duration=10.0,
    sampling_rate=250.0,
    heart_rate=70.0,
    lead_names=canonical_12,
    random_seed=42
)

# Plot on standard clinical ECG paper (display_mode="paper" 1:1 scale by default)
fig, ax = ecg_12lead.plot_clinical(
    lead="II",
    duration=5.0,
    display_mode="paper",
    grid_style="clinical_pink",
    show_calibration_pulse=True,
    title="STANDARD DIAGNOSTIC ECG STRIP — LEAD II (25 mm/s, 10 mm/mV)"
)
plt.show()

Rendered Clinical ECG Strip

Standard 12-Lead Diagnostic ECG Report Layout¶

Full clinical diagnostic report arranging all 12 standard leads (\(3 \text{ rows} \times 4 \text{ columns}\)) with true electrophysiological \(R\)-wave progression and continuous Lead II rhythm strip:

12-Lead Clinical ECG Report

Key Highlights¶

Unified Multi-Lead Abstraction (ECGSignal): Immutable-friendly dataclass handling \(N\)-lead 2D arrays, time vector computation, zero-phase resampling, slicing, and 3 normalization strategies (zscore, minmax, robust).
Universal Multi-Source Dispatcher (load_ecg): Native streaming from PhysioNet databases (mitdb, incartdb, ptb-xl), local files, and synthetic models with ingestion-time sampling frequency standardization (target_fs) and proportional annotation rescaling.
Authentic 12-Lead Dynamical Generator: 3D vectorcardiographic simulation based on the McSharry-Clifford-Sameni attractor model with anatomically accurate \(R\)-wave progression (\(V_1 \to V_6\)), inverted \(a\text{VR}\) polarity, and cardiac arrhythmia injection (Bradycardia, Tachycardia, PVC, Asystole).
Clinical-Grade ECG Paper Plotting: Standard \(25\text{ mm/s}\) paper speed and \(10\text{ mm/mV}\) voltage gain millimeter grid, \(1\text{ mV} \times 0.2\text{ s}\) calibration pulse, inverted triangle \(R\)-peak annotations, sparse tick labeling, and dual display_mode="paper" (1:1 physical scale) vs display_mode="digital" (screen responsive) modes.
Inter-Patient Rigor: Full compliance with the ANSI/AAMI EC57 standard and strict DS1/DS2 inter-patient partitioning to eliminate data leakage.
Edge-to-Cloud Benchmarking: Sub-millisecond latency profiling, RAM tracking, FLOPs calculation, and the composite Edge-Wearable Suitability Index (\(EWSI\)).

Quick Installation¶

pip install ai-ecg-sdk

Or install from source with full developer dependencies:

git clone https://github.com/Carglglz/ai-ecg-sdk.git
cd ai-ecg-sdk
pip install -e ".[dev,docs]"

AI ECG SDK (ai-ecg-sdk / ecg_sdk)¶