CardioAI is a reproducible ECG classification workflow developed for PTB-XL in-domain evaluation and PTB Diagnostic inference-only external validation. The project integrates standardized preprocessing, beat tokenization, controlled comparison between a CNN-only baseline and a hybrid CNN–Transformer, evaluation, explainability analysis, and thesis artefact materials.
This repository contains the core research workflow used in the CardioAI study. It is intended for research transparency, reproducibility, and educational demonstration.
The CardioAI workflow was designed to support:
- standardized ECG preprocessing
- beat-level tokenization
- patient-wise train/validation/test evaluation on PTB-XL
- inference-only cross-dataset transfer to PTB Diagnostic
- explainability and model-auditing analysis
- organized export of selected figures, tables, and artefact materials
Within the implemented thesis scope, the workflow supports:
- binary normal-vs-abnormal classification on PTB-XL
- multilabel / five-superclass classification on PTB-XL
- external MI-vs-healthy inference-only evaluation on PTB Diagnostic
- explainability analysis using methods such as Integrated Gradients and GradientSHAP
CardioAI/
├── README.md
├── .gitignore
├── requirements.txt
├── notebooks/
│ └── CardioAI_workflow.ipynb
| └── Cross_Dataset_PTB_XL_PTB_Diagnostic.ipynb
├── docs/
│ ├── artefact_manifest.md
│ └── reproduction_guide.md
├── results/
│ ├── demo/
│ ├── figures/
│ └── tables/
└── appendix_assets/
-
notebooks/Google Colab notebooks used for preprocessing, tokenization, training, evaluation, and figure generation -
configs/Configuration files for experiment settings, paths, and reproducibility-related parameters. -
results/Selected output figures, tables, and sample artefacts used in the thesis and supporting analysis. -
docs/Artefact documentation, including the artefact manifest and reproduction notes. -
appendix_assets/Thesis-ready figures and supplementary artefact materials.
The Streamlit-based research demo is maintained in a separate repository.
That separate repository contains the user-facing prototype for:
- ECG viewing
- prediction display
- explanation visualization
This repository focuses on the core research pipeline, while the Streamlit repository is kept separate to preserve a clear distinction between:
- the experimental/reproducibility workflow, and
- the demonstration-oriented application
This repository does not redistribute PTB-XL or PTB Diagnostic ECG data.
Please obtain the datasets from their official sources and place them in your local or cloud data directory before running the notebooks.
- PTB-XL — primary development dataset for in-domain training and evaluation
- PTB Diagnostic ECG Database — independent cohort used for inference-only external validation
- Python 3.10+
- Google Colab or local Jupyter environment
- GPU recommended for model training and evaluation
The workflow was primarily developed and executed in Google Colab. A local Jupyter environment may also be used, provided that package versions, dataset paths, and runtime settings are configured consistently.
- Install dependencies from
requirements.txt - Download PTB-XL and PTB Diagnostic from the official sources
- Update dataset paths in the notebook or configuration files
- Run preprocessing and signal standardization
- Run beat extraction / tokenization
- Run training and evaluation
- Run explainability analysis
- Run inference-only external validation on PTB Diagnostic
- Export selected figures and tables
- Fixed random seeds should be used where specified in the notebook/configuration
- Preprocessing settings should remain consistent across PTB-XL and PTB Diagnostic
- Raw data should be kept separate from generated artefacts
- Large intermediate caches and temporary files are intentionally excluded from the repository
- preprocessing and tokenization workflow notebooks
- training and evaluation notebooks
- experiment configuration files
- selected figures and tables used in the thesis
- supporting artefact documentation
- thesis pipeline and appendix materials
- raw PTB-XL or PTB Diagnostic data
- large cached artefacts
- private credentials, tokens, or access keys
- full deployment assets for the separate Streamlit app repository
This repository is provided for:
- research reproducibility
- academic documentation
- educational demonstration
It is not intended for clinical deployment or medical decision-making.
If this repository is used in connection with the CardioAI thesis or related academic work, please cite or reference the associated thesis/report as appropriate.
CardioAI is a research and educational project. The models, analyses, and outputs in this repository are not validated for clinical use and must not be used as a substitute for professional medical interpretation.