NeuroGuard is an end-to-end Machine Learning application that predicts stroke risk using clinical patient information while providing interpretable explanations through SHAP.
The project demonstrates a production-oriented ML workflow rather than simply training a machine learning model.
It includes:
- Data validation
- Feature engineering
- Multiple model benchmarking
- Class imbalance experiments
- Cross validation
- Threshold optimization
- Explainable AI (SHAP)
- REST API using FastAPI
- Docker deployment
- MLflow experiment tracking
- Interactive prediction dashboard
Patient Data
│
▼
Data Validation
│
▼
Feature Engineering
│
▼
Data Preprocessing
│
▼
Model Training Pipeline
│
┌────────────────┴─────────────────┐
▼ ▼
Model Evaluation SHAP Explainability
│ │
└──────────────┬───────────────────┘
▼
Saved Artifacts
│
┌──────────────┴──────────────┐
▼ ▼
FastAPI API Consumer UI
│ │
└──────────────┬──────────────┘
▼
Real-time Predictions
- Logistic Regression
- Decision Tree
- Random Forest
- Extra Trees
- Gradient Boosting
- Dataset loading
- Missing value handling
- Train/Test split
- Standard Scaling
- One-Hot Encoding
- Feature persistence
- Artifact versioning
Automatically computes
- Accuracy
- Precision
- Recall
- F1 Score
- ROC AUC
- PR AUC
- Confusion Matrix
- Calibration Curve
- ROC Curve
- Precision Recall Curve
Supports
- Baseline
- Random Oversampling
- SMOTE
- Borderline SMOTE
- ADASYN
- SMOTEENN
- SMOTETomek
Searches multiple probability thresholds and selects the best threshold using
- F1 Score
- Precision
- Recall
- Specificity
- Balanced Accuracy
- Youden Index
Implemented using SHAP.
Generated automatically:
- Global Feature Importance
- SHAP Summary Plot
- Beeswarm Plot
- Waterfall Plot
- Dependence Plots
- Local Prediction Explanation
FastAPI endpoints
GET /
GET /health
POST /predict
Swagger documentation
http://localhost:8000/docs
Run the complete application anywhere using Docker.
docker compose up --build
Tracks
- Parameters
- Metrics
- Models
- Artifacts
- Experiments
Launch
mlflow ui
NeuroGuard/
apps/
│
├── api/
│
ml/
│
├── data/
├── features/
├── models/
├── evaluation/
├── explainability/
├── inference/
├── visualization/
├── mlflow/
└── monitoring/
artifacts/
datasets/
models/
preprocessors/
metadata/
figures/
experiments/
explainability/
configs/
docker/
README.md
requirements.txt
Dockerfile
docker-compose.yml
| Metric | Score |
|---|---|
| Accuracy | 74.56% |
| Precision | 13.79% |
| Recall | 80.00% |
| F1 Score | 23.53% |
| ROC AUC | 84.37% |
| PR AUC | 26.85% |
The dataset is highly imbalanced. Therefore ROC AUC, Recall, PR AUC and threshold tuning were prioritized over raw accuracy.
- Python
- Scikit-learn
- Pandas
- NumPy
- SciPy
- Imbalanced-Learn
- SHAP
- FastAPI
- Uvicorn
- Pydantic
- Docker
- Docker Compose
- MLflow
- Matplotlib
Clone repository
git clone https://github.com/Garvitjoshi1/NeuroGuard.git
cd NeuroGuard
Create environment
python -m venv .venv
Windows
.venv\Scripts\activate
Linux
source .venv/bin/activate
Install dependencies
pip install -r requirements.txt
python -m ml.features.pipeline
The pipeline performs
- preprocessing
- model training
- evaluation
- visualization
- explainability
- artifact generation
uvicorn apps.api.main:app --reload
Open
http://localhost:8000/docs
Build
docker compose build
Run
docker compose up
NeuroGuard is intended for educational and research purposes only.
Predictions generated by this application must not be used as a substitute for professional medical diagnosis or treatment decisions.
If you found this project useful, consider giving it a star.