Cardiology Multilabel Dataset and Classification Tasks

[jiama843]

Authors: John Ma (jm119@illinois.edu), Jia Lin Cheoh (jcheoh2@illinois.edu), Leo Yoon (byoon7@illinois.edu)
Dataset: PhysioNet/CinC Challenge 2020 (v1.0.2)
Protocol Paper: Nonaka and Seita (2021) - Towards Improving Multi-label ECG Classification

Overview

This PR contributes a new dataset and a multilabel classification task for the PhysioNet/Computing in Cardiology Challenge 2020 dataset. It includes support for 12-lead ECG signals and a specialized task parameter for lead ablation studies.

Dataset (cardiology2.py and cardiology.yaml)

1. Multi-Source Support: Handles six distinct sub-collections (CPSC, Georgia, PTB, etc.) via a chosen_dataset binary mask.
2. Metadata Indexing: Scans .hea header files to extract SNOMED-CT diagnosis codes, patient sex, and age, generating a flat metadata CSV for efficient loading.
3. Caching: Implements BaseDataset with integrated caching to speed up subsequent loads.

Tasks (cardiology_multilabel_classification.py)

CardiologyMultilabelClassification.

• Implements a sliding window approach with configurable epoch_sec (window length) and shift (stride).
• Spatial Ablation Support: Includes a leads parameter allowing users to select specific ECG leads (e.g., Lead I only) to simulate wearable device constraints vs. clinical 12-lead setups.
• Maps raw SNOMED-CT codes to the 27 scored classes defined in the 2020 challenge.

Examples & Ablation Studies

1. cardiology_multilabel.ipynb: A complete walkthrough from data installation to a sanity check on a SparcNet model.
2. cardiology_multilabel_resnet_lead_ablation.py: A specialized script comparing clinical (12-lead) vs. wearable (1-lead) configurations using a native PyHealth ResNet.

Unit Tests (test_cardiology_multilabel.py)

1. Synthetic Data Generation: Uses synthetic ECG tensors to ensure tests remain fast and environment-independent.
2. Initialization Checks: Verifies the model (SparcNet) correctly identifies the multilabel mode and output dimensions based on the dataset schema.
3. Forward/Backward Pass: Validates tensor shapes for logits and probabilities, and ensures gradients are successfully backpropagated.
4. Embedding Check: Verifies that the model correctly returns 2D latent representations when requested.

Review Note (Dataset Access)

The PhysioNet 2020 dataset is open access and does not require a signed Data Use Agreement (DUA) for the primary challenge files. The implementation expects the data to be downloaded locally via wget or gsutil as outlined in the provided notebook.

[jhnwu3]

Just some small bits of feedback:

It seems this dataset has a defunct dataset variant here: https://github.com/sunlabuiuc/PyHealth/blob/master/pyhealth/datasets/cardiology.py . It would be good to just replace it instead of creating a duplicate but functional class here.

Looks like the CI fails from some other bug here. Will need to look into that myself.

[jiama843]

@jhnwu3 That sounds good, the only concern I have is there are some other examples which use the old dataset (I believe a section in examples/datasets_overview.ipynb, examples/cardiology_detection_isAR_SparcNet.py and some related rst files).

We just wanted to avoid cascading those two changes in one PR. If needed (not sure if its orthodox) - I can try putting up a separate PR to deprecate/replace the old cardiology.py dataset and tidy up related files.