diff --git a/README.md b/README.md index 6bc74e5..4ebf782 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,66 @@ # Brain Tumor Segmentation — BraTS 2023 -3D brain tumor segmentation on multimodal MRI data using MONAI and PyTorch, with a full MLOps pipeline including experiment tracking, CI/CD, containerized inference, and an interactive demo. +3D brain tumor segmentation on multimodal MRI data using MONAI and PyTorch, with a full MLOps pipeline including experiment tracking, CI/CD, containerized inference, and an interactive 3D demo. --- -## Overview +## Demo -This project trains a 3D U-Net on the BraTS 2023 dataset to segment brain tumor subregions from multimodal MRI volumes (T1, T1ce, T2, FLAIR). The model predicts three clinically meaningful subregions: +🔗 **[Live Demo — Hugging Face Spaces](https://huggingface.co/spaces/AndrewVFranco/NeuralSeg)** -- **Whole Tumor (WT)** — full tumor extent -- **Tumor Core (TC)** — necrotic core and enhancing tissue -- **Enhancing Tumor (ET)** — actively growing tumor region +Upload any BraTS-format MRI volume and visualize predicted tumor subregion masks interactively across axial, coronal, and sagittal planes. -Beyond model training, the project implements a production-style MLOps pipeline: experiment tracking, automated evaluation, containerized inference, and a live interactive demo where users can upload an MRI volume and visualize predicted segmentation masks across axial, coronal, and sagittal planes. +![UI Screenshot](notebooks/figures/ui_screenshot.png) --- -## Demo +## Results + +Evaluated on 188 held-out BraTS 2023 GLI test cases. Metrics computed using standard image-level Dice and Hausdorff95. + +| Subregion | Dice ↑ | HD95 (mm) ↓ | +|---|---|---| +| Whole Tumor (WT) | **0.930** | **5.94** | +| Tumor Core (TC) | **0.910** | **3.76** | +| Enhancing Tumor (ET) | **0.848** | **3.23** | + +### Leaderboard Comparison + +| Model | WT Dice | TC Dice | ET Dice | WT HD95 | TC HD95 | ET HD95 | +|-------------------------------|---|---|---|---|---|---| +| **This Model (3D U-Net)** | **0.930** | **0.910** | **0.848** | **5.94** | **3.76** | **3.23** | +| BraTS 2023 Winner (ensemble)† | 0.901 | 0.867 | 0.851 | 14.94 | 14.47 | 17.70 | +| KLE-based SOTA (2024)† | 0.929 | — | — | 2.93 | 6.78 | 10.35 | + +† Challenge entries report lesion-wise metrics which penalize missed lesions and false positives, resulting in lower scores than the standard image-level metrics used here. + +### Dice Score Distribution -> 🔗 Live demo link — coming soon (Hugging Face Spaces) +![Dice Boxplot](notebooks/figures/dice_boxplot.png) + +Full evaluation details and qualitative visualizations in [`notebooks/02_evaluation.ipynb`](notebooks/02_evaluation.ipynb). --- -## Results +## Overview -| Subregion | Dice Score | Hausdorff95 | -|---|---|---| -| Whole Tumor (WT) | TBD | TBD | -| Tumor Core (TC) | TBD | TBD | -| Enhancing Tumor (ET) | TBD | TBD | +This project trains a 3D U-Net on the BraTS 2023 GLI dataset to segment brain tumor subregions from multimodal MRI volumes. The model predicts three clinically meaningful subregions: + +- **Whole Tumor (WT)** — full tumor extent (labels 1 + 2 + 3) +- **Tumor Core (TC)** — necrotic core and enhancing tissue (labels 1 + 3) +- **Enhancing Tumor (ET)** — actively growing tumor region (label 3) -*Evaluated on BraTS 2023 held-out validation split. Comparison to published BraTS leaderboard baselines documented in `/notebooks/evaluation.ipynb`.* +Beyond model training, the project implements a production-style MLOps pipeline: experiment tracking with MLflow, automated CI/CD via GitHub Actions, containerized inference via Docker, and a publicly accessible live demo. --- ## Architecture - **Model:** 3D U-Net with residual connections (MONAI) -- **Input:** 4-channel multimodal MRI volume (T1, T1ce, T2, FLAIR), normalized and skull-stripped -- **Output:** 3-class segmentation mask (WT / TC / ET) +- **Input:** 4-channel multimodal MRI volume (T1, T1ce, T2, FLAIR), skull-stripped and intensity normalized +- **Output:** 3-class voxel-wise segmentation mask (WT / TC / ET) - **Loss:** Dice loss + cross-entropy (combined) -- **Inference:** Sliding window inference over full volume +- **Inference:** Sliding window inference with 128³ ROI over full volume --- @@ -48,17 +68,27 @@ Beyond model training, the project implements a production-style MLOps pipeline: ``` brats-tumor-segmentation/ +├── .github/workflows/ # GitHub Actions CI/CD (ci.yml) +├── checkpoints/ # Saved model weights (best_model.pth) +├── configs/ # YAML training configuration ├── data/ # gitignored — BraTS NIfTI volumes +│ ├── raw/ # original downloaded volumes +│ ├── processed/ # skull-stripped, normalized volumes +│ └── splits/ # train/val/test split definitions +├── docker/ # Dockerfile + .dockerignore +├── notebooks/ +│ ├── figures/ # saved evaluation plots +│ ├── 01_data_exploration.ipynb +│ └── 02_evaluation.ipynb ├── src/ -│ ├── preprocessing/ # skull stripping, bias correction, normalization -│ ├── training/ # model definition, training loop, loss functions -│ ├── inference/ # sliding window inference, postprocessing -│ └── utils/ # shared utilities, visualization helpers -├── notebooks/ # exploration, training walkthrough, evaluation -├── configs/ # YAML training configs +│ ├── inference/ # sliding window inference, FastAPI endpoint +│ ├── interface/ # NiiVue 3D viewer (index.html + sample cases) +│ ├── preprocessing/ # skull stripping, normalization, split creation +│ ├── training/ # model, dataloader, transforms, training loop +│ └── utils/ # data download, manifest utilities ├── tests/ # pytest unit tests -├── docker/ # Dockerfile + compose for inference service -├── .github/workflows/ # GitHub Actions CI/CD +├── .env +├── pyproject.toml ├── requirements.txt └── README.md ``` @@ -67,11 +97,13 @@ brats-tumor-segmentation/ ## MLOps Pipeline -- **Experiment tracking:** MLflow — logs hyperparameters, per-epoch metrics, Dice scores, and sample segmentation visualizations as artifacts -- **Model registry:** MLflow model registry with version tags and metric annotations -- **CI/CD:** GitHub Actions — runs linting, unit tests, and model evaluation on every PR -- **Containerization:** Docker — reproducible inference environment -- **Deployment:** Hugging Face Spaces — publicly accessible live demo +| Component | Tool | Details | +|---|---|---| +| Experiment tracking | MLflow | Logs hyperparameters, per-epoch metrics, and segmentation visualizations as artifacts | +| Model registry | MLflow | Version tags with metric annotations | +| CI/CD | GitHub Actions | Linting, unit tests, and model checks on every PR | +| Containerization | Docker | Reproducible inference environment | +| Deployment | Hugging Face Spaces | Publicly accessible live demo | --- @@ -94,7 +126,7 @@ pip install -r requirements.txt ### Data -Download BraTS 2023 data from [Synapse](https://www.synapse.org/) (free registration required). Place volumes in `/data/raw/`. See `/notebooks/01_data_exploration.ipynb` for expected directory structure. +Download BraTS 2023 GLI data from [Synapse](https://www.synapse.org/) (free registration required). Place volumes in `data/raw/`. See `notebooks/01_data_exploration.ipynb` for expected directory structure. ### Training @@ -108,21 +140,28 @@ python src/training/train.py --config configs/train_config.yaml python src/inference/predict.py --input path/to/volume.nii.gz --output path/to/output/ ``` +### Docker + +```bash +docker build -f docker/Dockerfile -t brats-inference . +docker run -p 8000:8000 brats-inference +``` + --- ## Dataset -**BraTS 2023** (Brain Tumor Segmentation Challenge) +**BraTS 2023 GLI** (Brain Tumor Segmentation Challenge — Glioma) - Hosted via Synapse (RSNA-ASNR-MICCAI) - ~1,200 multimodal MRI cases with expert annotations - Four MRI modalities per case: T1, T1ce, T2, FLAIR -- Labels: background, necrotic core, peritumoral edema, enhancing tumor +- Labels: 0 — background, 1 — necrotic core, 2 — peritumoral edema, 3 — enhancing tumor --- ## Background -This project was developed as part of a portfolio demonstrating full-stack ML engineering competency in clinical medical imaging. Bringing 8+ years of clinical experience in cardiac telemetry monitoring, informing the design of the system with real-world awareness of clinical workflow constraints and patient safety considerations. +Developed as a portfolio project demonstrating full-stack ML engineering in clinical medical imaging. Informed by 8+ years of clinical experience in cardiac telemetry monitoring, with real-world awareness of clinical workflow constraints, alarm fatigue, and patient safety considerations that are often absent from purely academic implementations. --- diff --git a/notebooks/figures/segmap_overlay.png b/notebooks/figures/segmap_overlay.png deleted file mode 100644 index 25bc10f..0000000 Binary files a/notebooks/figures/segmap_overlay.png and /dev/null differ diff --git a/notebooks/figures/ui_screenshot.png b/notebooks/figures/ui_screenshot.png new file mode 100644 index 0000000..675fff4 Binary files /dev/null and b/notebooks/figures/ui_screenshot.png differ diff --git a/src/interface/index.html b/src/interface/index.html index 48a9ece..945ec73 100644 --- a/src/interface/index.html +++ b/src/interface/index.html @@ -6,6 +6,7 @@ NeuralSeg — Brain Tumor Segmentation + - +
- -
-
- Upload MRI volumes to begin +
+ + +
+ +
+
+
+ Upload MRI volumes to begin +
+