Create README.md

README.md

@@ -0,0 +1,141 @@
+---
+license: cc-by-4.0
+tags:
+- medical-imaging
+- segmentation
+- pytorch
+- deeplabv3plus
+- brain-tumor
+- mri
+library_name: pytorch
+---
+
+# Brain Tumor Segmentation — DeepLabv3+ (ResNet-34 + ASPP + WBCE)
+
+An implementation of the architecture and training recipe described in
+Soomro et al., *"Boosting Brain Tumor Detection Accuracy in MRI Using
+Transfer Learning and Fine-Tuned DeepLabv3+"* (IEEE Open Journal of the
+Computer Society, 2026), trained on the CE-MRI brain tumor dataset
+(Cheng et al., 233 patients, 3,064 T1-weighted contrast-enhanced axial
+slices: glioma, meningioma, pituitary tumors).
+
+This is a personal/academic reproduction project — **not the original
+authors' model, not clinically validated, and not for medical use.**
+See [Honest results](#honest-results-vs-the-paper) below before using
+this for anything beyond learning/experimentation.
+
+## Model architecture
+
+- ResNet-34 encoder, initialized from ImageNet-pretrained weights
+- Atrous Spatial Pyramid Pooling (ASPP), rates 12/16/18 + global image pooling
+- Lightweight decoder fusing low-level and ASPP features (DeepLabv3+ design)
+- Binary output: tumor vs. background, per pixel
+- Trained with Weighted Binary Cross-Entropy (WBCE) loss, with per-slice
+  adaptive class-imbalance weighting
+
+## Training setup
+
+- 100 epochs, Adam optimizer (β1=0.9, β2=0.999, weight decay 1e-5),
+  initial LR 1e-4 with `ReduceLROnPlateau`
+- Patient-wise 70/15/15 train/val/test split (163/35/35 patients) —
+  no patient's slices appear in more than one split, avoiding data leakage
+- Image size 512×512, batch size 8
+- Trained on a single Kaggle GPU session (T4×2)
+
+Full training/evaluation code: **[link to your GitHub repo here]**
+
+## Honest results vs. the paper
+
+The paper reports ~98% DSC and ~99.3% sensitivity. This reproduction
+falls meaningfully short of that on the two metrics that matter most for
+segmentation quality (DSC, sensitivity), while matching closely on
+accuracy/specificity — which is expected, since ~98% of pixels in these
+images are background, so accuracy/specificity are dominated by the easy
+majority class rather than tumor-finding ability.
+
+| Metric | This model (test set, 35 held-out patients) | Paper |
+|---|---:|---:|
+| DSC (overall) | **75.6%** | 98.0% |
+| Sensitivity | 88.95% | 99.3% |
+| Specificity | 99.34% | 98.99% |
+| Accuracy | 99.11% | 99.1% |
+
+Per-tumor-type DSC: glioma 70.2%, meningioma 85.5%, pituitary 74.6% —
+the same relative ordering (meningioma easiest, glioma hardest) as the
+paper reports, which is a useful internal consistency check even though
+absolute numbers differ.
+
+**Why the gap likely exists** (in rough order of suspected impact):
+1. The paper doesn't fully specify some architectural details (exact
+   decoder channel widths, output stride choice, precise augmentation
+   policy) — this implementation fills those gaps with standard
+   DeepLabv3+ conventions, which may not match the authors' exact setup.
+2. Training was extended from 40 to 100 epochs and DSC barely moved
+   (74.3% → 75.6%), suggesting the model has converged for this
+   configuration — the remaining gap is not simply "needs more training."
+3. Possible differences in preprocessing intensity (the paper mentions
+   CLAHE contrast enhancement; exact parameters aren't given) or data
+   augmentation strength.
+
+This gap is reported transparently rather than hidden — reproducing a
+paper's exact numbers without the authors' full implementation details
+is a known hard problem in ML research, and getting a rigorous, honest
+measurement of *how far off* a reproduction is is itself the useful
+skill being demonstrated here.
+
+## Intended use
+
+- Educational / portfolio demonstration of a segmentation pipeline
+  (transfer learning, class-imbalance-aware loss, patient-wise
+  evaluation discipline)
+- Starting point for further experimentation (e.g. testing architectural
+  variants, better augmentation, longer training with a different LR
+  schedule)
+
+## Out of scope / not suitable for
+
+- Any clinical, diagnostic, or medical decision-making use
+- Deployment without independent validation on a properly consented,
+  IRB-approved clinical dataset
+- Use as a certified medical device (it is not one, and has not been
+  evaluated as one)
+
+## How to use
+
+```python
+import torch
+from model import DeepLabV3Plus  # from this repo's model.py
+
+model = DeepLabV3Plus(num_classes=1, use_imagenet_init=False)
+state = torch.load("pytorch_model.pt", map_location="cpu", weights_only=False)
+model.load_state_dict(state)
+model.eval()
+
+# image: torch.Tensor, shape (1, 3, 512, 512), ImageNet-normalized
+with torch.no_grad():
+    logits = model(image)
+    mask = (torch.sigmoid(logits) > 0.5).float()
+```
+
+See the [GitHub repo](#) for the full `dataset.py` preprocessing pipeline
+(CLAHE + ImageNet normalization) needed to prepare inputs correctly.
+
+## Dataset
+
+Trained on the CE-MRI brain tumor dataset (Cheng et al., 2017,
+*"Enhanced performance of brain tumor classification via tumor region
+augmentation and partition,"* PLoS ONE). This repository does not
+redistribute the dataset — see the original publication for access.
+
+## Citation
+
+If referencing the original paper this reproduces:
+
+```
+Soomro et al., "Boosting Brain Tumor Detection Accuracy in MRI Using
+Transfer Learning and Fine-Tuned DeepLabv3+," IEEE Open Journal of the
+Computer Society, vol. 7, 2026.
+```
+
+This repository is an independent reproduction and is not affiliated
+with the original authors.