README.md

---
title: "AIO2025M03 Heart Disease Diagnosis"
emoji: "🫀"
colorFrom: "blue"
colorTo: "red"
sdk: "gradio"
sdk_version: "5.38.2"
app_file: "app.py"
pinned: false
---

# 🫀 Cleveland Heart Disease Diagnosis (Ensemble Demo)

An interactive demo that predicts heart disease risk from patient features using an ensemble of ML models trained on the Cleveland dataset.

## ✨ Features

- **🧩 Ensemble models**: Decision Tree, k-NN, and Naive Bayes with soft voting
- **📋 Validation metrics**: ROC-AUC, Accuracy, Precision, Recall, F1 (80/20 stratified split)
- **🧪 Patient inputs**: 13 clinical features with sensible defaults and example selector
- **📈 Results visualization**: Color/emoji-coded prediction confidence bar chart per model
- **ℹ️ Clear context**: Styled About card and fixed disclaimer (educational use only)
- **🎨 Theming**: VLAI template with configurable colors, fonts (Inter), header/footer

## 🚀 Quick Start

### Local Installation
```bash
git clone <repository-url>
cd AIO2025M03_HEART_DISEASE_PREDICTION
pip install -r requirements.txt
python app.py
```

### Usage
1. Ensure `data/cleveland.csv` exists (included in this repo)
2. Launch the app: `python app.py`
3. Review the About card and disclaimer at the top
4. Inspect data preview and validation metrics (trained at startup, 80/20)
5. Enter patient features or pick an example, then click Predict
6. Read individual model results and the predictions overview chart

## 🧠 Technical Highlights

- **Preprocessing**: Numeric median imputation; categorical most-frequent + one-hot
- **Pipelines**: Shared preprocessor wrapped with each estimator; ensemble via `VotingClassifier`
- **Evaluation**: Stratified train/validation split, with ROC-AUC and common classification metrics
- **Visualization**: Plotly bar chart; Gradio Blocks UI using VLAI template

## 📋 Requirements

- Python 3.8+
- Gradio 5.38+
- Scikit-learn
- Pandas
- NumPy
- Plotly

## 🎨 Theming & Branding

The UI is powered by `vlai_template.py` and can be customized programmatically:

```python
import vlai_template as vt

vt.configure(
    project_name="Heart Disease Diagnosis Project",
    year="2025",
    module="03",
    description=(
        "Predict heart disease risk from patient data with ML models "
        "trained on the Cleveland dataset."
    ),
    colors={
        "primary": "#0F6CBD",
        "accent": "#C4314B",
        "bg1": "#F0F7FF",
        "bg2": "#E8F0FA",
        "bg3": "#DDE7F8",
    },
    font_family=(
        "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, "
        "'Helvetica Neue', Arial, 'Noto Sans', 'Liberation Sans', sans-serif"
    ),
    meta_items=[
        ("Dataset", "Cleveland Heart Disease"),
        ("Models", "Decision Tree, k-NN, Naive Bayes"),
        ("Ensemble", "Soft Voting"),
    ],
)
```

You can also inject the info and disclaimer blocks:

```python
gr.HTML(vt.render_info_card(icon="🫀", title="About this demo"))
gr.HTML(vt.render_disclaimer(
    text=(
        "This interactive heart disease prediction demo is provided strictly "
        "for educational purposes and is not intended for clinical use."
    )
))
```

## 📄 License

Educational use for AIO2025 course materials. This demo is not medical advice.

---

**Live Demo**: coming soon