---
license: cc-by-nc-4.0
tags: [electrocardiogram, ecg, cardiovascular-risk, foundation-model, self-supervised, deepecg-ssl]
library_name: pytorch
pipeline_tag: tabular-classification
---

# DeepECG-SSL-CLSA-CVD

Fine-tuned **DeepECG-SSL** (self-supervised 12-lead ECG transformer; Nolin-Lapalme et al., *Eur Heart J* 2026, doi:10.1093/eurheartj/ehaf1119) to predict **incident cardiovascular disease** over a median 5.8 years in the Canadian Longitudinal Study on Aging (CLSA). The model accompanies the manuscript *"A Lab-Free ECG Foundation Model Versus Guideline Risk Scores for Incident Cardiovascular Disease: Development in CLSA and External Validation at the Montreal Heart Institute"*.

## What is in this repository
- `weights/deepecg_ssl_clsa_cvd_fold{0-4}.safetensors`: the five cross-validation fold models (full fine-tuning; ECG only).
- `model_params.json`:
  - per-fold Platt calibration parameters;
  - the **Model A+** logistic equation (DeepECG-SSL score + age + sex + hypertension; no blood test).
- `inference.py`: a loader and prediction functions. It needs `fairseq-signals` and the matching DeepECG-SSL v2 (amplitude-preserved) encoder checkpoint for the architecture.

## Input
- 12-lead resting ECG, 10 s, resampled to 250 Hz: an array of shape (12, 2500).
- Units are millivolts, with no per-lead normalisation.
- Standard lead order: I, II, III, aVR, aVL, aVF, V1–V6.

## Performance (from the manuscript)

**CLSA held-out test set** (n = 3,906; 394 events). The guideline scores need a blood test; Model A+ does not.

| Model | AUROC |
|---|---|
| **Model A+** | **0.733** (95% CI 0.707–0.759) |
| PREVENT | 0.715 |
| PCE | 0.709 |
| SCORE2/OP | 0.708 |
| FRS | 0.689 |

- **Where the gain comes from:** it is driven by the non-specific self-reported "heart disease" outcome item.
- **Endpoints the gain does not cover:** for hard atherosclerotic endpoints, PREVENT and SCORE2 are as good or better.

**External validation at the Montreal Heart Institute** (n = 21,647; 6-year hard MACE; DeepECG-SSL + age + sex with CLSA coefficients):

| Model | AUROC |
|---|---|
| DeepECG-SSL + age + sex | 0.761 |
| Age + sex | 0.728 |

- **By component:** the gain is in heart failure and stroke, not in myocardial infarction.
- **Calibration:** absolute risks need local recalibration before use.

## Intended use and limitations
- **Research use only.** This is not a medical device and has not been prospectively validated.
- **Training data:** CLSA, a mostly White community cohort aged 45–85, with GE CardioSoft ECGs.
- **Other populations and devices:** performance may differ.
- **No CLSA participant data** are included in this repository.

## Citation
Please cite the manuscript (citation to be added on publication) and DeepECG-SSL (Nolin-Lapalme A, et al. *Eur Heart J* 2026;47:2174–2186).

## Strict inference package

The `clsa_cvd` package adds strict five-fold checkpoint loading, explicit raw-source
mV conversion, full-precision logistic coefficients and the external age/sex variant.
It uses the same five fold weights already staged in this repository. The existing
root `inference.py` API remains present for compatibility; use this package for the
external variant and strict input/checkpoint validation.

```python
from clsa_cvd.model import CLSACVDModel

model = CLSACVDModel(
    weights_dir="weights",
    base_checkpoint="/approved/models/deepecg-ssl-v2-wcr-amp-preserved-encoder.pt",
    params_path="clsa_cvd/model_params.json",
    device="cuda:0",
    precision="float32",
)
# ecg_mv: finite float32 (N, 12, 2500), 10 seconds at 250 Hz in mV.
# age/female/hypertension: one numeric value per ECG; female/HTN are binary.
pred = model.predict(ecg_mv, age, female, hypertension, batch_size=32)
# p_ecg, risk_Aplus, ecg_logit_uncal, risk_ecg_age_sex
```

Lead order: I, II, III, aVR, aVL, aVF, V1–V6. For raw NPY inputs use
`clsa_cvd.preprocessing.prepare_waveform` or `load_waveform` with an explicit
format: `clsa` = 500-Hz CardioSoft ADC ×0.005 then polyphase resampling;
`muse` = 250-Hz MUSE ADC ×0.00488; `mv250` = already in mV at 250 Hz.
No spectral-power normalization or per-lead z-scoring is applied.

`risk_ecg_age_sex` uses the logit of the mean uncalibrated fold probabilities.
It is the transported MHI variant, not A+ with hypertension set to zero, and its
absolute risks require local recalibration. A+ uses the mean of Platt-calibrated
fold probabilities with age, female and physician-diagnosed hypertension.

The new package defaults to IEEE float32 with TF32 disabled. Historical test
predictions used CUDA bfloat16, batch 128. Select `precision="bfloat16"` and
batch size 128 to reproduce that arithmetic. On all 3,906 CLSA test participants,
historical-mode predictions matched the archive within 9e-8. Float32 is stable
under the tested single/batch ordering but differs from the historical ECG
probabilities by up to 0.001780 and A+ by 0.000998. Full-precision equation
coefficients reproduce archived A+ outputs within 2.3e-16 when supplied stored
ECG probabilities. Do not assume bit-identical results across precision modes.

Validated Python environment: PyTorch NVIDIA 26.08, CUDA 13.4, Python 3.12;
fairseq-signals `Jwoo5/fairseq-signals` commit
`f8f0ff1c788a82c2059cb452cd5462898867489e`. `requirements-clsa.txt` records
the observed direct dependency versions. The matching encoder checkpoint is still
required to define the architecture; its SHA-256 and fold artifact hashes are in
`clsa_cvd/artifacts.json`. Container build/run has not yet been verified.

`synthetic_validation.json` describes non-participant sinusoidal fixtures and
expected outputs. No participant-level data are included in this update.


## Pretraining overlap and subgroup reporting

No patient crosswalk between the encoder pretraining sources and the MHI validation
cohort is available. Patient-level pretraining/validation overlap has therefore not
been independently verified. This repository does not claim a reproduced
zero-overlap audit.

Exploratory racial/cultural subgroup reporting is limited by small event counts
and disclosure restrictions; suppressed results do not establish fairness in those
groups. Disclosure and fairness review were confirmed complete by the project
owner on 23 October 2026.

## Environment setup

The reference environment uses the NVIDIA PyTorch 26.08 container. In that
environment, install the direct dependencies and use the pinned fairseq source:

```bash
python -m pip install -r requirements-clsa.txt
git clone https://github.com/Jwoo5/fairseq-signals.git
git -C fairseq-signals checkout f8f0ff1c788a82c2059cb452cd5462898867489e
export PYTHONPATH="$PWD/fairseq-signals${PYTHONPATH:+:$PYTHONPATH}"
```

Download this repository (including `weights/`) using the Hugging Face client.
Supply the matching encoder checkpoint separately; its public download location
has not been verified. Verify its SHA-256 against `clsa_cvd/artifacts.json`.
The fine-tuned fold weights are included here; the separate base encoder is not.