Spaces:

Expanic
/

SEPSIS_ICU_MIMIC

Sleeping

App Files Files Community

SEPSIS_ICU_MIMIC / README.md

Expanic

Fix HF Spaces configuration header

9392e43 about 1 month ago

preview code

Raw

History Blame Contribute Delete

11.2 kB

metadata

title: SEPSIS ICU MIMIC
emoji: 🔥
colorFrom: blue
colorTo: red
sdk: docker
pinned: false

🏥 Sepsis Prediction System

An AI-powered early warning system for sepsis prediction using MIMIC-IV ICU data

Features • Installation • Dataset • API Docs • Deployment

📋 Overview

This application leverages machine learning to predict sepsis risk in ICU patients using the MIMIC-IV clinical database. The system provides:

Real-time sepsis risk prediction with probability scores
Multi-organ dysfunction scoring (SOFA-based: Respiratory, Cardiovascular, Renal, CNS)
Patient monitoring dashboard with emergency patient tracking
Beautiful, modern UI with dark theme and responsive design

⚠️ Important: This project uses the MIMIC-IV dataset which requires credentialed access. See Obtaining MIMIC-IV Dataset for instructions.

✨ Features

Feature	Description
🔮 AI Prediction	GRU-D + Transformer model for sepsis probability prediction
📊 Multi-output	Predicts multiple SOFA component scores (6h, 12h, 24h windows)
🏥 Patient Dashboard	View hospital-wide statistics and emergency patients
📝 Data Entry	Add new patient measurements with auto-forward-fill
📈 Visualizations	Risk gauges, charts, and patient body visualization
🔄 Real-time Updates	Auto-refresh patient data and predictions

📁 Project Structure

Sepsis-Prediction/
├── backend/                    # FastAPI Backend Server
│   ├── api.py                  # API endpoint definitions
│   ├── main.py                 # FastAPI app entry point
│   ├── database.py             # SQLAlchemy database models
│   ├── model_wrapper.py        # ML model loading & prediction logic
│   ├── schemas.py              # Pydantic request/response schemas
│   ├── requirements.txt        # Python dependencies
│   └── venv/                   # Python virtual environment (create yourself)
│
├── frontend/                   # Next.js Frontend Application
│   ├── src/
│   │   ├── app/                # Next.js App Router
│   │   │   ├── page.tsx        # Main page component
│   │   │   ├── layout.tsx      # Root layout
│   │   │   └── globals.css     # Global styles
│   │   ├── components/
│   │   │   ├── dashboard/      # Dashboard components
│   │   │   │   ├── HospitalOverview.tsx
│   │   │   │   ├── PatientDashboard.tsx
│   │   │   │   ├── PredictionResults.tsx
│   │   │   │   └── DistributionChart.tsx
│   │   │   ├── form/           # Form components
│   │   │   │   └── SepsisForm.tsx
│   │   │   ├── ui/             # Reusable UI components
│   │   │   │   ├── RiskGauge.tsx
│   │   │   │   ├── MinMaxInput.tsx
│   │   │   │   └── ...
│   │   │   └── layout/
│   │   │       └── BodyVisualizer.tsx
│   │   └── lib/                # Utilities
│   ├── package.json
│   └── .env.local              # Environment variables (create yourself)
│
├── new_model/                  # Trained ML Model Artifacts
│   ├── model_joblib.pkl        # Main XGBoost model
│   ├── scaler_X.pkl            # Feature scaler
│   ├── scaler_y_reg.pkl        # Target scaler
│   └── global_feat_mean30.npy  # Feature means for imputation
│
├── sql/                        # Database Queries
│   └── select_query.sql        # MIMIC-IV data extraction query
│
├── dataset/                    # Dataset files (NOT included - see instructions)
│
├── notebook/                   # Jupyter notebooks for training
│
├── .gitignore                  # Git ignore rules
├── .gitattributes              # Git LFS configuration
└── README.md                   # This file

🚀 Installation

Prerequisites

Python 3.10+
Node.js 18+
Git LFS (for large model files)

1. Clone Repository

git clone https://github.com/Expanics/Sepsis-Prediction.git
cd Sepsis-Prediction

# Pull LFS files (model artifacts)
git lfs pull

2. Backend Setup

cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3. Frontend Setup

cd frontend

# Install dependencies
npm install

# Create environment file
echo "NEXT_PUBLIC_API_URL=http://127.0.0.1:8000" > .env.local

🗄️ Obtaining MIMIC-IV Dataset

The MIMIC-IV database is a restricted dataset requiring credentialed access from PhysioNet.

Step 1: Get PhysioNet Access

Go to PhysioNet
Create an account and complete the CITI training course
Request access to MIMIC-IV
Wait for approval (usually 1-2 weeks)

Step 2: Access via Google BigQuery

Once approved, you can access MIMIC-IV via Google BigQuery:

Go to Google Cloud Console
Create or select a project
Enable the BigQuery API
Link your PhysioNet credentials to access physionet-data.mimiciv_3_1_derived

Step 3: Run the Data Extraction Query

Execute the SQL query in sql/select_query.sql using BigQuery:

-- This query extracts hourly patient data with vital signs, 
-- lab values, and sepsis labels from MIMIC-IV

-- See sql/select_query.sql for the complete query

Export the results to CSV or Parquet format.

Step 4: Prepare the Database

After obtaining the dataset, load it into the SQLite database:

# In backend/ directory
import pandas as pd
from database import init_db, get_db, PatientData
from sqlalchemy.orm import Session

# Load your exported data
df = pd.read_csv('your_mimic_data.csv')  # or parquet

# Initialize database
init_db()

# Insert data (use your own script or modify database.py)

🏃 Running the Application

Start Backend Server

cd backend
source venv/bin/activate  # or .\venv\Scripts\activate on Windows
export OMP_NUM_THREADS=1  # Recommended for model performance
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

Backend will be available at: http://localhost:8000

Start Frontend Server

cd frontend
npm run dev

Frontend will be available at: http://localhost:3000

📡 API Endpoints

Base URL: http://localhost:8000

Statistics & Overview

Method	Endpoint	Description
`GET`	`/`	Health check - API status
`GET`	`/stats`	Get hospital statistics (total patients, sepsis cases, demographics)

Patient Management

Method	Endpoint	Description
`GET`	`/patients`	List all patients (with optional `?search=` query)
`GET`	`/patients/emergency`	Get patients with sepsis (limit=50)
`GET`	`/patient/{stay_id}`	Get patient's complete history
`POST`	`/patient`	Add new patient measurement record

Predictions

Method	Endpoint	Description
`POST`	`/predict/{stay_id}?window_hours=6`	Predict for existing patient (6/12/24h window)
`POST`	`/predict?window_hours=6`	Predict from manual input data

Example Requests

Get Patient List:

curl http://localhost:8000/patients?search=12345

Get Prediction for Patient:

curl -X POST "http://localhost:8000/predict/30001234?window_hours=6"

Manual Prediction:

curl -X POST "http://localhost:8000/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "heart_rate_min": 70,
    "heart_rate_max": 90,
    "temperature_min": 36.5,
    "temperature_max": 37.2,
    ...
  }'

Response Format

Prediction Output:

{
  "sepsis": 0.45,           // Sepsis probability (0-1)
  "respiration": 1.2,       // Respiratory SOFA score
  "cardiovascular": 0.8,    // Cardiovascular SOFA score
  "renal": 0.3,             // Renal SOFA score
  "cns": 0.5                // CNS SOFA score
}

🛠️ Development

Running Tests

# Backend
cd backend
pytest

# Frontend
cd frontend
npm test

Environment Variables

Backend (backend/.env):

DATABASE_URL=sqlite:///./patients.db
MODEL_PATH=../new_model

Frontend (frontend/.env.local):

NEXT_PUBLIC_API_URL=http://127.0.0.1:8000

📦 Model Information

The prediction model is built using:

Algorithm: XGBoost Multi-output Regressor
Features: 80+ clinical variables (vital signs, lab values, etc.)
Outputs: Sepsis probability + 4 SOFA component scores
Training Data: MIMIC-IV ICU dataset (~100k patients)

Feature Categories

Category	Features
Vital Signs	Heart rate, BP, Temperature, SpO2, Respiratory rate
Blood	WBC, Platelets, Hemoglobin, Neutrophils, INR, PT
Respiratory	PO2, PCO2, FiO2, P/F ratio, Ventilation status
Acid-Base	pH, Lactate, Bicarbonate, Base excess
Electrolytes	Na, K, Cl, Ca, Glucose
Chemistry	Creatinine, BUN, Albumin, Bilirubin, Liver enzymes
Neurological	GCS (motor, verbal, eyes)
Cardiac	Troponin, CK-MB, NT-proBNP
Vasopressors	Dopamine, Epinephrine, Norepinephrine doses

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

This application is for research and educational purposes only. It should NOT be used for clinical decision-making without proper validation and regulatory approval. Always consult qualified healthcare professionals for medical decisions.

🙏 Acknowledgments

MIMIC-IV Database - PhysioNet
Sepsis-3 Definitions - JAMA
Built with ❤️ using FastAPI, Next.js, and XGBoost