Upload GradeEye four-ch-morph checkpoints

README.md

@@ -1,3 +1,56 @@
 ---
 license: cc-by-nc-4.0
+tags:
+  - medical-imaging
+  - diabetic-retinopathy
+  - domain-generalization
+  - pytorch
+pipeline_tag: image-classification
+library_name: pytorch
 ---
+
+# GradeEye four-ch-morph
+
+This repository contains GradeEye CORN ordinal diabetic-retinopathy classifiers using the `convnext_tiny` backbone at 384x384 resolution, with 4-channel input and a 4-threshold ordinal head. The `_ema.safetensors` file is the **primary** artifact: the paper's reported evaluation metrics were generated using the EMA state dict. The unsuffixed `.safetensors` file is the corresponding raw `model_state_dict` secondary artifact.
+
+## Checkpoints
+
+| Primary EMA weights | Raw secondary weights | Architecture | Held-out fold | Best QWK | Epoch |
+|---|---|---|---|---:|---:|
+| `lodo_aptos_convnext_tiny_best_ema.safetensors` | `lodo_aptos_convnext_tiny_best.safetensors` | `convnext_tiny` | varies | 0.7789 | 12 |
+| `lodo_ddr_convnext_tiny_best_ema.safetensors` | `lodo_ddr_convnext_tiny_best.safetensors` | `convnext_tiny` | varies | 0.7702 | 7 |
+| `lodo_eyepacs_convnext_tiny_best_ema.safetensors` | `lodo_eyepacs_convnext_tiny_best.safetensors` | `convnext_tiny` | varies | 0.7833 | 3 |
+| `lodo_messidor2_convnext_tiny_best_ema.safetensors` | `lodo_messidor2_convnext_tiny_best.safetensors` | `convnext_tiny` | varies | 0.7395 | 2 |
+
+## Preprocessing
+
+1. Resize the RGB fundus image to 384x384 using the same offline preprocessing pipeline.
+2. Convert RGB to float in [0,1] and apply ImageNet normalization: mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225).
+3. Append one auxiliary channel in [0,1] after RGB normalization. It is not ImageNet-normalized.
+
+### Fourth-channel construction
+
+- Source pool: `segmentation_pooled_morph`.
+- Producer: `gradeeye/seg-unet-bcedice`.
+- Exact method: The BCE+Dice U-Net raw sigmoid probability map after 3x3 elliptical morphological opening, 3x3 elliptical closing, and Gaussian blur (sigma=0.5). It remains a continuous [0,1] soft-probability map, not a morphological gradient or edge channel.
+- The resulting tensor is `(4, 384, 384)` in channel-first layout.
+- This is the only one of the three published four-channel variants with morphological post-processing; it is not a gradient or edge channel.
+
+## Loading
+
+```python
+import json
+from modeling import load_model
+
+config = json.load(open('config.json'))
+model = load_model('lodo_eyepacs_convnext_tiny_best_ema.safetensors', config)
+# model(x) returns CORN logits with shape (batch, 4)
+```
+
+Install `torch`, `timm`, and `safetensors`, and make the GradeEye source repository available on `PYTHONPATH`.
+
+## Intended use and limitations
+
+These weights are released for research and reproducibility only. They are not validated for clinical diagnosis or treatment decisions. Performance varies substantially by held-out dataset and should not be interpreted as clinical-grade generalization.
+
+Source code and paper materials: [https://github.com/ahmed-farhanur-rashid/gradeeye](https://github.com/ahmed-farhanur-rashid/gradeeye).

config.json

@@ -0,0 +1,49 @@
+{
+  "model_type": "DRGradingModel",
+  "task": "diabetic-retinopathy-grading",
+  "architecture": "convnext_tiny",
+  "backbone_timm_name": "convnext_tiny",
+  "in_channels": 4,
+  "image_size": 384,
+  "num_classes": 5,
+  "ordinal_head": "CORN",
+  "num_thresholds": 4,
+  "use_cbam": true,
+  "cbam_num_stages": 2,
+  "head_hidden_dim": 512,
+  "dropout": 0.4,
+  "channels_last": true,
+  "ema_decay": 0.999,
+  "loss_type": "corn",
+  "use_class_weighting": true,
+  "use_mixup": true,
+  "primary_weights": "*_best_ema.safetensors (EMA; reproduces paper metrics)",
+  "secondary_weights": "*_best.safetensors (raw model_state_dict)",
+  "normalization": {
+    "rgb": {
+      "mean": [
+        0.485,
+        0.456,
+        0.406
+      ],
+      "std": [
+        0.229,
+        0.224,
+        0.225
+      ]
+    },
+    "extra_channel": "Already in [0,1]; appended after RGB normalization; not ImageNet-normalized."
+  },
+  "class_names": [
+    "No DR",
+    "Mild",
+    "Moderate",
+    "Severe",
+    "Proliferative DR"
+  ],
+  "extra_channel": {
+    "source": "segmentation_pooled_morph",
+    "producer": "gradeeye/seg-unet-bcedice",
+    "description": "The BCE+Dice U-Net raw sigmoid probability map after 3x3 elliptical morphological opening, 3x3 elliptical closing, and Gaussian blur (sigma=0.5). It remains a continuous [0,1] soft-probability map, not a morphological gradient or edge channel."
+  }
+}

lodo_aptos_convnext_tiny_best.meta.json

@@ -0,0 +1,38 @@
+{
+  "best_metric": 0.7789129817933231,
+  "checkpoint_source": "saved/checkpoints/four_ch_morph/lodo_aptos_convnext_tiny_best.pt",
+  "class_names": [
+    "No DR",
+    "Mild",
+    "Moderate",
+    "Severe",
+    "Proliferative DR"
+  ],
+  "ema_state_dict_present": true,
+  "epoch": 12,
+  "global_step": 13742,
+  "phase_name": "phase2_full_training",
+  "primary_weights": "lodo_aptos_convnext_tiny_best_ema.safetensors",
+  "primary_weights_kind": "ema",
+  "secondary_weights": "lodo_aptos_convnext_tiny_best.safetensors",
+  "secondary_weights_kind": "raw_model_state_dict",
+  "training_config": {
+    "arch": "convnext_tiny",
+    "cbam_num_stages": 2,
+    "channels_last": true,
+    "dropout": 0.4,
+    "ema_decay": 0.999,
+    "head_hidden_dim": 512,
+    "img_size": 384,
+    "in_chans": 4,
+    "loss_type": "corn",
+    "num_thresholds": 4,
+    "phase_batches": {
+      "phase1_frozen": 64,
+      "phase2_full_training": 24
+    },
+    "use_cbam": true,
+    "use_class_weighting": true,
+    "use_mixup": true
+  }
+}

lodo_aptos_convnext_tiny_best.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b3a79a5c8cc5afec9dad585fd958dc7044acd46ddaf449fbe1703aed558b5c05
+size 113275512

lodo_aptos_convnext_tiny_best_ema.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a53902948ad286ea55ea7ea9eb9ad14981268018c20471fe8f008d5104321c7e
+size 113275512

lodo_ddr_convnext_tiny_best.meta.json

@@ -0,0 +1,38 @@
+{
+  "best_metric": 0.7701556000355464,
+  "checkpoint_source": "saved/checkpoints/four_ch_morph/lodo_ddr_convnext_tiny_best.pt",
+  "class_names": [
+    "No DR",
+    "Mild",
+    "Moderate",
+    "Severe",
+    "Proliferative DR"
+  ],
+  "ema_state_dict_present": true,
+  "epoch": 7,
+  "global_step": 8756,
+  "phase_name": "phase2_full_training",
+  "primary_weights": "lodo_ddr_convnext_tiny_best_ema.safetensors",
+  "primary_weights_kind": "ema",
+  "secondary_weights": "lodo_ddr_convnext_tiny_best.safetensors",
+  "secondary_weights_kind": "raw_model_state_dict",
+  "training_config": {
+    "arch": "convnext_tiny",
+    "cbam_num_stages": 2,
+    "channels_last": true,
+    "dropout": 0.4,
+    "ema_decay": 0.999,
+    "head_hidden_dim": 512,
+    "img_size": 384,
+    "in_chans": 4,
+    "loss_type": "corn",
+    "num_thresholds": 4,
+    "phase_batches": {
+      "phase1_frozen": 64,
+      "phase2_full_training": 24
+    },
+    "use_cbam": true,
+    "use_class_weighting": true,
+    "use_mixup": true
+  }
+}

lodo_ddr_convnext_tiny_best.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ac201739ad9d112366f0c385788035eeff6ae6f4f4b80cb800f156a86c39e2dc
+size 113275512

lodo_ddr_convnext_tiny_best_ema.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:70d5b5ffcf287d5cae291b228d597033cc6d65159b15cfea444ff522cc18b639
+size 113275512

lodo_eyepacs_convnext_tiny_best.meta.json

@@ -0,0 +1,38 @@
+{
+  "best_metric": 0.7832504424849636,
+  "checkpoint_source": "saved/checkpoints/four_ch_morph/lodo_eyepacs_convnext_tiny_best.pt",
+  "class_names": [
+    "No DR",
+    "Mild",
+    "Moderate",
+    "Severe",
+    "Proliferative DR"
+  ],
+  "ema_state_dict_present": true,
+  "epoch": 3,
+  "global_step": 1192,
+  "phase_name": "phase2_full_training",
+  "primary_weights": "lodo_eyepacs_convnext_tiny_best_ema.safetensors",
+  "primary_weights_kind": "ema",
+  "secondary_weights": "lodo_eyepacs_convnext_tiny_best.safetensors",
+  "secondary_weights_kind": "raw_model_state_dict",
+  "training_config": {
+    "arch": "convnext_tiny",
+    "cbam_num_stages": 2,
+    "channels_last": true,
+    "dropout": 0.4,
+    "ema_decay": 0.999,
+    "head_hidden_dim": 512,
+    "img_size": 384,
+    "in_chans": 4,
+    "loss_type": "corn",
+    "num_thresholds": 4,
+    "phase_batches": {
+      "phase1_frozen": 64,
+      "phase2_full_training": 24
+    },
+    "use_cbam": true,
+    "use_class_weighting": true,
+    "use_mixup": true
+  }
+}

lodo_eyepacs_convnext_tiny_best.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:02d454aed62a11bfb7a3a22665806a9bfa91c813698ec3de508c1035d11ccfac
+size 113275512

lodo_eyepacs_convnext_tiny_best_ema.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d5feac6151cda5ec893869c2754066dcf66a4e80071a58fe322d8536815f76d0
+size 113275512

lodo_messidor2_convnext_tiny_best.meta.json

@@ -0,0 +1,38 @@
+{
+  "best_metric": 0.7395453178905533,
+  "checkpoint_source": "saved/checkpoints/four_ch_morph/lodo_messidor2_convnext_tiny_best.pt",
+  "class_names": [
+    "No DR",
+    "Mild",
+    "Moderate",
+    "Severe",
+    "Proliferative DR"
+  ],
+  "ema_state_dict_present": true,
+  "epoch": 2,
+  "global_step": 4789,
+  "phase_name": "phase2_full_training",
+  "primary_weights": "lodo_messidor2_convnext_tiny_best_ema.safetensors",
+  "primary_weights_kind": "ema",
+  "secondary_weights": "lodo_messidor2_convnext_tiny_best.safetensors",
+  "secondary_weights_kind": "raw_model_state_dict",
+  "training_config": {
+    "arch": "convnext_tiny",
+    "cbam_num_stages": 2,
+    "channels_last": true,
+    "dropout": 0.4,
+    "ema_decay": 0.999,
+    "head_hidden_dim": 512,
+    "img_size": 384,
+    "in_chans": 4,
+    "loss_type": "corn",
+    "num_thresholds": 4,
+    "phase_batches": {
+      "phase1_frozen": 64,
+      "phase2_full_training": 24
+    },
+    "use_cbam": true,
+    "use_class_weighting": true,
+    "use_mixup": true
+  }
+}

lodo_messidor2_convnext_tiny_best.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3f0a946bb0ce3e6878c01e51a8e0e9d65c411cb19998ba99c7baf209dfc1b5bb
+size 113275512

lodo_messidor2_convnext_tiny_best_ema.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:10170dc91c2161db9a70059423bf454a0b5490b6e7aac9938f0d23f37d035c5f
+size 113275512

modeling.py

@@ -0,0 +1,44 @@
+"""Minimal GradeEye classifier loader for Hugging Face Hub.
+
+Requires the GradeEye source package on PYTHONPATH plus torch, timm, and
+safetensors. The architecture is the same DRGradingModel used during training.
+EMA files are the primary weights and reproduce the paper evaluation protocol.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+import torch
+
+# For local source checkout usage. Users may instead install the GradeEye package.
+try:
+    from src.models.dr_model import DRGradingModel
+except ImportError as exc:
+    raise ImportError(
+        "Install/clone GradeEye and make its repository root available on PYTHONPATH."
+    ) from exc
+from safetensors.torch import load_file
+
+
+def load_model(weights_path: str | Path, config: dict, device: str = "cpu") -> DRGradingModel:
+    """Instantiate DRGradingModel and strictly load a .safetensors state dict."""
+    model = DRGradingModel(
+        pretrained=False,
+        use_cbam=config["use_cbam"],
+        cbam_num_stages=config["cbam_num_stages"],
+        num_thresholds=config["num_thresholds"],
+        head_hidden_dim=config["head_hidden_dim"],
+        dropout=config["dropout"],
+        output_mode="corn",
+        arch=config["architecture"],
+        in_chans=config["in_channels"],
+        img_size=config["image_size"],
+    )
+    state_dict = load_file(str(weights_path), device="cpu")
+    result = model.load_state_dict(state_dict, strict=True)
+    if result.missing_keys or result.unexpected_keys:
+        raise RuntimeError(
+            f"State-dict mismatch: missing={result.missing_keys}, "
+            f"unexpected={result.unexpected_keys}"
+        )
+    return model.to(device).eval()