Downloads · 30 days
0
FatmaZahraGaida/diabetic-retinopathy-classification-xai
diabetic-retinopathy-classification-xai is a machine learning model from FatmaZahraGaida. Use it for the machine learning task on the model card, and read the license before you ship it in a product.
Diabetic retinopathy (DR) grading on APTOS 2019 fundus photographs with six pretrained backbones, plus explainable-AI (XAI) analysis: Grad-CAM / Grad-CAM++ heatmaps, a cross-model comparison, and a quantitative valida…
Downloads · 30 days
0
Access
Public
Updated Sep 19, 2026
Repo size
1.5 GB
Likes
0
Public
Click a slice to open those files.
.pth1.2 GB · 82%
From the Hugging Face model README
Diabetic retinopathy (DR) grading on APTOS 2019 fundus photographs with six pretrained backbones, plus explainable-AI (XAI) analysis: Grad-CAM / Grad-CAM++ heatmaps, a cross-model comparison, and a quantitative validation of the heatmaps against pixel-level lesion masks from the IDRiD dataset.
Six ImageNet-pretrained timm architectures are fine-tuned with an identical protocol (class-weighted CE, Adam 1e-4, 3 frozen epochs then full fine-tuning, early stopping, checkpoint on best validation QWK, seed 42):
| Model | Family | Params | Grad-CAM target layer |
|---|---|---|---|
| ResNet-50 | CNN | 23.5 M | layer4 |
| DenseNet-121 | CNN | 7.0 M | features.norm5 |
| EfficientNet-B3 | CNN | 10.7 M | bn2 |
| ViT-Base/16 | Transformer | 86.4 M | blocks.11.norm1 |
| DeiT-Base/16 (distilled) | Transformer | 86.4 M | blocks.11.norm1 |
| Swin-Base (patch 4, window 7) | Hierarchical transformer | 86.7 M | layers.3.blocks.1.norm1 |
The workflow is:
| Document | Content |
|---|---|
| METHODOLOGY_AND_RESULTS.md | preprocessing choices, training protocol, evaluation metrics, full APTOS results tables (global, per-class, referable DR) and model comparison |
| IDRID_VALIDATION.md | protocol, metric definition (IoU at a fixed cut-off and best IoU over a threshold sweep, per lesion type and mIoU), results and discussion of the Grad-CAM++ vs IDRiD lesion-mask validation, including the Swin target-layer analysis |
DR Grading XAI/
├── app/ # Streamlit demo (see below)
│ ├── app.py # Streamlit interface only
│ ├── config.py # Model registry (backbone, cam_layer, checkpoint), class names
│ ├── gradcam.py # Grad-CAM and Grad-CAM++ engine
│ ├── models.py # timm construction, checkpoint loading, classification
│ ├── pipeline.py # image -> prediction + attribution maps
│ ├── preprocessing.py # FOV crop, 512x512 resize, [-1, 1] normalisation
│ ├── styles.css # custom CSS for the Streamlit UI
│ └── requirements.txt # runtime dependencies of the demo
├── .streamlit/
│ └── config.toml # dark theme, 50 MB upload limit
├── checkpoints/ # fine-tuned weights (one per model)
│ ├── deit_base16.pth
│ ├── densenet121.pth
│ ├── efficientnet_b3.pth
│ ├── resnet50.pth
│ ├── swin_base_patch4_window7_224_s42.pth
│ └── vit_base16.pth
├── data/ # datasets, git-ignored (download separately, see "Data")
│ └── IDRiD/
│ └── A. Segmentation/ # used only for heatmap validation, never for training
├── data_preprocessing/
│ └── preprocessing-aptos-2019.ipynb
├── models_notebooks/ # one training/evaluation notebook per backbone
│ ├── deit-base-16.ipynb
│ ├── densenet-121.ipynb
│ ├── efficientnet-b3.ipynb
│ ├── resnet-50.ipynb
│ ├── swin-base.ipynb
│ └── vit-base-16.ipynb
├── results/
│ ├── figures/
│ │ ├── deit_base16/ # per model: cam_correct, cam_per_class, cam_errors,
│ │ ├── densenet121/ # confusion_matrix, roc_curve, training_curves
│ │ ├── efficientnet_b3/
│ │ ├── resnet50/
│ │ ├── swin_base_patch4_window7_224/
│ │ ├── vit_base16/
│ │ ├── comparison/ # generated by `gradcampp_comparison.py compare`
│ │ └── idrid_validation/ # generated by `gradcampp_comparison.py idrid`
│ │ ├── idrid_gradcampp_p1.png ... p5.png
│ │ ├── per_image_metrics.csv
│ │ ├── summary.csv
│ │ ├── summary.png
│ │ ├── swin_alt_layer_metrics.csv
│ │ └── cams/ # cached Grad-CAM++ maps, cams_<model>.npz
│ └── metrics/ # test-set metrics per model (JSON)
│ ├── deit_base16_metrics.json
│ ├── densenet121_metrics.json
│ ├── efficientnet_b3_metrics.json
│ ├── Resnet50_metrics.json
│ ├── swin_metrics.json
│ └── vit_base16_metrics.json
├── gradcampp_comparison.py # cross-model Grad-CAM++ grid + IDRiD lesion validation
├── upload.py # pushes the repo to the Hugging Face Hub
├── IDRID_VALIDATION.md
├── METHODOLOGY_AND_RESULTS.md
├── README.md
└── .gitignore # ignores data/, .cache/, __pycache__/
The app/ folder contains a Streamlit interface that loads the checkpoints,
classifies an uploaded fundus photograph and shows Grad-CAM and Grad-CAM++
explanations for the chosen model. The theme is set in .streamlit/config.toml
and the extra styling in app/styles.css.
pip install -r app/requirements.txt
streamlit run app/app.py
| File | Role |
|---|---|
app/app.py | Streamlit interface only |
app/gradcam.py | Grad-CAM and Grad-CAM++ (same maths as the notebooks) |
app/models.py | timm construction, checkpoint loading, classification |
app/preprocessing.py | FOV crop, 512x512 resize, [-1, 1] normalisation |
app/pipeline.py | Glue: image -> prediction + attribution maps |
app/config.py | Model registry (backbone, cam_layer, ckpt_file, metrics_file), class names, constants |
app/styles.css | Custom CSS injected into the Streamlit page |
gradcampp_comparison.py reuses the app/ package (same preprocessing,
checkpoints and Grad-CAM++ engine) and has two sub-commands. It needs
app/requirements.txt plus matplotlib.
Options shared by both commands:
| Option | Meaning |
|---|---|
--models | comma-separated model keys (default: every checkpoint present in checkpoints/) |
--n | number of images (default 8) |
--device | cuda / cpu (default: auto) |
--reuse | reuse the cached Grad-CAM++ maps in <out>/cams/ and only redo metrics and figures |
compare — all models side by side on the same imagesThe per-model figures in results/figures/<model>/ use different samples, so
they cannot be compared directly. This command runs every model on the same
APTOS images:
python gradcampp_comparison.py compare --images path/to/aptos/test_images \
--labels path/to/test.csv --n 8 # --labels is optional (id_code,diagnosis)
Writes results/figures/comparison/gradcampp_comparison_p*.png (one row per
image, one column per model, titles green/red when the true grade is known)
and predictions.csv.
idrid — heatmaps vs IDRiD ground-truth lesionsIDRiD (segmentation subset, 81 images with pixel masks for microaneurysms, haemorrhages, hard and soft exudates, and the optic disc) is never used for training — only to check whether the attribution lands on real lesions.
# official run: full test split (27 images, IDRiD_55–81), all six checkpoints
python gradcampp_comparison.py idrid --root "data/IDRiD/A. Segmentation" --split test --n 27
# redo metrics / figures from the cached maps without re-running the models
python gradcampp_comparison.py idrid --root "data/IDRiD/A. Segmentation" --split test --n 27 --reuse
--split is train, test or all (default all). Masks go through the
same FOV crop and 512x512 resize as the image, so they stay aligned with the
heatmap. The explained class is the model's predicted grade. Outputs in
results/figures/idrid_validation/:
| File | Content |
|---|---|
idrid_gradcampp_p*.png | fundus, colour-coded lesion masks (MA red, HE orange, EX yellow, SE green), then one Grad-CAM++ panel per model with lesion contours (white) and optic disc (black) |
per_image_metrics.csv | per image x model x region: iou (IoU between the map binarised at 0.5 and the region), iou_best (best IoU over a cut-off sweep 0.05–0.95), best_thr (the cut-off that reached it) |
summary.csv, summary.png | mean IoU per model and region plus an mIoU row (mean over the four lesion types); the optic disc (OD) row is a distractor the models should not fire on |
swin_alt_layer_metrics.csv | the same metrics for Swin-Base hooked one block earlier (layers.3.blocks.0.norm1) |
cams/cams_<model>.npz | cached Grad-CAM++ maps, reused with --reuse |
Both commands load one model at a time, so they run on CPU (a few seconds per image and model; the full IDRiD test split takes about 15 min).
Metric = IoU between the binarised Grad-CAM++ map and the lesion mask, best
cut-off per image (iou_best). ALL is the union of the four lesion types;
mIoU the mean over MA / HE / EX / SE; OD is the optic disc, which is not
a lesion.
| Model | Any lesion (mean / median) | Hard exudates | mIoU | Optic disc | images with IoU > 0.10 |
|---|---|---|---|---|---|
| DenseNet-121 | 0.145 / 0.149 | 0.072 | 0.055 | 0.170 | 17 / 27 |
| DeiT-Base/16 | 0.129 / 0.111 | 0.095 | 0.053 | 0.060 | 14 / 27 |
| ResNet-50 | 0.122 / 0.111 | 0.069 | 0.047 | 0.024 | 14 / 27 |
| EfficientNet-B3 | 0.066 / 0.048 | 0.043 | 0.029 | 0.185 | 5 / 27 |
| ViT-Base/16 | 0.052 / 0.029 | 0.035 | 0.018 | 0.041 | 4 / 27 |
Swin-Base (layers.3.blocks.1.norm1, notebook layer) | 0.010 / 0.009 | 0.005 | 0.003 | 0.046 | 0 / 27 |
Swin-Base (layers.3.blocks.0.norm1, one block earlier) | 0.126 / 0.106 | 0.085 | 0.052 | 0.106 | 16 / 27 |
Key findings:
Full protocol, metric definitions, discussion and limitations: IDRID_VALIDATION.md.
The preprocessing notebook data_preprocessing/preprocessing-aptos-2019.ipynb
is designed for the APTOS 2019 Blindness Detection
dataset (3662 images, 5 grades). It performs FOV detection and crop, a direct
512x512 INTER_AREA resize (no padding), lossless PNG export and a stratified
train / val / test split (2930 / 366 / 366, seed 42). The same steps are
ported to app/preprocessing.py.
The Indian Diabetic Retinopathy Image Dataset
(CC-BY-4.0) segmentation subset provides 81 images with pixel-level masks for
microaneurysms, haemorrhages, hard exudates, soft exudates and the optic disc.
Place it under data/IDRiD/ so that --root points at the folder containing
1. Original Images/ and 2. All Segmentation Groundtruths/:
data/IDRiD/A. Segmentation/
├── 1. Original Images/
│ ├── a. Training Set/ # IDRiD_01 – IDRiD_54
│ └── b. Testing Set/ # IDRiD_55 – IDRiD_81 (used in the report)
└── 2. All Segmentation Groundtruths/
├── a. Training Set/
└── b. Testing Set/
├── 1. Microaneurysms/ 2. Haemorrhages/ 3. Hard Exudates/
└── 4. Soft Exudates/ 5. Optic Disc/
The data/ folder is git-ignored and is never uploaded to the Hub.
Python 3.10 or newer is recommended.
# demo + comparison / validation script
pip install -r app/requirements.txt
pip install matplotlib
# notebooks (training, evaluation, figures)
pip install torch torchvision torchaudio
pip install timm scikit-learn pandas numpy matplotlib seaborn
pip install opencv-python pillow jupyter
# optional
pip install grad-cam captum albumentations
# publishing to the Hugging Face Hub (upload.py)
pip install huggingface_hub
data_preprocessing/preprocessing-aptos-2019.ipynb to prepare the APTOS dataset.models_notebooks/ for the architecture you want to train or evaluate.checkpoints/.results/metrics/ and the figures under results/figures/<model>/.gradcampp_comparison.py compare to see all models on the same images.gradcampp_comparison.py idrid --split test --n 27 to validate the heatmaps against lesion masks.Fine-tuned weights for the six models are stored in checkpoints/. Each one is
registered in app/config.py (ModelSpec: timm backbone, Grad-CAM target
layer, checkpoint and metrics file names) and is loaded by the demo, the
comparison script and the IDRiD validation.
Test-set metrics (n = 366, checkpoint chosen on validation QWK) are saved as
JSON under results/metrics/ with per-class metrics, referable-DR metrics,
confusion matrix and bootstrap 95 % CI (2000 resamples). Figures per model in
results/figures/<model>/: training_curves.png, confusion_matrix.png,
roc_curve.png, cam_correct.png, cam_per_class.png, cam_errors.png.
| Model | QWK [95 % CI] | Accuracy | Macro-F1 | AUC (OvR macro) | Referable-DR sensitivity |
|---|---|---|---|---|---|
| DeiT-Base/16 | 0.905 [0.875–0.929] | 0.792 | 0.647 | 0.951 | 0.968 |
| ResNet-50 | 0.896 [0.857–0.927] | 0.817 | 0.694 | 0.948 | 0.951 |
| Swin-Base | 0.895 [0.865–0.919] | 0.738 | 0.580 | 0.942 | 0.995 |
| DenseNet-121 | 0.893 [0.856–0.925] | 0.822 | 0.681 | 0.944 | 0.973 |
| EfficientNet-B3 | 0.890 [0.846–0.927] | 0.836 | 0.688 | 0.936 | 0.968 |
| ViT-Base/16 | 0.822 [0.781–0.860] | 0.678 | 0.516 | 0.885 | 0.935 |
The confidence intervals of the top five overlap almost entirely; only ViT-Base/16 is clearly worse. Per-class F1, referable-DR tables and the full comparison: METHODOLOGY_AND_RESULTS.md.
upload.py pushes the repository to
FatmaZahraGaida/diabetic-retinopathy-classification-xai in two stages: the
small files (app/, metrics, docs) with upload_large_folder, then the
multi-MB files (notebooks, figures, checkpoints) one commit at a time through
LFS so uploads survive a slow connection. data/, .cache/, .claude/ and
__pycache__/ are excluded. Already-uploaded files are skipped, so the script
can be re-run.
huggingface-cli login
python upload.py
app/ and gradcampp_comparison.py.This project does not currently include a specified license file. If you plan to share or publish this repository, add an appropriate license before distribution. IDRiD is distributed under CC-BY-4.0; APTOS 2019 is subject to the Kaggle competition rules.