Cardisoft

Cardisoft — Explainable AI for Coronary Artery Disease Risk Estimation with Interactive 3D Heart Visualization.

Comment

Cardisoft

Inspiration

Coronary artery disease (CAD) is commonly confirmed by invasive coronary angiography, which carries cost and procedural risk. We asked whether machine learning, clinical data, explainable AI, and interactive 3D visualization could be brought into one transparent research workflow.

Cardisoft combines four independently trained classifiers, patient-level feature explanations, and an interactive heart dashboard. It lets users review what information the models receive and inspect the resulting estimates. It is a research and educational prototype, not a diagnostic or treatment tool.

What it does

Cardisoft accepts 54 structured clinical inputs and independently estimates four outcomes:

  • Overall coronary artery disease (CAD)
  • Left anterior descending artery (LAD) stenosis
  • Left circumflex artery (LCX) stenosis
  • Right coronary artery (RCA) stenosis

The dashboard displays probabilities, input coverage, vessel-specific results, and explanations. Its interactive 3D heart shows selectable, illustrative LAD, LCX, and RCA reference routes. Each route has a probability-driven color and numerical label; selecting it opens a vessel inspector. These routes do not identify patient-specific lesions or anatomy.

Users can enter measurements directly or review values imported through text, speech, selectable-text PDF extraction (pdf.js), and browser-based printed-text OCR (Tesseract.js). Raw audio and medical images are not model inputs. Imported values require review before analysis. The interface also supports comparison between assessments and PDF export.

How we built it

Dataset and preprocessing

We used the 303-record Z-Alizadeh Sani CAD dataset. Its 59 columns comprise 54 permitted predictors, four targets, and one constant field excluded from modeling. Target distributions are:

Target Positive Negative
CAD 216 87
LAD 177 126
LCX 119 184
RCA 114 189

Numerical fields use median imputation and RobustScaler; categorical fields use most-frequent imputation and model-appropriate one-hot or native categorical processing. Preprocessing is fitted within training folds to avoid leakage. New training runs additionally support clinical ratios, finding counts, and selected logarithmic transformations; the saved serving models use baseline inputs.

Machine-learning architecture

Four independent binary estimators predict CAD, LAD, LCX, and RCA. Training compares 32 configurations per target across Random Forest, XGBoost, HistGradientBoosting, LightGBM, CatBoost, stacking, and soft voting. Selection uses mean ROC–AUC over ten repeats of five-fold cross-validation, with mean F1 as tie-breaker. Class weighting addresses imbalance.

The saved serving bundle uses CatBoost for CAD (400 iterations, depth 4, learning rate 0.05, L2 = 3, balanced weights) and Random Forest for LAD, LCX, and RCA (400 trees, minimum leaf size 2; RCA maximum depth 8). Saved artifacts include preprocessors, estimators, feature schemas, metadata, and explanation reference data.

Frontend, backend, and visualization

The frontend uses React, TypeScript, Vite, Recharts, Three.js, and React Three Fiber. FastAPI serves validated predictions and separate on-demand explanations from frozen artifacts; it does not fit models during requests. The browser and API share the reviewed 54-field input contract. jsPDF supports assessment export.

The anatomical heart asset comes from BodyParts3D/Anatomography. Because its meshes lack verified LAD, LCX, and RCA segmentation, we registered separate reference routes using landmarks, interpolation, and surface projection. Geometric checks assess continuity, origins, direction, and surface contact—not clinical anatomical accuracy. Prediction responses update route appearance and labels without rebuilding heart geometry.

Explainability

The explanation endpoint computes approximate permutation Shapley contributions in probability space. It returns a reference baseline, signed contributions grouped by original clinical field, and a residual so displayed values reconcile with the prediction. These attributions describe model behavior, not causal medical effects.

Evaluation

The saved serving models were evaluated on target-specific stratified 80/20 partitions: 242 development and 61 held-out records per target, with a fixed decision threshold of 0.5.

Target Accuracy Precision Recall F1 ROC–AUC TN/FP/FN/TP
CAD 0.852 0.870 0.930 0.899 0.893 12/6/3/40
LAD 0.787 0.795 0.861 0.827 0.843 17/8/5/31
LCX 0.672 0.611 0.458 0.524 0.711 30/7/13/11
RCA 0.672 0.600 0.391 0.474 0.748 32/6/14/9

CAD and LAD show stronger discrimination on these internal test partitions. LCX and RCA sensitivity is substantially weaker: the models miss 13 of 24 and 14 of 23 positive held-out cases, respectively. A separate nested CAD validation experiment reported mean outer ROC–AUC of 0.9280, but it uses a different protocol and is not the deployed bundle's held-out result. Serving probabilities remain uncalibrated; a displayed score is not a clinically validated individual risk percentage.

Challenges we ran into

  • Avoiding leakage: Excluding target labels and the constant field, while fitting preprocessing only within training partitions.
  • Small, imbalanced data: Only 303 records, with fewer positive LCX and RCA examples, make vessel sensitivity difficult to estimate and improve.
  • Looking beyond accuracy: LCX and RCA both reach 67.2% accuracy but recall only 45.8% and 39.1%. Confusion matrices and multiple metrics are essential.
  • Interpretable explanations: Grouping encoded features back into clinical fields and presenting approximate attributions without implying causation.
  • Anatomical integrity: Creating coherent illustrative vessel routes from an asset without clinically verified coronary segmentation, while avoiding patient-specific lesion claims.
  • Consistent integration: Keeping form inputs, defaults, preprocessing, model artifacts, and API responses aligned.
  • Reviewable imports: OCR and extracted report measurements may be incomplete or inaccurate, so imported values require user review.

Accomplishments that we're proud of

  • Built an end-to-end workflow connecting structured clinical inputs, four estimators, explanations, and interactive 3D presentation.
  • Achieved 85.2% held-out CAD accuracy, 93.0% CAD recall, and 0.893 CAD ROC–AUC on the internal test partition.
  • Implemented systematic model comparison with 32 configurations per target and repeated stratified cross-validation.
  • Created independently selectable LAD, LCX, and RCA reference routes with geometric consistency checks.
  • Added patient-level, probability-space Shapley-based explanations and a separate explanation endpoint.
  • Integrated browser-based PDF text extraction and OCR with a review step.
  • Packaged frozen inference artifacts and metadata for reproducible API serving.
  • Reported weaknesses alongside strengths, including confusion counts, uncertainty, and a distinct nested-validation CAD experiment.

GitHub: https://github.com/shavipal567/Cardisoft
Live demo: https://cardisoft.vercel.app/

What we learned

An end-to-end ML system requires a stable data contract and consistent preprocessing, artifacts, inference, and presentation—not just a classifier. Small internal test partitions require cautious interpretation. In particular, reasonable overall accuracy can coexist with clinically important false negatives.

We also learned to keep distinct concepts separate: input coverage is not accuracy; cohort evaluation is not an individual's chance of a correct prediction; Shapley attribution is not medical causation; and an illustrative coronary route is not patient imaging. Making these boundaries explicit is part of responsible product design.

What's next for Cardisoft

  • Improve LCX and RCA sensitivity: Investigate decision thresholds, larger samples, feature configurations, and model alternatives while measuring false-positive trade-offs.
  • Validate externally: Seek independent multi-site cohorts and review provenance, labels, patient independence, and pre-decision feature availability.
  • Study calibration: Evaluate probability quality and thresholds on adequate data rather than treating 0.5 as clinically optimized.
  • Explore multi-task relationships: Assess whether explicitly modeling vessel co-occurrence helps compared with independent estimators.
  • Improve visualization: Consider clinically reviewed segmentations if stronger spatial claims are pursued; do not infer lesion position from tabular predictions.
  • Refine imports and explanations: Expand report mappings and unit handling, test explanation stability, and preserve mandatory review.
  • Strengthen deployment and governance: Improve artifact versioning, readiness checks, privacy practices, and access controls before handling real patient workflows.

Cardisoft remains a research and educational prototype. It has not undergone external clinical validation, its serving probabilities are uncalibrated, and its outputs must not be used to rule out disease or make care decisions.

Built With

Share this project:

Updates

Submission history