README.md

---
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).