ECGBench

Reproducible ECG benchmark datasets with standardised splits, validation, and Croissant metadata.

ECGBench provides a curated catalogue of 64 publicly available ECG datasets, a config-driven pipeline for generating validated fold splits, and a unified PyTorch Dataset class for loading any supported dataset.

Website: vlbthambawita.github.io/ECGBench

Installation

Base (config, catalogue, validation, splitting)

pip install ecgbench

With PyTorch support

pip install ecgbench[torch]

With everything

pip install ecgbench[all]

From source (development)

git clone https://github.com/vlbthambawita/ECGBench.git
cd ECGBench
uv pip install -e ".[dev]"

Quick Start

from ecgbench import ECGDataset, ecg_collate_fn
from torch.utils.data import DataLoader

# Load PTB-XL training data (downloads fold CSVs from HuggingFace Hub)
train_ds = ECGDataset("ptbxl", split="train", data_path="/path/to/ptb-xl/1.0.3/")
loader = DataLoader(train_ds, batch_size=32, collate_fn=ecg_collate_fn)

for batch in loader:
    signals = batch["signal"]   # (B, 12, 5000) float32 tensor
    ecg_ids = batch["record_id"]
    break

Dataset Catalogue

Query the curated index of 64 ECG datasets:

import ecgbench

# List all datasets
datasets = ecgbench.list_datasets()
print(f"{len(datasets)} datasets available")

# Search by name, origin, format, or paper
ecgbench.search("PTB-XL")

# Filter by category and access type
ecgbench.search(category="12-Lead (PhysioNet)", access="Open")

# Look up a single dataset
ecgbench.get_dataset("MIMIC-IV-ECG")

# List categories
ecgbench.categories()

# Get as pandas DataFrame
df = ecgbench.to_dataframe()

Loading ECG Data

Standard train/val/test splits

from ecgbench import ECGDataset, ecg_collate_fn
from torch.utils.data import DataLoader

train_ds = ECGDataset("ptbxl", split="train", data_path="/data/ptb-xl/1.0.3/")
val_ds = ECGDataset("ptbxl", split="val", data_path="/data/ptb-xl/1.0.3/")
test_ds = ECGDataset("ptbxl", split="test", data_path="/data/ptb-xl/1.0.3/")

loader = DataLoader(train_ds, batch_size=32, collate_fn=ecg_collate_fn)

Selecting specific folds

fold_numbers picks individual folds out of a split. Folds are 1-indexed.

ECGDataset("ptbxl", split="train", fold_numbers=[3], data_path="...")       # one fold
ECGDataset("ptbxl", split="train", fold_numbers=[1, 2, 5], data_path="...") # several

Each fold belongs to exactly one split — 1-8 under train/, 9 under val/, 10 under test/ — so split="train", fold_numbers=[9] is an error. To select folds regardless of that layout, for custom cross-validation, pass split=None:

# Hold out fold 7 as test and fold 10 as val, train on the other eight.
test  = ECGDataset("ptbxl", split=None, fold_numbers=[7],  data_path="...")
val   = ECGDataset("ptbxl", split=None, fold_numbers=[10], data_path="...")
train = ECGDataset("ptbxl", split=None,
                  fold_numbers=[n for n in range(1, 11) if n not in (7, 10)],
                  data_path="...")

split=None requires fold_numbers, and each returned sample's ["split"] reports the record's own default split rather than one name for the whole set. Unlike stitching per-split datasets together with ConcatDataset, this returns a single ECGDataset, so .metadata_df and .labels_df still describe the whole selection.

Labels

Fold CSVs are identification-only by design — record ID, patient ID, signal paths, fold, split. Ground truth stays with the source dataset, so labels=True needs a local copy of it:

ds = ECGDataset("ptbxl", split="train", data_path="/data/ptb-xl/1.0.3/", labels=True)

ds[0]["labels"]["superclasses"]   # ['MI', 'STTC']  — multi-label
ds[0]["labels"]["report"]         # the cardiologist's text
ds.labels_df                      # the whole split's labels, aligned to metadata_df

Or without a Dataset at all, for class weights and filtering:

from ecgbench import load_labels

labels = load_labels("chapman_shaoxing", data_path="/data/chapman-figshare/")
labels["Rhythm"].value_counts()

Each dataset exposes its own fields — SCP codes plus diagnostic super/subclasses for PTB-XL, SNOMED-CT codes for ecg_arrhythmia, rhythm/beat annotations and eleven automated measurements for chapman_shaoxing, free-text machine reports plus nine interval/axis measurements for mimic_iv_ecg, reference beat counts for incartdb. A dataset that genuinely has none (mimic_iv_ecg_demo) raises LabelsUnavailableError naming where labels could come from, rather than returning empty columns.

Leads and units

Select and reorder leads by name, and choose the output unit:

ds = ECGDataset("mimic_iv_ecg_demo", split="train", data_path="...",
                leads=["I", "II", "aVL", "V5"], units="uV")

ds[0]["signal"].shape   # (4, 5000)
ds.lead_names           # ('I', 'II', 'aVL', 'V5')
ds.units                # 'uV'

Names, not indices, because lead order is not consistent across datasets:

signal[4] is aVL in most of them and aVF in both MIMIC datasets, so slicing by index across datasets silently crosses two leads. Matching is case-insensitive — leads=["aVL"] works on the lowercase datasets too — an unknown lead lists what is available, and a duplicate is rejected.

PTBDB is the one dataset that is not 12-lead: it stores 15 signals, the conventional twelve plus the three Frank vectorcardiography leads. leads= is how you take the standard twelve out of it. Its records are also variable length (32 s to 120 s), so batching needs a fixed window= — see examples/load_ptbdb.py.

incartdb is the one dataset whose primary labels are reference beat annotations rather than record-level diagnoses: 175,907 manually corrected beats over ten types, exposed as per-record counts (beat_N, beat_V, …, pvc_fraction) alongside the patient diagnosis and free-text per-record findings. Its records are 1800 s (~44 MB each), so batching needs a window=. It is also the clearest case for patient-grouped folds — 3,166 of its 3,174 RBBB beats come from a single patient — see examples/load_incartdb.py.

brugada_huca is the smallest and cleanest dataset here — 363 records, one per subject, all 363 passing validation — and the only one sampled at 100 Hz alone (PTB-XL offers 100 Hz as an alternative to 500). Its labels are bare integers with no string form in the CSV: brugada is 0 healthy / 1 confirmed / 2 other-atypical, and ecgbench.splitting.strategies.brugada_huca.BRUGADA_CLASSES carries the meanings. Treat it as a screening cohort: class 0 means "investigated and not diagnosed", not a general-population control. See examples/load_brugada_huca.py.

mimic_iv_ecg is the largest dataset here — 800,035 records from 161,352 patients (~96.5 GB) — and the one where fold_numbers= matters most: a single fold is a tenth of it. Two facts to know before using its labels. They are free-text machine reports (up to 18 lines per study, joined into report_text), not codes, and primary_report is only the first line, which is sometimes a data-quality warning rather than a rhythm. And its numeric measurements encode "not measurable" as integer sentinels — 29999, 32767, 65535 — which ECGBench converts to NaN; read the CSV yourself and a mean P-wave axis comes out meaningless. See examples/load_mimic_iv_ecg.py. Its 659-record open demo is a separate config, mimic_iv_ecg_demo, which has no labels at all.

challenge2021 is the one dataset where sampling rate varies per record (257/500/1000 Hz), because it concatenates eight source cohorts. Rate is therefore a label to filter on, not a sampling_rate= argument, and record length spans 5 s to 1800 s so batching needs a window= too. It also contains PTB-XL, PTBDB, INCART, CPSC-2018, Chapman-Shaoxing and Ningbo — its source label says which cohort each record came from, and evaluating on any of those after training on it is testing on training data. See examples/load_challenge2021.py.

Both are read-time adapters: they shape the returned tensor only. Source files, fold CSVs and validation are untouched — a record excluded for a flat V6 stays excluded even if you never load V6.

ECGDataset parameters

Sample windows

window=(start, length) returns a fixed slice of each record, in samples:

first  = ECGDataset("ptbxl", split="train", data_path="...", window=(0, 2500))
second = ECGDataset("ptbxl", split="train", data_path="...", window=(2500, 2500))
first[0]["signal"].shape    # (12, 2500) -- samples 0-2499
second[0]["signal"].shape   # (12, 2500) -- samples 2500-4999

length=None reads to the end of the record. Prefer window= over a cropping transform for two reasons:

• It is pushed down into the reader, so only those samples are decoded. On long records that is a large difference — incartdb goes from ~106 ms to ~8 ms per record; on 10-second records it changes nothing.
• It is picklable. transform=lambda x: x[:, :2500] fails in a DataLoader(num_workers>0) under the spawn start method, the default on macOS and Windows. window= works under both fork and spawn.

A window that does not fit raises WindowOutOfRangeError, naming the record and its true length. Record length is not constant in every dataset — cpsc_2018 runs 6-144 s and ptbdb 32-120 s — so a fixed window can fit most records and not all.

window combines freely with fold_numbers, leads and units; it is applied first, then lead selection, then units, then transform.

Derived datasets (annotations for another dataset's records)

Some releases contain no recordings of their own — they annotate someone else's. There are two: PTB-XL+ (3 feature tables, 2 statement tables, derived median beats and 283,326 fiducial-point files, all keyed by PTB-XL's ecg_id) and MIMIC-IV-ECG-Ext-ICD (ICD-10-CM discharge diagnoses for all 800,035 MIMIC-IV-ECG studies, keyed by study_id).

Those get no config and no splits, deliberately. Their records are the host dataset's, so generating folds would create a second ECGBench partition of the same recordings and let someone train on one and evaluate on the other. They are label providers instead: load the host on its own folds and join.

from ecgbench import ECGDataset
from ecgbench.labels.ptbxl_plus import load_ptbxl_plus

ds = ECGDataset("ptbxl", split="train", data_path="/data/ptb-xl/1.0.3/", labels=True)
plus = load_ptbxl_plus("/data/ptb-xl-plus/1.0.1/", features=("unig",))

joined = plus.reindex(ds.metadata_df["ecg_id"].values)   # 17,376 of 17,376
joined.iloc[0]["ptbxl_scp_codes"]     # [('NORM', 100.0), ('LVOLT', 100.0), ('SR', 100.0)]
joined.iloc[0]["12sl_statements"]     # ['NSR', 'NML']  -- the algorithm's opinion
joined.iloc[0]["unig_QRS_Dur_Global"] # 86.0 ms

You need both downloads, since PTB-XL+ has no waveforms. Feature columns are provider-prefixed because the three providers reuse names. See examples/load_ptbxl_plus.py, and the dataset page for the release's own defects — notably that 12sl_features.csv ships with no key column.

Ext-ICD works the same way, and adds one wrinkle worth knowing: it ships the upstream authors' own 20-fold split alongside the labels, which is independent of ECGBench's 10 folds. Reproduce published numbers on one or work on ECGBench's folds on the other, but never cross them.

from ecgbench.labels.mimic_iv_ecg_ext_icd import label_set, load_ext_icd, multi_hot

# prefix= because MIMIC-IV-ECG's own label frame also carries ecg_time.
icd = load_ext_icd("/data/mimic-iv-ecg-ext-icd-labels/1.0.1/", prefix="icd_")
codes = label_set(icd, prefix="icd_")          # 1076, the published label set
targets = multi_hot(icd.head(1000), codes, prefix="icd_")

Only 58.5% of its records carry a diagnosis at all, and the empty ones are empty lists rather than nulls — see examples/load_mimic_iv_ecg_ext_icd.py.

Restricted and credentialed datasets

Most datasets' fold CSVs are published to the HuggingFace Hub and download automatically. Some are deliberately not, and those you generate yourself.

Fold CSVs carry identifiers only — record ID, patient ID, signal path, fold, split. For an openly licensed source that is uncontroversial. For a credentialed or restricted source those identifiers are still data derived under a use agreement, and the ECGBench Hub repository is public and ungated, so ECGBench does not publish them. mimic_iv_ecg is the current example: 800,035 study_ids and 161,352 subject_ids stay with the people who signed the PhysioNet DUA.

Such a dataset declares this in its config, and the tooling enforces it in both directions — ecgbench upload refuses to publish it, and ECGDataset raises SplitsNotPublishedError (carrying the command below) instead of a 404:

publish_fold_csvs: false
no_publish_reason: >
  MIMIC-IV-ECG is credentialed under the PhysioNet Credentialed Health Data
  Use Agreement, so ECGBench does not republish its identifiers ...

The split is distributed as a recipe instead. Because fold assignment is a deterministic function of the input table and a fixed seed, regenerating locally reproduces the canonical partition exactly:

# 1. Generate — writes output/<slug>/ plus a manifest.json
ecgbench splits --dataset mimic_iv_ecg --data-path /path/to/mimic-iv-ecg/1.0/

# 2. Verify it is the canonical partition, not merely a plausible one
python -c "from ecgbench import verify_splits; \
           print(verify_splits('mimic_iv_ecg', 'output/mimic_iv_ecg')['ok'])"

# 3. Point the loader at your generated folds
cp -r output/mimic_iv_ecg/{clean,original} /path/to/mimic-iv-ecg/1.0/

ds = ECGDataset("mimic_iv_ecg", split="train", metadata_source="local",
                data_path="/path/to/mimic-iv-ecg/1.0/", labels=True)

manifest.json is what makes "regenerate it yourself" trustworthy. ecgbench splits writes one for every dataset, recording the seed, fold count, grouping column, a SHA-256 of each input file, the record counts, and a fold digest — a hash over the entire record-to-fold mapping in canonical order. Two runs agree on that digest if and only if they produced the same partition. verify_splits() compares yours against a reference manifest shipped in the package and, on mismatch, names the input file that differs.

That last part is the common failure. A split only reproduces if the input is byte-identical, and local copies get filtered: we found a machine_measurements.csv cut to 789,481 of 800,035 rows, which silently changes the stratification and hence the folds. Verify your download against the provider's own checksums before generating.

Output format

Each sample is a dict:

• signal -- float32 tensor (leads, samples), in millivolts unless units="uV"
• record_id -- record identifier
• split, fold -- split name and fold number
• labels -- dict of the dataset's label and metadata fields (only with labels=True)
• All other CSV columns as tensors (numeric) or raw values (str/dict)

The dataset object also carries ds.lead_names and ds.units, so the tensor is self-describing.

Data Versions

• clean (default): only records that pass all quality checks
• original: all records with is_valid and quality_issues columns

Both versions share identical fold assignments. Use original when you need all records or want to filter manually; use clean for standard benchmarking.

Validation

ECGBench validates every signal file before splitting:

• missing_leads -- lead entirely NaN or all-zero
• nan_values -- any NaN in signal
• truncated_signal -- fewer samples than expected
• flat_line -- lead with near-zero variance
• corrupt_header -- unreadable signal file
• amplitude_outlier -- samples outside physiological range

Results are saved in validation_report.json with per-record details.

Croissant Metadata

Both clean/ and original/ versions include MLCommons Croissant 1.1 JSON-LD metadata (croissant.json) with SHA-256 hashes for reproducibility. The full pipeline generates both automatically. For standalone generation:

ecgbench croissant --dataset ptbxl --splits-dir output/ptbxl/clean/ --version clean
ecgbench croissant --dataset ptbxl --splits-dir output/ptbxl/original/ --version original

Adding a New Dataset

1. Copy ecgbench/data/configs/_template.yaml to <slug>.yaml, fill in fields
2. Run ecgbench splits --dataset <slug> --data-path /path/to/data/
3. Check validation_report.json -- review excluded records
4. If custom logic needed, create ecgbench/splitting/strategies/<slug>.py with @register("<slug>")
5. Run pytest
6. Upload: ecgbench upload --data-dir output/ --datasets <slug>

CLI

Installing ecgbench adds a single ecgbench console command with three subcommands:

ecgbench --help               # top-level help
ecgbench <command> --help     # per-subcommand flags
ecgbench --version            # package version

Every subcommand has an equivalent Python function (run_splits, run_croissant, run_upload) with the same arguments, so the same workflow can be driven from a notebook or downstream code.

ecgbench splits

Runs the full pipeline: validate -> split -> export -> Croissant. Writes output/<dataset>/{original,clean}/ by default.

ecgbench splits --dataset ptbxl --data-path /path/to/ptb-xl/1.0.3/
ecgbench splits --dataset ptbxl                        # auto-download
ecgbench splits --dataset chapman_shaoxing \
    --data-path /data/chapman/ \
    --output-dir /data/outputs/chapman/ \
    --n-folds 10 --max-workers 8

# PhysioNet ecg-arrhythmia (45,152 records, Chapman-Shaoxing + Ningbo).
# Ships no metadata CSV — the splitter builds ecgbench_metadata.csv from the
# per-record WFDB headers on first run, so the data directory must be writable.
ecgbench splits --dataset ecg_arrhythmia \
    --data-path /data/ecg-arrhythmia/1.0.0/ --max-workers 32

Python equivalent:

import ecgbench

result = ecgbench.run_splits(
    dataset="ptbxl",
    data_path="/path/to/ptb-xl/1.0.3/",
    output_dir=None,          # -> output/ptbxl/
    sampling_rate=None,       # -> config default_sampling_rate
    n_folds=10,
    max_workers=4,
    skip_validation=False,
    skip_croissant=False,
)
# result is a dict with: dataset, dataset_name, output_dir,
# original={total,train,val,test}, clean={total,train,val,test}, excluded

ecgbench croissant

Standalone Croissant 1.1 JSON-LD generator for an existing splits directory. Run once per version (clean and original).

ecgbench croissant --dataset ptbxl --splits-dir output/ptbxl/clean/    --version clean
ecgbench croissant --dataset ptbxl --splits-dir output/ptbxl/original/ --version original
ecgbench croissant --dataset ptbxl --splits-dir output/ptbxl/clean/ --validate

Python equivalent:

from pathlib import Path
import ecgbench

saved_path: Path = ecgbench.run_croissant(
    dataset="ptbxl",
    splits_dir="output/ptbxl/clean/",
    output=None,              # -> splits_dir/croissant.json
    version="clean",
    validate=True,            # raises RuntimeError if the file does not validate
)

Requires the croissant extra (pip install ecgbench[croissant]).

ecgbench upload

Uploads each dataset's original/ and clean/ CSV folds, plus validation_report.json and croissant.json if present, to a HuggingFace Hub dataset repository. One or more dataset slugs can be uploaded in a single call.

ecgbench upload --data-dir output/ --datasets ptbxl
ecgbench upload --data-dir output/ --datasets ptbxl chapman_shaoxing
ecgbench upload --data-dir output/ --datasets ptbxl --dry-run
ecgbench upload --data-dir output/ --datasets ptbxl \
    --hf-repo-id your-org/ECGBench

Authentication resolves in this order: token= argument (Python API only) -> HF_TOKEN env var -> HUGGINGFACE_HUB_TOKEN env var -> .env file in the current working directory. Run with --dry-run first to review the file list.

Python equivalent:

import ecgbench

counts: dict[str, int] = ecgbench.run_upload(
    data_dir="output/",
    datasets=["ptbxl", "chapman_shaoxing"],
    hf_repo_id="vlbthambawita/ECGBench",
    dry_run=False,
    token=None,               # falls back to env / .env
)
# counts: {"ptbxl": 42, "chapman_shaoxing": 42}

Requires the hf extra (pip install ecgbench[hf]).

API Reference

Config

• load_config(slug) -- load DatasetConfig from YAML
• list_available_configs() -- list dataset slugs with configs

Catalogue

• list_datasets() -- all 64 datasets as CatalogueEntry objects
• search(query, category, access) -- filter datasets
• get_dataset(name) -- look up by name
• categories() -- unique categories
• to_dataframe() -- as pandas DataFrame

Dataset

• ECGDataset(dataset, split, ...) -- unified PyTorch Dataset
• ecg_collate_fn(batch) -- custom collate for DataLoader
• WindowOutOfRangeError -- raised when a window= does not fit a record

Validation

• validate_dataset(data_path, config) -- run quality checks
• generate_report(result, config) -- generate report dict
• save_report(result, config, path) -- save report JSON

Splitting

• split_dataset(df, labels, config) -- generate folds
• export_splits(split_result, val_result, output_dir, config) -- write CSVs
• get_splitter(slug) -- get dataset-specific splitter

Croissant

• generate_croissant(config, splits_dir) -- generate JSON-LD
• save_croissant(config, splits_dir) -- save to file
• validate_croissant(path) -- validate JSON-LD

Download

• download_dataset(config) -- download from source
• resolve_data_path(path, config) -- resolve or download

Pipelines (CLI + Python API)

• run_splits(dataset, ...) -- full validate + split + Croissant pipeline (same as ecgbench splits)
• run_croissant(dataset, splits_dir, ...) -- standalone Croissant generation (same as ecgbench croissant)
• run_upload(data_dir, datasets, ...) -- HuggingFace Hub upload (same as ecgbench upload)

Development

uv pip install -e ".[dev]"
ruff check ecgbench/
black ecgbench/
pytest

Citation

If you use ECGBench in your research, please cite:

@software{ecgbench,
  author = {Thambawita, Vajira},
  title = {ECGBench: Reproducible ECG Benchmark Datasets},
  url = {https://github.com/vlbthambawita/ECGBench}
}

License

MIT License -- see LICENSE for details.