Distribution policy

Not every dataset's fold CSVs are published to the public HuggingFace repository. Where they are not, ECGBench distributes the split as a recipe instead, and ecgbench/manifest.py is what makes that reproducible partition trustworthy.

The rule is enforced in both directions rather than left to whoever runs the command: cli/upload.py raises PermissionError before any network call, and ECGDataset._load_from_hf raises SplitsNotPublishedError — quoting the config's no_publish_reason, which must therefore contain the regeneration command — instead of letting the user hit a bare 404.

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 — or material a licence forbids redistributing — and the ECGBench Hub repository is public and ungated, so ECGBench does not publish them. Four datasets are in this category: mimic_iv_ecg, whose 800,035 study_ids and 161,352 subject_ids stay with the people who signed the PhysioNet DUA; echonext, under the PhysioNet Restricted Health Data License whose clause 3 forbids sharing access to the data at all; ikem, which ships a LICENSE file that is verbatim CC BY-NC-ND 4.0 — the NoDerivatives term makes republishing a derived fold table legally unclear, so it is the first dataset here withheld by licence rather than by an access agreement; and ecg_capable_smartwatches, which is under the same Restricted licence as echonext and is withheld even though no human was ever recorded — every waveform is a patient simulator's and the identifiers are its settings. The licence travelling with the data governs whatever the data turns out to contain, which is the same rule applied to ikem.

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.

Adding another restricted dataset

See Phase 7 of the dataset checklist, which tabulates what may and may not be published for a credentialed or restricted source.