Skip to content

README.md

Latest commit

 

History

History
212 lines (160 loc) · 6.9 KB

README.md

File metadata and controls

212 lines (160 loc) · 6.9 KB
Raw

🔬 OmicPath

Multimodal Breast Cancer Survival Prediction — WSI + RNA-seq

OmicPath fuses gigapixel H&E histopathology slides with transcriptomic pathway scores to jointly predict 5-year survival risk, PAM50 molecular subtype, and TP53 mutation status. An ABMIL attention heatmap overlaid on the slide thumbnail provides spatial interpretability.

CI/CD License: MIT

Results

Task Metric Mean Std
Survival prediction C-index 0.666 ±0.053
PAM50 subtype Accuracy 0.700 ±0.042
TP53 mutation AUROC 0.818 ±0.020

TCGA-BRCA · 1,030 patients · 5-fold cross-validation

Architecture

WSI (.svs / .h5)                    RNA (natural language)
       │                                     │
HistoPrep tiling (256×256)        LLM → 50 Hallmark pathway scores
       │                                     │
 UNI2-h encoder (ViT-H, 1536-d)    RNA encoder (MLP, 512-d)
       │                                     │
 ABMIL attention pooling  ←── Bidirectional CrossAttention ──→
                                      │
                     ┌────────────────┼────────────────┐
                     │                │                │
              Cox PH survival    PAM50 (×5)       TP53 (×2)
Component Details
WSI encoder UNI2-h (ViT-H/14, 1536-d, MahmoodLab)
RNA encoder 3-layer MLP + LayerNorm + Dropout
Fusion Bidirectional CrossAttention (8 heads, 2 layers)
Survival Cox PH loss + Breslow estimator
Calibration Platt scaling ensemble (5 folds)
XAI ABMIL attention heatmap via medical-ai-middleware

Demo

$env:OPENROUTER_API_KEY      = "sk-or-..."
$env:HUGGING_FACE_HUB_TOKEN  = "hf_..."
python hf_spaces_app.py
# → http://localhost:7860
  1. Upload .svs or pre-extracted .h5
  2. Describe molecular profile in plain English
  3. Check GDPR consent box
  4. Click ▶ Run Analysis

Outputs: Risk group + 5-year mortality · PAM50 subtype · TP53 status · Attention heatmap · LLM clinical report

Input Results
Input form Results
Attention Heatmap Clinical Report
Heatmap Report

Installation

git clone https://github.com/moebouassida/omicpath.git
cd omicpath
pip install -r requirements.txt

Requirements:

  • Python 3.12, PyTorch 2.2+
  • CUDA GPU recommended for SVS pipeline
  • OpenSlide — Windows: extract to C:\openslide-win64; Linux: apt install libopenslide-dev
  • HF token for UNI2-h — request access at MahmoodLab/UNI2-h

FastAPI Server

uvicorn src.app:app --host 0.0.0.0 --port 8000 --reload
Method Endpoint Description
GET /health Liveness probe
GET /metrics Prometheus scrape
POST /predict Predict from H5 + RNA text
POST /predict/svs Full SVS pipeline
GET /audit Audit log (last N entries)
DELETE /audit/{request_id} GDPR right to erasure

Rate limits: /predict* → 10 req/min · default → 30 req/min

Docker

Requires an OPENROUTER_API_KEY environment variable.

# CPU
OPENROUTER_API_KEY=sk-or-... docker compose up

# With monitoring (Prometheus + Grafana at :9090 / :3000)
OPENROUTER_API_KEY=sk-or-... docker compose --profile monitoring up

Training

python src/train.py \
  --config config/config.yaml \
  --wsi_dir data/wsi_features/ \
  --rna_path data/rna/processed/pathway_activity.csv \
  --survival_path data/clinical/survival.csv

5-fold CV · AdamW + cosine LR · MultiTask loss · WandB logging · early stopping on C-index

Project Structure

omicpath/
├── src/
│   ├── models/             # WSIEncoder, RNAEncoder, Fusion, OmicPath
│   ├── app.py              # FastAPI server
│   ├── predict.py          # Inference pipeline
│   ├── train.py            # Training loop
│   ├── explainer.py        # LLM clinical report (OpenRouter)
│   ├── losses.py           # MultiTask + Cox PH loss
│   ├── metrics.py          # C-index, AUROC, accuracy
│   ├── dataset.py          # TCGA-BRCA loader
│   ├── calibrate.py        # Platt scaling
│   └── evaluate.py         # Evaluation suite
├── hf_spaces_app.py        # Gradio demo
├── config/config.yaml      # Model + training config
├── Dockerfile              # CPU image
├── docker-compose.yml      # Full stack (API + monitoring)
├── requirements.txt
└── .github/workflows/      # CI/CD (lint → test → build → deploy)

Environment Variables

Variable Default Description
OPENROUTER_API_KEY required OpenRouter API key (get one at openrouter.ai/keys)
HUGGING_FACE_HUB_TOKEN optional Required only for .svs uploads (downloads UNI2-h on first use). Not needed for .h5 inference.
LLM_MODEL anthropic/claude-sonnet-4-5 Any model available on OpenRouter
S3_ENABLED false Enable S3 audit logging
AWS_ACCESS_KEY_ID — AWS credentials
AWS_SECRET_ACCESS_KEY — AWS credentials
AWS_REGION us-east-1 AWS region
S3_BUCKET_LOGS medical-ai-logs S3 bucket for audit log entries
S3_BUCKET_XAI medical-ai-xai S3 bucket for attention heatmap PNGs
RATE_LIMIT_PREDICT 10/minute Rate limit for /predict
RATE_LIMIT_DEFAULT 30/minute Default rate limit
MAX_PATCHES 2048 Max WSI patches per slide

Privacy & Compliance

  • GDPR Art. 9 consent gate before every prediction
  • Anonymized IP logging (last octet zeroed)
  • Right to erasure via DELETE /audit/{request_id}
  • Local by default — no patient data sent externally
  • S3 audit with 24h lifecycle auto-deletion when S3_ENABLED=true
  • Powered by medical-ai-middleware

Citation

@software{omicpath2026,
  author = {Bouassida, Moez},
  title  = {OmicPath: Multimodal Breast Cancer Survival Prediction},
  year   = {2026},
  url    = {https://github.com/moebouassida/omicpath}
}

License

MIT — see LICENSE.

⚠️ Research use only. OmicPath is not a medical device and does not constitute clinical advice. All outputs must be interpreted by qualified healthcare professionals.