Explainable-Stroke-Risk-AI

Explainable AI-Based Stroke Risk Assessment System

An educational project scaffold for exploring stroke-risk classification and model explainability. It is not a medical device and must not be used to diagnose, treat, or guide care.

Current status

• The supplied dataset is stored unchanged at data/stroke_risk_prediction_dataset.csv.
• Dataset inspection is available through backend/ml/analyze_dataset.py; it prints the requested checks and regenerates reports/dataset_analysis.md.
• Data-quality and leakage analysis is available through backend/ml/data_quality.py; it updates backend/ml/feature_config.json and reports/data_quality_and_leakage.md.
• The cleaned model-input copy is generated by backend/ml/prepare_data.py at data/processed/stroke_risk_prepared.csv.
• Exploratory analysis is available through backend/ml/exploratory_analysis.py; it writes figures to images/eda/ and a report to reports/exploratory_data_analysis.md.
• The shared, training-partition-only preprocessing code and SHAP feature-name mapping are documented in backend/ml/PREPROCESSING.md.
• Stratified partitions and training-only imbalance comparisons are documented in backend/ml/IMBALANCE.md.
• Multi-class baseline training/evaluation is implemented in backend/ml/train_models.py; it uses train and validation only and leaves the final test locked.
• Hyperparameter search and one-time final evaluation are documented in backend/ml/TUNING.md.
• Global and local SHAP explanations are documented in backend/app/services/SHAP.md and exposed through /explain and /explanations API routes.
• Prediction API endpoints, validation behavior, and request/response formats are documented in backend/app/API.md.
• FastAPI serves the saved final model and SHAP explanation endpoints; startup loads the fitted artifacts without retraining.
• The React frontend includes Home, Assessment, Results, AI Explanation, Model Performance, and About pages.

Dataset analysis

From the workspace root, run:

python backend/ml/analyze_dataset.py

An alternate CSV or report destination can be supplied with --csv and --report.

Data quality and EDA

From the workspace root, run the checks and prepare the separate model-input copy:

python backend/ml/data_quality.py
python backend/ml/prepare_data.py
python backend/ml/exploratory_analysis.py

The EDA runner uses the persisted feature configuration and prepared dataset. It does not train a model; figures are saved under images/eda/.

Stratified splits and imbalance

python backend/ml/split_data.py
python backend/ml/class_imbalance.py

These commands create train, validation, and locked final-test partitions, then compare training-only balanced weights and random oversampling. The test partition is not read by the imbalance analysis.

Baseline model evaluation

python backend/ml/train_models.py

This trains the four baseline candidates on the training split, evaluates them on validation, and saves metrics, curves, and candidate pipelines. It does not access the locked test split or tune hyperparameters.

Hyperparameter tuning and final evaluation

python -m backend.ml.tune_models

This uses stratified cross-validation on training data, validation-based model selection, then evaluates the selected pipeline once on the locked test split and saves the final artifacts.

Backend

Create and activate a Python environment, then install backend dependencies:

python -m venv backend/.venv
backend/.venv/Scripts/Activate.ps1
python -m pip install -r backend/requirements.txt

Start the API from the backend directory:

python -m uvicorn app.main:app --reload

The health check is at http://127.0.0.1:8000/health and the generated API documentation is at http://127.0.0.1:8000/docs.

Frontend

In another terminal, from the workspace root:

Copy-Item frontend/.env.example frontend/.env.local
Set-Location frontend
npm install
npm run dev

Open http://localhost:5173. Set VITE_API_BASE_URL in frontend/.env.local if the API runs at another origin. The backend CORS allow-list is configured with FRONTEND_ORIGINS.

Safety

This system is for educational experimentation only. Its outputs are not medical diagnoses or a substitute for professional medical advice.