Cardio-Risk-Analyzer

KO | EN

gitlite — search

#ai #typescript #go #android #machine-learning #deep-learning #java #nodejs #windows #awesome #vue #awesome-list #pytorch #security

Cardio-Risk-Analyzer

(★ 3)

A ML based cardiovascular risk prediction system that uses an ensemble of XGBoost and CatBoost to provide real time heart disease risk estimates. With interactive health visualization and clean UI.

Cardio-Risk-Analyzer Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# CardioML – AI-Powered Heart Disease Risk Predictor

A full-stack application that estimates cardiovascular (heart disease) risk using an ensemble of machine learning models with rich visual explainability.

> **For research and educational use only.** Not a substitute for professional medical advice, diagnosis, or treatment.

---

## Live Demo

- **Web App (Frontend)**: [`https://cardioml-kbss.vercel.app`](https://cardioml-kbss.vercel.app)
- **ML API (Backend – Hugging Face Space)**: [`https://kbsss-cardioml-backend.hf.space`](https://kbsss-cardioml-backend.hf.space)  
  - Main prediction endpoint: `POST https://kbsss-cardioml-backend.hf.space/api/predict`

---

## Screenshots

![Dashboard](https://raw.githubusercontent.com/kbss0000/Cardio-Risk-Analyzer/main/screenshots/dashboard.png)
![Risk Assessment](https://raw.githubusercontent.com/kbss0000/Cardio-Risk-Analyzer/main/screenshots/assessment.png)
![Results](https://raw.githubusercontent.com/kbss0000/Cardio-Risk-Analyzer/main/screenshots/results.png)

_Replace these with real screenshots from your deployed app._

- **Home / Dashboard** – Hero section with ROC‑AUC stats, CTAs, and animated cards.  
- **Risk Assessment** – Patient input form with live BMI/BP calculations.  
- **Results View** – Risk gauge, model breakdown (XGBoost vs CatBoost), SHAP feature importance bars, and recommendations.

---

## About The Project

CardioML helps users understand their **cardiovascular risk** using clinically inspired features and modern machine learning:

- Users enter health metrics (age, blood pressure, cholesterol, lifestyle, ejection fraction, etc.).
- The backend computes **base + derived features** (BMI, MAP, age group, lifestyle score, risk age, risk level…).
- An **ensemble of XGBoost + CatBoost** models predicts the probability of cardiovascular events.
- The app returns:
  - **Risk percentage** and **risk level** (low / moderate / high)
  - **Per‑model probabilities** (XGBoost, CatBoost)
  - **SHAP-inspired feature contributions** (which factors increase or decrease risk)
  - **Human-readable risk summary** like “High BP, Obese, Elevated Cholesterol, Alcohol, Reduced EF”.

This is a **demo / educational** tool only – not a medical device.

---

## Tech Stack

| Layer        | Technology                                                                 |
|-------------|-----------------------------------------------------------------------------|
| **Frontend**| Next.js 14, React 18, TypeScript, Tailwind CSS, Lucide Icons               |
| **Backend** | FastAPI (Python 3.11+), Uvicorn                                            |
| **ML**      | XGBoost 2.x, CatBoost 1.2.x, scikit‑learn, Pandas, NumPy                   |
| **Explain** | Custom SHAP-style feature contributions for interpretability               |
| **Deploy**  | Vercel (frontend), Hugging Face Spaces (Docker + FastAPI backend)         |

---

## Project Structure

```bash
.
├── frontend/                 # Next.js 14 + TypeScript frontend (CardioML UI)
│   ├── src/
│   │   ├── app/             # App Router pages (/ , /predict , /results , /api/*)
│   │   ├── components/      # UI components & 3D / parallax effects
│   │   ├── lib/             # API client & utility functions
│   │   └── types/           # Shared TypeScript types (e.g. PatientData)
│   ├── public/              # Static assets (icons, images)
│   ├── package.json         # Frontend dependencies
│   └── next.config.js       # Next.js configuration
│
├── backend/                  # FastAPI Backend (Hugging Face Space)
│   ├── app.py               # FastAPI entrypoint
│   ├── backend/             # Core logic (models, features, prediction)
│   ├── models/              # Trained ML artifacts (joblib/json)
│   ├── Dockerfile           # Docker configuration for HF Space
│   └── requirements.txt     # Python dependencies
│
├── scripts/                  # Training & testing utilities
│   ├── train_model.py       # Model training & evaluation pipeline
│   ├── test_app.py          # End‑to‑end API tests
│   └── test_formulas.py     # Unit tests for derived feature formulas
│
├── screenshots/              # Project screenshots
├── oneLastTime.ipynb         # Jupyter notebook with experiments & evaluation
├── requirements.txt          # Root Python deps for training / notebooks
└── LICENSE.md                # MIT License
```

---

## Getting Started

### Prerequisites

- **Node.js** 18+  
- **Python** 3.10+ or 3.11  
- **Git**

### 1. Clone the Repository

```bash
git clone https://github.com/kbss0000/YOUR-REPO-NAME.git
cd YOUR-REPO-NAME
```

### 2. Run the Frontend (Next.js)

```bash
cd frontend
npm install

# Local dev API URL (optional; by default it uses NEXT_PUBLIC_API_URL if set)
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local

npm run dev
```

Frontend runs at: `http://localhost:3000`

### 3. Run the Backend Locally (FastAPI)

```bash
cd ../backend
python3 -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

uvicorn app:app --host 0.0.0.0 --port 8000 --reload
```

Backend runs at:

- `http://localhost:8000/health`
- `http://localhost:8000/api/predict`

---

## API (Hugging Face Backend)

Production predictions are served by the Hugging Face Space:

- **Base URL**: `https://kbsss-cardioml-backend.hf.space`
- **Main endpoint**: `POST /api/predict`

**Example request body:**

```json
{
  "gender": 1,
  "age_years": 55,
  "height": 170,
  "weight": 80,
  "ap_hi": 140,
  "ap_lo": 90,
  "cholesterol": 2,
  "gluc": 2,
  "smoke": 0,
  "alco": 1,
  "active": 0,
  "protein_level": 7.2,
  "ejection_fraction": 55.0
}
```

**Example response (simplified):**

```json
{
  "risk_percentage": 42.75,
  "prediction": 1,
  "risk_level": "moderate",
  "confidence": 83.4,
  "models": {
    "xgboost": 39.12,
    "catboost": 46.38
  },
  "derived_features": {
    "BMI": 27.7,
    "BMI_Category": "Overweight",
    "BP_diff": 60,
    "MAP": 103.3,
    "Risk_Age": 61.4,
    "Risk_Level": "Moderate"
  },
  "reason_string": "High BP, Overweight, Elevated Cholesterol, Alcohol, Reduced EF"
}
```

---

## Model & Features

**Base Features (13)**  
- Demographics: `gender`, `age_years`, `height`, `weight`  
- Blood pressure: `ap_hi`, `ap_lo`  
- Labs: `cholesterol` (1–3), `gluc` (1–3), `protein_level`  
- Lifestyle: `smoke`, `alco`, `active`  
- Cardiac function: `ejection_fraction`

**Derived Features (15+)**  
- `BMI`, `BMI_Category` (Underweight / Normal / Overweight / Obese)  
- `BP_diff`, `Systolic_Pressure`, `BP_Category` (Normal / Elevated / Stage 1 / Stage 2)  
- `MAP` (Mean Arterial Pressure), `Pulse_Pressure_Ratio`  
- `Age_Group` (`20–29`, `30–39`, `40–49`, `50–59`, `60+`)  
- `Lifestyle_Score` (0–3) from activity, smoking, alcohol  
- `Risk_Age` (age adjusted by BMI & labs)  
- `Health_Risk_Score`, `Risk_Level` (Low / Moderate / High)  
- `Obesity_Flag`, `Hypertension_Flag`, `Smoker_Alcoholic`

**Ensemble Strategy**  
- XGBoost + CatBoost with tuned weights (`w_xgb`, `w_cat`)  
- Final probability:

\[
  P(\text{risk}) = w_{xgb} \cdot P_{xgb} + w_{cat} \cdot P_{cat}
  \]

---

## Frontend Highlights

- **Modern UI** with glassmorphism, neon accents, 3D cards, and subtle particle effects.
- **Fully responsive** – desktop, tablet, and mobile (Tailwind `md:` breakpoints).
- **Live health metrics**:
  - BMI with status badges (Normal / Overweight / Obese)
  - Blood pressure breakdown (pulse pressure, MAP, category)
  - Lifestyle risk score widget
- **Rich result page**:
  - Animated circular risk gauge
  - XGBoost vs CatBoost vs Ensemble breakdown
  - SHAP-style feature importance bars (red = increases risk, blue = decreases risk)
  - Downloadable JSON/CSV report
- **Attribution**: Footer credits the author as [`@kbss0000`](https://github.com/kbss0000).

---

## Development & Scripts

### Frontend

```bash
cd frontend
npm install
npm run dev      # start dev server on http://localhost:3000
npm run build    # production build
npm run lint     # run ESLint
```

### Backend (local FastAPI)

```bash
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app:app --reload
```

### Training & Evaluation

```bash
cd scripts
python train_model.py      # trains XGBoost + CatBoost ensemble
python test_app.py         # integration tests for API
python test_formulas.py    # validate derived feature formulas
```

Notebooks for experimentation live in `oneLastTime.ipynb`.

---

## Deployment

### Frontend – Vercel

1. Connect this GitHub repo to Vercel.
2. Configure:
   - **Build Command**: `npm run build`
   - **Output Directory**: `.next`
3. Environment variable:
   - `NEXT_PUBLIC_API_URL` = `https://kbsss-cardioml-backend.hf.space`
4. Deploy – your app will be available at a `*.vercel.app` URL (e.g. `https://cardioml-kbss.vercel.app`).

### Backend – Hugging Face Space (Docker + FastAPI)

The `backend/` folder contains everything needed for the Space:

- `app.py` – FastAPI entrypoint
- `backend/` – model loading, feature engineering, prediction logic
- `models/` – serialized ML models and feature metadata
- `Dockerfile` – environment definition for the Space

High‑level deployment steps:

1. Create a Space `kbsss/cardioml-backend` with SDK = **Docker**.
2. Push the contents of `backend/` to that Space repo.
3. Hugging Face builds the image and exposes `https://kbsss-cardioml-backend.hf.space` (with `/api/predict`).

---

## Privacy & Data

- The public demo does **not** persist user data; everything is processed in memory.
- Do not enter real identifiable patient data in the public instance.
- For any real‑world usage, you must perform your own security, privacy, and regulatory review.

---

## License

This project is licensed under the **MIT License** – see [`LICENSE.md`](./LICENSE.md) for details.

---

Built with machine learning by **[@kbss0000](https://github.com/kbss0000)**.  
Always consult qualified healthcare professionals for actual medical decisions.

Cardio-Risk-Analyzer

Cardio-Risk-Analyzer Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Cardio-Risk-Analyzer

Cardio-Risk-Analyzer Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README