README.md

metadata

title: Heart Attack Risk Predictor
emoji: 🫀
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false

🫀 Heart Attack Risk Predictor — Multimodal

An AI-powered clinical decision-support tool that estimates a patient's heart-attack risk from tabular patient data, an ECG image, or both — using an ensemble-router architecture with a tabular model, an ECG image model, and late-fusion of their scores.

🔴 TRY THE LIVE DEMO ON HUGGING FACE SPACES 🔴

⚠️ Educational / portfolio demo — not a medical device. Do not use for real clinical decisions.

---

📑 Table of Contents

• What's New in v2
• Key Features
• How It Works — Architecture
• The Two Models
• Tech Stack
• Project Structure
• Getting Started
• Usage & API
• Model Performance
• Testing
• Limitations & Honesty
• Team Members

---

🆕 What's New in v2

Version 1 was a single-model biomarker classifier (8 vitals → Random Forest). A leakage test showed its ~98% accuracy was largely a biomarker-threshold rule (accuracy fell to ~62% without Troponin & CK-MB). Version 2 re-architects the project into a multimodal ensemble router:

• Two models instead of one — a tabular model and an ECG image model.
• A router that picks the model(s) based on what the user submits, and averages their scores when both are provided.
• Honest evaluation — proper metrics (ROC-AUC for the imbalanced tabular task, per-class metrics for the ECG task) and a clear statement of limitations.

The original v1 biomarker research is preserved in research_and_experiments/.

---

✨ Key Features

• Multimodal input — enter patient data, upload an ECG image, or do both.
• Ensemble router — one POST /predict endpoint routes to the right model(s): tabular → Model A, ECG → Model B, both → averaged score.
• Missing-data friendly — blank tabular fields are filled automatically by K-Nearest-Neighbours imputation, so a partial form still works.
• Server-side validation — out-of-range or non-numeric fields are rejected with a clear message (HTTP 422).
• ECG confidence check — low-confidence ECG predictions are flagged ("may not be a clear 12-lead ECG").
• Transparent results — the UI shows each model's score and, in "both" mode, the combined average, so nothing is a black box.
• Modern UI — dark glassmorphism theme, drag-and-drop ECG upload, color-coded risk badges (🔴 High / 🟡 Moderate / 🟢 Low).

---

🧠 How It Works — Architecture

                 ┌──────────────── POST /predict (multipart/form-data) ────────────────┐
   tabular only ─┤→ Model A (Framingham: KNN-impute → scale → RandomForest) → p_a ─┐    │
                 │                                                                  ├─ both → average → p → band (Low/Mod/High)
   ECG only ─────┤→ Model B (ResNet18 transfer learning on ECG images)      → p_b ─┘    │
                 │                                                                       │
   neither ──────┤→ HTTP 400                                                             │
                 └───────────────────────────────────────────────────────────────────────┘

Each model outputs a scalar risk probability p ∈ [0, 1]. That value is mapped to a band — Low (< 0.33), Moderate (0.33–0.66), High (> 0.66) — and, when both models run, the two scores are combined by an equal-weight average.

---

🤖 The Two Models

Model A — Tabular (Framingham 10-year CHD)

• Data: Framingham Heart Study (4,240 patients, 15 clinical features).
• Target: TenYearCHD — probability of coronary heart disease within 10 years.
• Pipeline: StandardScaler → KNNImputer(k=5) → classifier, saved as one artifact.
• Model selection: RandomForest vs XGBoost by 5-fold CV ROC-AUC — RandomForest won (0.69 vs 0.67).
• Handles imbalance (~15% positive) with class weighting; the app uses the continuous probability, not a hard 0.5 cutoff.

Model B — ECG image (ResNet18)

• Data: ECG Images Dataset of Cardiac Patients (928 images, 4 classes).
• Method: transfer learning — a ResNet18 pretrained on ImageNet, with a new 4-class head; train the head, then fine-tune the last block.
• Classes → risk weight: Normal 0.0, abnormal heartbeat 0.5, post-MI history 0.8, myocardial infarction 1.0. The 4-class softmax is collapsed to one risk score via these weights.

---

🛠️ Tech Stack

Layer	Technology	Purpose
Backend	FastAPI + Uvicorn	Async web framework + ASGI server; multipart /predict router
Tabular ML	scikit-learn (RandomForest, KNNImputer, StandardScaler), XGBoost	Model A pipeline + model comparison
Image ML	PyTorch + torchvision (ResNet18)	Model B transfer learning
Images / Uploads	Pillow, python-multipart	ECG image decoding + file uploads
Data	pandas, NumPy	Data handling
Frontend	HTML5, CSS3, Vanilla JS	Single-page glassmorphism UI with ECG drag-and-drop
Deployment	Docker → Hugging Face Spaces	Containerized serving on port 7860

---

📁 Project Structure

heart-attack-risk-predictor/
│
├── app.py                       # FastAPI app + ensemble router (multipart /predict)
├── requirements.txt             # Production dependencies
├── Dockerfile                   # Container build (copies app, inference/, models/, static/)
│
├── inference/                   # Serving-time prediction package
│   ├── fusion.py                # Risk bands + late-fusion (combine)
│   ├── framingham.py            # Model A inference (with KNN imputation)
│   ├── ecg.py                   # Model B inference (softmax → risk scalar)
│   └── validation.py            # Server-side field validation
│
├── models/                      # Trained artifacts (Git LFS)
│   ├── framingham_pipeline.joblib   # Model A bundle
│   ├── ecg_resnet.pt                # Model B weights
│   └── ecg_classes.json             # ECG class list + risk weights + preprocessing
│
├── train_framingham.py          # Trains Model A
├── train_ecg.py                 # Trains Model B
│
├── static/index.html            # Frontend (form + ECG upload + per-branch results)
│
├── DOCUMENTATION.md             # Full technical documentation
├── DEFENSE_GUIDE.md             # Beginner-friendly project defense guide
│
└── research_and_experiments/    # v1 biomarker research (notebook, dataset, old model)

---

🚀 Getting Started

Prerequisites

• Python 3.11+ (3.12 recommended)

Install

git clone https://github.com/Shahd1Sayed/heart-attack-risk-predictor.git
cd heart-attack-risk-predictor
pip install -r requirements.txt

Data (only needed to (re)train — download from Kaggle)

data/framingham.csv                  # "Framingham Heart Study dataset"
data/ecg_data/<class>/*.jpg          # "ECG Images Dataset of Cardiac Patients"

Train (produces the files in models/)

python train_framingham.py
python train_ecg.py

Run

uvicorn app:app --host 127.0.0.1 --port 8000
# open http://127.0.0.1:8000

The app boots even before models are trained; a branch needing an untrained model returns HTTP 503 with a hint.

---

▶️ Usage & API

POST /predict accepts multipart/form-data with optional tabular fields and an optional ecg image file.

# tabular only
curl -F age=61 -F male=1 -F sysBP=150 -F totChol=240 http://127.0.0.1:8000/predict

# ECG only
curl -F ecg=@some_ecg.jpg http://127.0.0.1:8000/predict

# both (multimodal)
curl -F age=61 -F sysBP=150 -F ecg=@some_ecg.jpg http://127.0.0.1:8000/predict

Tabular fields: male, age, education, currentSmoker, cigsPerDay, BPMeds, prevalentStroke, prevalentHyp, diabetes, totChol, sysBP, diaBP, BMI, heartRate, glucose (all optional; blanks are KNN-imputed).

Example response (multimodal):

{
  "mode": "multimodal",
  "risk_level": "High",
  "p_risk": 0.7306,
  "branches": {
    "tabular": { "p_risk": 0.4825, "band": "Moderate",
                 "detail": {"CHD": 0.4825, "No CHD": 0.5175}, "imputed_fields": ["glucose"] },
    "ecg": { "p_risk": 0.9787, "band": "High", "ecg_class": "myocardial_infarction_ecg_images",
             "confidence": 0.9587, "low_confidence": false, "warning": null }
  }
}

Status codes: 200 success · 400 no input / unreadable image · 422 invalid tabular field · 503 model not trained yet.

---

📊 Model Performance

Model	Metric	Value
Model A — Framingham	CV ROC-AUC	0.69
	Hold-out ROC-AUC	0.64
	Accuracy	0.85 (≈ all-negative baseline — see note)
Model B — ECG ResNet18	Test accuracy	0.90
	Macro F1	0.90
	MI precision	1.00

⚠️ Metric honesty: Framingham is imbalanced (~15% positive), so 85% accuracy is essentially the "always predict no-CHD" baseline — which is why we lead with ROC-AUC. Predicting a decade ahead from basic clinical features is genuinely hard, so ~0.64–0.69 AUC is expected. The ECG numbers are strong for a small dataset but optimistic vs. other acquisition setups (the images are photos of printed ECGs).

---

🧪 Testing

The project ships with a test harness (router paths, response invariants, adversarial inputs, determinism, an ECG serving sweep, input validation, ECG confidence, and concurrency). Result: 62/62 checks pass. See DOCUMENTATION.md for details.

---

⚖️ Limitations & Honesty

• The two models predict different things — Model A estimates 10-year prognosis; Model B classifies the current ECG. They are trained on different, unpaired populations, so the combined score is a transparent heuristic demonstrating the architecture, not a validated clinical measure.
• The fusion weights are hand-set (equal average) because no paired dataset exists to learn/validate them. A learned fusion on paired data (e.g. PTB-XL) is future work.
• ECG images are photos of printouts — a small, imbalanced dataset; the CNN may not generalize to other setups.
• No out-of-distribution rejection — a non-ECG image is still classified (now flagged low-confidence, but not refused).
• Not for clinical use.

---

👥 Team Members

Name	Role	GitHub
Shahd Sayed	Machine Learning Engineer	@Shahd1Sayed
Shahd Mohammed	Full-Stack Developer

---