Heart Disease Clinical Risk Prediction Platform

01 Executive Overview

The Heart Disease Prediction Platform is an end-to-end machine learning system developed using the UCI Cleveland Heart Disease dataset. Built to demonstrate rigorous machine-learning best practices, the system addresses the common pitfall of data leakage by encapsulating all data transformation steps inside scikit-learn Pipeline and ColumnTransformer objects.

The project pairs the serialized model with an interactive clinical frontend and a production-ready FastAPI backend, providing automated input validation, structured prediction responses, and persistent audit logging to an SQL database.

02 Problem & System Objectives

The Machine Learning Integrity Challenge

Many published machine-learning projects suffer from subtle data leakage bugs: fitting scalers or imputers on the entire dataset before splitting, or evaluating models without stratified sampling. When applied to tabular diagnostic benchmarks, these bugs lead to artificially inflated evaluation metrics that collapse in real-world inference.

Engineering Objectives

1. Leakage-Free Feature Processing: Encapsulate all imputation and feature scaling within an atomic scikit-learn Pipeline so test splits remain strictly unseen until final evaluation.
2. Adherence to Interpretable Models: Constrain model families to permitted, interpretable architectures (Logistic Regression, Decision Trees, Random Forests, and Soft Voting Ensembles) rather than uncalibrated black-box models.
3. Automated Persistence & Audit Logging: Record all inference queries, input feature vectors, predicted probabilities, and timestamps into an SQL audit table for traceability.
4. Production-Grade CI/CD & Containerization: Enforce automated testing in GitHub Actions and containerize the service using Docker.

03 Solution Architecture

The platform architecture enforces clean separation between data ingestion, offline model training/serialization, online inference serving, and database persistence:

[UCI Cleveland Raw Dataset: 13 Features]
                   │
                   ▼
  [Stratified 80/20 Train/Test Split]
        ├── Training Split (80%) ───────► [Pipeline Training]
        └── Untouched Test Split (20%) ──► [Final Generalization Holdout]
                   │
                   ▼
  [Scikit-Learn Pipeline & ColumnTransformer]
  ├── Numeric Pipeline: SimpleImputer(median) ──► StandardScaler()
  └── Categorical Pipeline: SimpleImputer(most_frequent) ──► OneHotEncoder()
                   │
                   ▼
  [Model Training & Stratified 5-Fold Cross-Validation]
  (Logistic Regression, Decision Tree, Random Forest, Soft Voting)
                   │
                   ▼
 [Serialized Artifact: models/heart_model.pkl]
                   │
                   ▼
 [FastAPI REST Service & Clinical Dashboard]
  ├── GET  /         (Interactive Clinical UI)
  ├── GET  /health   (Microservice Health Check)
  ├── POST /predict  (Pydantic Validated Prediction)
  └── GET  /history  (Recent Patient Predictions)
                   │
                   ▼
[SQL Audit Database: SQLite / PostgreSQL]
            

Feature Set Specification

The model processes 13 clinical features:

• Demographics & Vitals: Age, Sex, Resting Blood Pressure (trestbps), Serum Cholesterol (chol), Fasting Blood Sugar (fbs).
• Cardiological Exam Metrics: Chest Pain Type (cp), Resting ECG (restecg), Max Heart Rate (thalach), Exercise Induced Angina (exang), ST Depression (oldpeak), Slope of ST Segment (slope), Number of Major Vessels (ca), Thalassemia Type (thal).
• Target Variable: Binary clinical condition (0 = No heart disease, 1 = Heart disease present).

04 Implementation Details

Implemented Engineering Highlights

• Atomic Pipeline Encapsulation: By binding ColumnTransformer and the classifier into a single composite object, serialization and deserialization guarantee identical transformation logic during both training and real-time inference.
• Pydantic Data Contracts: The POST /predict endpoint uses a strict Pydantic model enforcing clinical boundary validation (e.g. valid age ranges, permitted categorical integers). Malformed payloads return explicit HTTP 422 errors before reaching the model.
• Audit Logging: Every inference query automatically writes patient feature values, predicted probabilities, and timestamp records into SQLite (locally) or PostgreSQL (in cloud deployment).

05 Evaluation & Verification Evidence

Evaluation was conducted using Stratified 5-Fold Cross-Validation on the training split, followed by evaluation on the untouched 20% holdout test set:

• Validation Generalization: The Soft Voting Ensemble achieved balanced accuracy and strong ROC-AUC on the holdout split (~85% on validation folds).
• Automated Test Suite: Comprehensive unit tests (tests/test_model.py, tests/test_api.py) execute under pytest, verifying prediction payload formats, schema edge cases, and health check status codes.
• Live Deployment: Containerized and actively hosted on Render PaaS at https://heart-disease-prediction-8vuc.onrender.com/.

06 Challenges & Engineering Trade-offs

07 Future Roadmap

1. SHAP Feature Attribution: Integrate TreeSHAP into the web UI to present individualized waterfall plots explaining feature contributions for each prediction.
2. Brier Score & Probability Calibration: Apply isotonic regression or Platt scaling to ensure calculated probabilities match empirical diagnostic rates.
3. Multi-Center Dataset Integration: Expand evaluation across external datasets (e.g. Hungarian and Long Beach cohorts) to assess cross-hospital generalization.