Add model card (v1 deployed / v2 rigorous evaluation)

README.md

@@ -0,0 +1,127 @@
+---
+license: mit
+language:
+  - en
+tags:
+  - image-classification
+  - medical-imaging
+  - histopathology
+  - breast-cancer
+  - pytorch
+  - convnext
+  - patchcamelyon
+pipeline_tag: image-classification
+---
+
+# Cancer_pathos — Histopathologic Cancer Detection (ConvNeXt-Tiny)
+
+Binary classification of **metastatic cancer in 96×96 histopathologic tissue patches**
+(PatchCamelyon / Kaggle *Histopathologic Cancer Detection*). Backbone **ConvNeXt-Tiny**
++ a custom **residual classification head** (1 logit, sigmoid).
+
+> ⚠️ **Research Use Only (RUO)** — this is **not** a certified medical device and must **not** be used for clinical diagnosis.
+
+🔗 **Code & full report:** https://github.com/Hakim78/histopathologic-cancer-detection
+🤗 **Interactive demo:** https://huggingface.co/spaces/hakim78/Cancer_pathos_demo
+
+---
+
+## 📦 Checkpoints
+
+| File | Training data | Role | Headline metric |
+|------|---------------|------|-----------------|
+| `models/best_model_epoch50_auc0.9980.pth` | ~95 % of labels, 50 epochs | **v1 — deployed in the demo** | Validation AUC **0.9983** (TTA ×5) |
+| `models/final_model_v2_locked.pth` | 70 % train, early-stopped on val | **v2 — rigorous evaluation** | Locked-test AUC **0.9979** (TTA ×5) |
+
+- **v1** maximizes performance (more data, longer training) and powers the live demo.
+- **v2** was trained under a stricter protocol — a 3-way split with a **strictly locked test set** + 5-fold cross-validation — to report a **defensible, independent** test metric.
+
+---
+
+## 📊 Results (v2 — rigorous protocol)
+
+70 / 15 / 15 stratified split (seed 42). The 15 % **test set (33,004 patches) is locked**:
+never used for training, model selection or hyperparameters — opened once for the final metrics.
+Robustness first estimated by 5-fold cross-validation on train+val.
+
+| Metric | 5-fold CV (mean ± σ) | Locked test (TTA ×5) |
+|--------|:--------------------:|:--------------------:|
+| AUC-ROC | 0.9975 ± 0.0001 | **0.9979** |
+| Accuracy | 0.9821 ± 0.0008 | **0.9847** |
+| F1-score | 0.9778 ± 0.0010 | **0.9810** |
+| Brier Score | 0.0212 ± 0.0005 | **0.0172** |
+| Sensitivity | 0.9753 ± 0.0015 | **0.9794** |
+| Specificity | 0.9867 ± 0.0006 | **0.9882** |
+
+Calibration on the locked test: **Brier 0.0172, ECE 0.0449**.
+Confusion matrix (33,004 patches): **TN 19,405 · FP 231 · FN 275 · TP 13,093**.
+TTA ×5 yields a small but statistically significant gain (DeLong on AUC: z = 6.62, p < 10⁻⁴).
+Full metrics in [`results_v2/`](results_v2).
+
+---
+
+## 🏗 Architecture & training
+
+- **Backbone:** `timm` `convnext_tiny` (ImageNet-pretrained, `num_classes=0`, `drop_rate=0.3`) → 768-d features.
+- **Head:** Residual MLP — `Linear(768→256) → BN → GELU → Dropout → Linear(256→256) → BN → (+ shortcut) → GELU → Dropout → Linear(256→1)`.
+- **Loss:** Focal Loss (α = 0.25, γ = 2.0). **Optimizer:** AdamW (lr 1e-4, wd 1e-5). **Scheduler:** CosineAnnealingLR. **AMP** enabled. **Seed:** 42.
+- **Input:** RGB 96×96, ImageNet normalization (mean `[0.485, 0.456, 0.406]`, std `[0.229, 0.224, 0.225]`).
+
+---
+
+## 🚀 Usage
+
+```python
+import torch, timm
+import torch.nn as nn
+from huggingface_hub import hf_hub_download
+
+class ResidualHead(nn.Module):
+    def __init__(self, in_features, hidden=256, dropout=0.3):
+        super().__init__()
+        self.fc1, self.bn1 = nn.Linear(in_features, hidden), nn.BatchNorm1d(hidden)
+        self.fc2, self.bn2 = nn.Linear(hidden, hidden), nn.BatchNorm1d(hidden)
+        self.fc_out, self.shortcut = nn.Linear(hidden, 1), nn.Linear(in_features, hidden)
+        self.gelu, self.dropout = nn.GELU(), nn.Dropout(dropout)
+    def forward(self, x):
+        identity = self.shortcut(x)
+        out = self.dropout(self.gelu(self.bn1(self.fc1(x))))
+        out = self.gelu(self.bn2(self.fc2(out)) + identity)
+        return self.fc_out(self.dropout(out))
+
+class CancerClassifier(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.backbone = timm.create_model("convnext_tiny", pretrained=False, num_classes=0)
+        self.head = ResidualHead(self.backbone.num_features)
+    def forward(self, x):
+        return self.head(self.backbone(x))
+
+model = CancerClassifier()
+
+# v2 (rigorous) — raw state_dict:
+path = hf_hub_download("hakim78/Cancer_pathos", "models/final_model_v2_locked.pth")
+model.load_state_dict(torch.load(path, map_location="cpu"))
+
+# v1 (deployed) — checkpoint dict:
+# path = hf_hub_download("hakim78/Cancer_pathos", "models/best_model_epoch50_auc0.9980.pth")
+# model.load_state_dict(torch.load(path, map_location="cpu")["model_state_dict"])
+
+model.eval()
+```
+
+Prediction = `torch.sigmoid(model(x))` (probability of cancer; threshold 0.5). For best results, average over 5 TTA views (original + H/V flip + 90° rotation + transpose).
+
+---
+
+## ⚠️ Limitations
+
+- **Patch-level only** (96×96), not whole-slide. A 1.18 % per-patch false-positive rate aggregates over the tens of thousands of patches in a slide → a **MIL aggregation** step is required for slide-level use.
+- PatchCamelyon originates from a **limited set of centers/scanners** → external multicentric validation and stain normalization are required before any clinical perspective.
+- Calibration is good but shows a slight sigmoid profile (ECE 0.045) → **temperature scaling** recommended before any autonomous use.
+
+---
+
+## 👤 Author
+
+**Hakim Djaalal** — Master's in Big Data & AI. License: MIT (Research Use Only).