Cardiac Risk Map: 3D Coronary & SHAP Risk Engine

ML-powered CAD & LAD/LCX/RCA stenosis predictor with real-time per-vessel SHAP explainability & 60 FPS 3D WebGL AHA 17-segment beating heart mapping (Python Flask, Scikit-Learn, SHAP, Three.js)

Comment

Inspiration

Cardiovascular disease remains the leading cause of mortality globally. While conventional statistical calculators can output a raw risk percentage from patient lab values, a flat number like 78% risk fails to give clinicians or patients an intuitive spatial understanding of where pathology is developing inside the coronary anatomy or which physiological signals triggered a specific artery alert.

We built Cardiac Risk Map (GitHub Repository) to bridge the gap between 1D tabular clinical data and 3D human anatomy—combining four leak-free machine learning classification pipelines, real-time per-vessel SHAP (shap.TreeExplainer) interpretability, and a 60 FPS Three.js / WebGL beating human heart mapped to the American Heart Association (AHA) 17-segment myocardial perfusion territories.

Clinical Safety Disclaimer: This application is an educational and clinical decision-support prototype. Predictions are not a substitute for formal diagnostic imaging (coronary angiography, cardiac CT/MRI) or professional clinical evaluation.

What It Does

  • Multi-Vessel Stenosis & Overall CAD Prediction: Predicts both Overall Coronary Artery Disease (Cath) and vessel-specific stenosis probabilities (≥ 50% luminal narrowing) across the three major epicardial arteries:
    • LAD (Left Anterior Descending): Supplies the anterior wall and anterior interventricular septum.
    • LCX (Left Circumflex): Supplies the anterolateral and posterolateral left ventricular walls.
    • RCA (Right Coronary Artery): Supplies the right ventricle, inferior wall, and basal inferoseptal segments.
  • Real-Time 3D WebGL Beating Heart Mapping: Dynamically shades the 3D myocardium (beating-heart.glb) using GPU vertex color buffers based on predicted vessel probabilities (0% Normal → 25% Guarded → ≥ 55% High-Risk / 3D White Overdrive), complete with an interactive AHA 17-Segment Perfusion HUD, 3D Risk & Territory Scale legend, orbit/zoom camera controls, and clickable vessel inspection.
  • Per-Vessel Explainable AI (SHAP): Allows users to toggle the Feature Contributions (SHAP) panel across Overall CAD, LAD, LCX, and RCA to inspect exact risk-raising (red) and risk-lowering (blue/green) patient biomarkers in real time.
  • 1-Click Clinical Presets for Rapid Evaluation: Includes three pre-configured clinical profiles (High-Risk Anterior STEMI (LAD), Multi-Vessel CAD, and Healthy Baseline) for instant live testing.

How We Built It

1. Zero Target Leakage & Feature Engineering (src/config.py, src/data.py)

Trained on the Z-Alizadeh Sani Cardiology Dataset (N = 303 patients from Tehran Heart Center), our feature matrix X ingests 50+ non-invasive predictors spanning four clinical domains:

  1. Demographics & History: Age, Sex, BMI, DM (Diabetes), HTN (Hypertension), Current Smoker, FH (Family History), DLP (Dyslipidemia), CRF, CVA, CHF.
  2. Symptoms & Vitals: Typical Chest Pain, Atypical, Nonanginal, Exertional CP, Dyspnea, BP (Blood Pressure), PR (Pulse Rate), Edema, Lung Rales.
  3. 12-Lead Resting ECG: Rhythm, Q Wave, ST Elevation, ST Depression, Tinversion (T-Wave Inversion), LVH, Poor R Progression.
  4. Echocardiography & Laboratory Markers: EF-TTE (Ejection Fraction), Region with RWMA (Regional Wall Motion Abnormality), VHD, FBS, Cr, TG, LDL, HDL, HB, K, Na, WBC, PLT.

Because Cath, LAD, LCX, and RCA all originate from invasive coronary angiography, all four target columns are unconditionally excluded from X across every model pipeline to guarantee zero target leakage. Furthermore, Region with RWMA is used strictly as a clinical feature by the classifier rather than a direct 3D coordinate.

2. Multi-Target ML Pipeline & 5-Fold Stratified Cross-Validation (src/train.py)

For each target (Cath, LAD, LCX, RCA), we constructed an independent scikit-learn Pipeline combining inside-fold StandardScaler() normalization with a balanced ensemble classifier:

Pipeline([
    ("scaler", StandardScaler()),
    ("clf", RandomForestClassifier(
        n_estimators=300,
        max_depth=6,
        min_samples_leaf=2,
        class_weight="balanced",
        random_state=42
    ))
])

Evaluated via 5-Fold Stratified Cross-Validation (StratifiedKFold(n_splits=5, shuffle=True, random_state=42)), our deployed pipelines achieve:

Target Vessel / Disease Accuracy Majority Baseline ROC-AUC Sensitivity (Recall) Precision F1-Score Clinical Confidence Tier
Overall CAD (Cath) 86.5% 71.3% 0.930 90.3% 90.7% 90.5% Moderate (Single-Center Cohort)
LAD Artery (Anterior) 77.2% 58.4% 0.845 80.8% 80.6% 80.6% Moderate (Strong Anterior ECG Signal)
LCX Artery (Lateral) 63.7% 60.7% 0.727 58.8% 54.7% 56.5% Low / Guarded (Posterior Subtlety)
RCA Artery (Inferior) 65.7% 62.4% 0.711 57.9% 55.3% 56.2% Low / Guarded (Inferior Overlap)

3. Algorithmic Benchmarking & Probability Calibration (src/benchmark.py)

In docs/BENCHMARK_REPORT.md, we benchmarked our Balanced Random Forest against XGBoost, Gradient Boosting, and post-hoc probability calibration (CalibratedClassifierCV with Isotonic and Sigmoid scaling) evaluated via the Brier score (Brier = (1/N) Σ (pᵢ - yᵢ)²):

Target Vessel Random Forest ROC-AUC XGBoost ROC-AUC Gradient Boosting ROC-AUC Uncalibrated Brier Isotonic Calibrated Brier
Overall CAD (Cath) 0.930 ± 0.04 0.918 ± 0.05 0.912 ± 0.05 0.1030 0.0932
LAD Stenosis 0.845 ± 0.06 0.832 ± 0.07 0.825 ± 0.07 0.1684 0.1591
LCX Stenosis 0.728 ± 0.10 0.710 ± 0.11 0.696 ± 0.11 0.2215 0.2140
RCA Stenosis 0.704 ± 0.07 0.697 ± 0.08 0.678 ± 0.09 0.2268 0.2195

4. Sub-50ms Cached SHAP Engine & 60 FPS Three.js WebGL Pipeline (src/predict.py, static/heart3d.js)

To explain individual predictions, we compute exact additive feature attributions (f(x) = φ₀ + Σ φⱼ(x)) using shap.TreeExplainer, where φ₀ is the baseline model expectation and φⱼ(x) is the exact contribution of clinical feature j toward the predicted stenosis probability. By pre-instantiating all four TreeExplainer objects in memory at server boot (src/predict.py), our Flask /predict endpoint returns all four probabilities and four full SHAP vectors in under 50 ms. On the client (static/heart3d.js), Three.js maps those probabilities onto the 3D heart's GPU attributes.color vertex buffers at 60 FPS without requiring a dedicated GPU.

Challenges We Ran Into

  1. Anterior (LAD) vs. Posterolateral (LCX) & Inferior (RCA) Signal Asymmetry: Standard 12-lead resting ECG places precordial leads (V1–V6) directly over the anterior wall supplied by the LAD (0.845 ROC-AUC), whereas the posterolateral wall supplied by the LCX (0.727 ROC-AUC) lacks direct posterior leads (V7–V9) in routine exams. Rather than masking this clinical limitation, we added explicit Low / Guarded Confidence indicators on LCX and RCA cards and documented the single-center (N = 303) scope transparently.
  2. Real-Time SHAP Latency: Constructing TreeExplainer per HTTP request caused a >400 ms delay during interactive slider/preset updates. Moving explainer initialization to worker startup reduced inference + attribution latency to <50 ms.
  3. Smooth 3D Perfusion Shading Without Heavy Shaders: Instead of expensive multi-pass fragment shaders that lag on integrated laptop GPUs, we implemented spatial vertex weight interpolation directly on the Three.js mesh geometry buffers.

Accomplishments That We're Proud Of

  • Zero Data Leakage & Rigorous Validation: Achieved 0.930 ROC-AUC (90.5% F1) on Overall CAD and 0.845 ROC-AUC (80.6% F1) on LAD stenosis under strict 5-Fold Stratified Cross-Validation with zero angiography feature leakage.
  • True Per-Artery Explainability: Clinicians can click any individual vessel (LAD, LCX, RCA) to see both its 3D AHA 17-segment myocardial territory illumination and its dedicated SHAP biomarker breakdown.
  • Production Cloud Deployment: Deployed end-to-end on Render (cardiac-risk-prediction-k2jh.onrender.com) with 1-click judge demo presets and comprehensive technical documentation.

What We Learned & Team Contributions

  • Shivam Chauhan (Team Lead — System Architecture, Backend API, ML/SHAP Engine & 3D WebGL Pipeline): Architected the Flask REST inference backend (app.py, src/predict.py), boot-time shap.TreeExplainer caching, leak-free 5-fold Stratified CV training and benchmarking suite (src/config.py, src/train.py, src/benchmark.py), and the 60 FPS Three.js GPU vertex shading engine (static/heart3d.js, static/app.js).
  • Haseen Babu (Clinical Data Mapping, Preset Curation & UI QA): Mapped physiological reference bounds and unit labels across the 50+ input controls (templates/index.html), configured the 1-click clinical test case presets, and conducted cross-viewport QA testing.

What's Next for Cardiac Risk Map

  • External Multi-Center Validation: Expanding training beyond the single-center Tehran Heart Center cohort (N = 303) to multi-institutional registries to elevate clinical confidence from Moderate to High.
  • Sub-Branch Coronary Resolution: Extending the AHA 17-segment vertex map to include Diagonal (D1/D2), Obtuse Marginal (OM), and Posterior Descending (PDA) sub-branches.

Built With

Share this project:

Updates

Submission history