ml_src/README.md

# ML Pipeline

Cardiac risk prediction using an ensemble of ECGFounder (deep learning) and XGBoost (gradient boosting).

## Model Architecture

```
Raw ECG (1000 samples @ 100Hz)
        │
        ├──> ECGFounder (1D CNN)──> 128-dim embedding
        │                                │
        ├──> Feature Engineering ────────>├──> 14 clinical features
        │    (NeuroKit2 + SciPy)         │
        │                                v
        │                          XGBoost Classifier
        │                                │
        └── Ensemble ────────────────────>│──> Risk Score (0.0-1.0)
             (weighted average)               Risk Label
```

### ECGFounder

- **Architecture**: 1D convolutional neural network (`net1d.py`)
- **Input**: 1000 ECG samples (10s window at 100Hz), bandpass filtered 0.5-40Hz
- **Output**: 128-dimensional feature embedding
- **Model file**: `ml_models/ecgfounder_best.pt` (117 MB)

### XGBoost Classifier

- **Input**: 14 features (ECG embedding + clinical features)
- **Output**: Binary risk probability
- **Model file**: `ml_models/xgboost_cardiac.joblib` (752 KB)

## Feature Engineering

The `feature_extractor.py` module computes clinical features from raw ECG:

| Feature | Source | Description |
|---------|--------|-------------|
| Heart Rate | Input | BPM from MAX30100 |
| SpO2 | Input | Blood oxygen percentage |
| HRV (SDNN) | NeuroKit2 | Heart rate variability |
| HRV (RMSSD) | NeuroKit2 | Root mean square of successive RR differences |
| QRS Duration | NeuroKit2 | Ventricular depolarization time |
| PR Interval | NeuroKit2 | Atrial-ventricular conduction |
| Signal Quality | SciPy | SNR estimate of ECG signal |
| Mean RR | Computed | Average R-R interval |
| RR Irregularity | Computed | Coefficient of variation of RR |
| Age | Profile | User age (if available) |
| Sex | Profile | Binary encoded |
| BMI | Profile | Computed from height/weight |
| Comorbidity Score | Profile | Count of risk factors |
| HR Deviation | History | Z-score vs 24h baseline |

## Inference Flow

1. Vitals uploaded to `POST /api/v1/vitals`
2. If ECG leads are connected and >= 100 samples:
   a. Load user health profile from database
   b. Compute 24h and 7d historical baselines
   c. Extract features from ECG waveform
   d. Run ECGFounder for deep features
   e. Combine and run XGBoost
   f. Store prediction in `predictions` collection
3. Return vitals + prediction in API response

## Risk Labels

| Score Range | Label | Description |
|-------------|-------|-------------|
| 0.00 - 0.20 | normal | No concerning patterns |
| 0.20 - 0.40 | low | Minor irregularities |
| 0.40 - 0.60 | moderate | Some risk indicators |
| 0.60 - 0.80 | elevated | Multiple risk factors |
| 0.80 - 1.00 | high | Significant cardiac risk |

## Files

```
ml_src/
├── __init__.py
├── net1d.py               # ECGFounder 1D CNN model definition
└── feature_extractor.py   # Clinical feature extraction

ml_models/
├── ecgfounder_best.pt     # Trained ECGFounder weights (Git LFS)
└── xgboost_cardiac.joblib # Trained XGBoost model (Git LFS)
```

## Dependencies

- `torch` (CPU-only, installed from pytorch.org/whl/cpu)
- `xgboost >= 2.0.0`
- `neurokit2 >= 0.2.7`
- `scipy >= 1.14.1`
- `numpy >= 1.26.4`
- `joblib >= 1.3.0`