Deploy CardioScan inference 2026-04-23T12:22:25Z

.gitattributes

@@ -1,35 +1,4 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.pt  filter=lfs diff=lfs merge=lfs -text
 *.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
 *.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,68 @@
+# syntax=docker/dockerfile:1
+#
+# Hugging Face Spaces (Docker SDK) image for the CardioScan inference server.
+#
+# Spaces conventions:
+#   * Container must listen on the port declared in `README.md` (`app_port`).
+#   * Container is started as user `user` (UID 1000), not root.
+#   * /data is the only writable location persisted across restarts (we don't
+#     need persistence — checkpoints ship inside the image).
+#
+# Build context expected by `scripts/deploy-space.sh`:
+#   /
+#   ├── Dockerfile                       (this file)
+#   ├── README.md                        (HF Spaces metadata)
+#   ├── inference_server/                (FastAPI app + requirements.txt)
+#   └── model_training/
+#       ├── src/                         (only the package; notebooks excluded)
+#       └── notebooks/results/           (.pth checkpoints + manifest + metrics)
+
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    HF_HOME=/app/.cache/huggingface \
+    TORCH_HOME=/app/.cache/torch \
+    XDG_CACHE_HOME=/app/.cache
+
+# System deps for Pillow / scientific Python wheels.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        libgomp1 \
+        ca-certificates \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# HF Spaces requires the runtime user to be UID 1000.
+RUN useradd --create-home --uid 1000 user
+WORKDIR /app
+
+# Install Python deps first so layer caches when only code/weights change.
+COPY --chown=user:user inference_server/requirements.txt /app/inference_server/requirements.txt
+RUN pip install --upgrade pip && \
+    pip install --extra-index-url https://download.pytorch.org/whl/cpu \
+        torch==2.4.1 torchvision==0.19.1 && \
+    pip install -r /app/inference_server/requirements.txt
+
+# Copy the actual code and weights.
+COPY --chown=user:user inference_server/      /app/inference_server/
+COPY --chown=user:user model_training/src/    /app/model_training/src/
+COPY --chown=user:user model_training/notebooks/results/ /app/model_training/notebooks/results/
+
+# Pre-create writable cache dirs owned by `user`.
+RUN mkdir -p /app/.cache/torch /app/.cache/huggingface && chown -R user:user /app
+
+USER user
+
+# Spaces routes traffic to whatever app_port we declared in README.md (7860).
+ENV PORT=7860 \
+    LOG_LEVEL=INFO \
+    MODEL_USE_TTA=true \
+    ALLOWED_ORIGIN_REGEX="https://([a-z0-9-]+\\.)*lovable\\.app|https://([a-z0-9-]+\\.)*lovableproject\\.com|https://([a-z0-9-]+\\.)*hf\\.space|http://localhost(:\\d+)?|http://127\\.0\\.0\\.1(:\\d+)?"
+
+EXPOSE 7860
+
+# server.py expects to be importable from /app/inference_server.
+WORKDIR /app/inference_server
+CMD ["sh", "-c", "uvicorn server:app --host 0.0.0.0 --port ${PORT}"]

README.md

@@ -1,12 +1,42 @@
 ---
-title: Cardio Scan Api
-emoji: 🐢
-colorFrom: indigo
-colorTo: yellow
-sdk: gradio
-sdk_version: 6.13.0
-app_file: app.py
+title: CardioScan Inference
+emoji: 🫀
+colorFrom: red
+colorTo: pink
+sdk: docker
+app_port: 7860
 pinned: false
+license: mit
+short_description: Cardiomegaly screening API for the CardioScan frontend.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# CardioScan Inference
+
+FastAPI service that serves the chest X-ray cardiomegaly ensemble trained in
+[heart-scan-helper](https://github.com/) — a torchxrayvision DenseNet-121
+3-seed ensemble with optional 6-pass test-time augmentation.
+
+## Endpoints
+
+- `GET  /health`  — readiness + model metadata
+- `POST /predict`  — `multipart/form-data`, field name `image`
+- `POST /debug/predict`  — per-model, per-TTA logits (debugging)
+
+Response shape:
+
+```json
+{
+  "prediction": "Cardiomegaly",
+  "confidence": 0.873,
+  "heatmap_url": null,
+  "source": "model",
+  "threshold": 0.504486,
+  "ensemble_size": 3,
+  "use_tta": true
+}
+```
+
+## Environment
+
+CORS already allows `*.lovable.app`, `*.lovableproject.com`, `*.hf.space` and
+`localhost`. Override with `ALLOWED_ORIGIN_REGEX` if you need to lock it down.

inference_server/README.md

@@ -0,0 +1,218 @@
+# inference_server
+
+FastAPI service that wraps the **trained ensemble** in
+`model_training/notebooks/results/` and exposes a single `POST /predict`
+endpoint for the React frontend.
+
+This folder is strictly an inference layer — **nothing inside
+`model_training/` is modified**. We only import `src.model.build_model` and
+`src.model.cardio_logit` to recreate the architecture before loading the
+saved state dicts.
+
+## 1. Install
+
+```bash
+cd inference_server
+python -m venv .venv
+source .venv/bin/activate     # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+> The backbone is **auto-detected from the first checkpoint** referenced by
+> `ensemble_manifest.csv`, so there is never a mismatch between
+> architecture and weights. The shipped checkpoints in
+> `model_training/notebooks/results/` are `torchxrayvision densenet121`
+> (trained before `CFG.backbone` in `model_training/src/config.py` was
+> changed to `efficientnet_b0`); the server correctly identifies and
+> uses them. You can still force a specific backbone via `MODEL_BACKBONE`
+> if you train a new model — see _Configuration_ below.
+
+## 2. Run
+
+**You must use the venv** where `pip install -r requirements.txt` was run. If
+you see `ModuleNotFoundError: No module named 'torch'`, you started `uvicorn`
+with the system Python instead of `inference_server/.venv`.
+
+```bash
+cd inference_server
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+uvicorn server:app --host 0.0.0.0 --port 8000
+```
+
+Or, without activating (always uses the project interpreter):
+
+```bash
+cd inference_server
+./.venv/bin/uvicorn server:app --host 0.0.0.0 --port 8000
+```
+
+If port 8000 is still taken, use **8001** (or any free port) and point the
+frontend at the same port:
+
+```bash
+PORT=8001 ./run.sh
+# in project root .env:
+# VITE_PREDICT_API_URL=http://127.0.0.1:8001
+```
+
+If your shell prompt already shows `inference_server` in the path, you are
+**inside** that folder—do not run `cd inference_server` again (you will get
+`no such file`).
+
+**`[Errno 48] address already in use` on port 8000** means something else is
+already bound there (usually an older uvicorn you forgot to stop). On macOS:
+
+```bash
+lsof -i :8000
+# note the PID in the second column, then:
+kill <PID>
+# if it does not exit:
+kill -9 <PID>
+```
+
+Then start uvicorn again. To use another port without killing the other process
+(e.g. 8001), add `--port 8001` and set `VITE_PREDICT_API_URL` in the frontend
+`.env` to match.
+
+> **IPv4/IPv6 gotcha.** Bind with `--host 0.0.0.0` (not `127.0.0.1`). On
+> macOS, browsers often resolve `localhost` to IPv6 `::1` first, and
+> `uvicorn --host 127.0.0.1` only listens on IPv4, which surfaces in the
+> browser as a bare `Network Error` even though `curl 127.0.0.1:8000` works.
+> The frontend's `.env` uses `http://127.0.0.1:8000` (not `localhost`) for
+> the same reason.
+
+On startup the server will:
+
+1. Read `model_training/notebooks/results/ensemble_manifest.csv`.
+2. For each row, rebuild the EfficientNet-B0 architecture and load the
+   corresponding `model_seed*.pth` checkpoint.
+3. Move every model to CUDA / MPS / CPU (auto-detected).
+
+If the manifest is missing it falls back to
+`model_training/notebooks/results/best_model.pth`.
+
+## 3. Frontend wiring
+
+The app's `.env` already points at this server:
+
+```
+VITE_PREDICT_API_URL=http://localhost:8000
+```
+
+`src/services/predict.ts` posts the uploaded file to `/predict` as
+`multipart/form-data` (field name: `image`). The response shape is exactly
+what the frontend expects:
+
+```json
+{
+  "prediction": "Cardiomegaly",
+  "confidence": 0.873,
+  "heatmap_url": null,
+  "source": "model",
+  "threshold": 0.504486,
+  "ensemble_size": 3,
+  "use_tta": true
+}
+```
+
+The frontend uses `source: "model"` to render a green "Real model" badge on
+each result card, so there is no ambiguity about whether a prediction came
+from the real trained ensemble.
+
+## 4. Configuration (env vars)
+
+| Variable           | Default                | Purpose                                                  |
+| ------------------ | ---------------------- | -------------------------------------------------------- |
+| `MODEL_BACKBONE`   | `CFG.backbone`         | Must match the architecture used for training            |
+| `MODEL_IMG_SIZE`   | `CFG.img_size`         | Must match training (224 for EfficientNet-B0, 518 for RAD-DINO) |
+| `MODEL_THRESHOLD`  | `val_metrics_final.json::threshold` (fallback `0.5`) | Cut-off used when choosing the label string |
+| `MODEL_USE_TTA`    | `true`                 | `true` → run the 6-pass TTA used at training evaluation time |
+| `ALLOWED_ORIGINS`  | localhost dev origins  | Comma-separated CORS origins (exact match)               |
+| `ALLOWED_ORIGIN_REGEX` | _(unset)_          | Regex for origins, e.g. `https://.*\.lovable\.app` for Lovable preview URLs |
+| `LOG_LEVEL`        | `INFO`                 | Standard Python logging level                            |
+
+Example:
+
+```bash
+MODEL_USE_TTA=true MODEL_THRESHOLD=0.504 uvicorn server:app --port 8000
+```
+
+## 5. Smoke-test
+
+```bash
+curl -s http://localhost:8000/health | jq .
+curl -s -X POST -F "image=@/path/to/xray.png" http://localhost:8000/predict | jq .
+
+# Full transparency: per-model + per-TTA raw logits so you can compare
+# against val_predictions.csv / test_predictions.csv in the notebook:
+curl -s -X POST -F "image=@/path/to/xray.png" http://localhost:8000/debug/predict | jq .
+```
+
+Every `/predict` call is also logged in the server terminal with the
+filename, per-model mean logits, and the final probability — useful to
+confirm the frontend is actually hitting the server.
+
+## 6. Deploying to production (Lovable + separate inference host)
+
+Lovable hosts the React frontend, but it cannot run this Python server.
+You need a separate Python host for the inference server. In all cases the
+steps are the same:
+
+1. **Push this repo** (including `model_training/notebooks/results/*.pth`)
+   to the chosen host. The whole monorepo is self-contained.
+2. **Start command** (the host's "start" or "web" command):
+   ```bash
+   uvicorn server:app --host 0.0.0.0 --port $PORT --app-dir inference_server
+   ```
+   Most PaaS hosts inject `PORT`; if yours doesn't, use `8000`.
+3. **Requirements**: point the host at `inference_server/requirements.txt`.
+4. **Set env vars on the inference host**:
+   ```
+   ALLOWED_ORIGINS=https://your-app.lovable.app,https://your-custom-domain.com
+   # Or, if Lovable assigns preview URLs with a hash prefix:
+   ALLOWED_ORIGIN_REGEX=https://.*\.lovable\.app
+   MODEL_USE_TTA=true
+   ```
+5. **Set env var on Lovable (frontend)**:
+   ```
+   VITE_PREDICT_API_URL=https://your-inference-server-url
+   ```
+   Then redeploy the Lovable frontend so Vite bakes the new URL into the
+   bundle.
+
+### Suggested hosts
+
+| Host | Free tier | Notes |
+| ---- | --------- | ----- |
+| **Hugging Face Spaces** | 2 vCPU / 16 GB, always-on free | Ideal for this model. Create a Space with the "FastAPI" SDK, push the repo, and point it at `inference_server/server.py`. |
+| **Render.com** | Web service, spins down after 15 min idle | Simple Git-push deploy. Cold start ~30 s while weights load. |
+| **Fly.io** | Shared-CPU 256 MB free | Docker-based. Dockerfile is trivial (Python base → pip install → CMD uvicorn). |
+| **Railway / Modal** | Paid / pay-per-second | Always-on, fastest DX. |
+
+### Keep model checkpoints in Git LFS (optional)
+
+`model_training/notebooks/results/model_seed*.pth` are ~30 MB each. On
+GitHub free plans this is fine, but you may want to move them to Git LFS
+to keep repo clones small.
+
+## 7. Notes
+
+- The ensemble is loaded once at startup (one-time cost of a few seconds).
+- **Auto-detection**: the server inspects the first checkpoint on startup and
+  picks the matching backbone (`densenet121`, `efficientnet_b0`,
+  `mobilenet_v3_large`, or `rad-dino`). No `CFG` / env-var bookkeeping required.
+- **Correct preprocessing per backbone**: the server delegates to
+  `model_training/src/dataset.py::get_normalize_fn` so the normalization
+  matches training exactly — `xrv_normalize_np` (grayscale, [-1024, 1024]) for
+  torchxrayvision DenseNet-121, `imagenet_normalize_np` (3-channel) for every
+  other backbone.
+- **No pretrained-weight downloads**: torchvision and torchxrayvision
+  constructors are monkey-patched so they skip their pretrained-weight
+  download entirely — our trained checkpoint fully overwrites those weights
+  anyway. This means the server works offline and in sandboxed environments.
+- **Fail-fast checkpoint loading**: if `state_dict` keys don't match the
+  architecture, startup aborts with a clear error listing the mismatch.
+- Each request is ~50–150 ms on CPU without TTA (3 × DenseNet-121 forward
+  passes). With `MODEL_USE_TTA=true` that becomes ~0.5–1.5 s per image.
+- **Verified**: the server reproduces `notebooks/results/val_predictions.csv`
+  probabilities to 6 decimal places (zero delta) on the validation set.

inference_server/requirements.txt

@@ -0,0 +1,17 @@
+# FastAPI + ASGI server
+fastapi>=0.110
+uvicorn[standard]>=0.27
+python-multipart>=0.0.9
+
+# ML stack (must match `model_training/requirements.txt` so state-dict loads cleanly)
+torch>=2.1.0
+torchvision>=0.16.0
+numpy>=1.24
+pandas>=2.0
+pillow>=9.0
+
+# `model_training/src/model.py` imports this at module level
+torchxrayvision>=1.2.0
+
+# Needed only if MODEL_BACKBONE=rad-dino; harmless otherwise
+transformers>=4.40.0

inference_server/run.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Run the API with the project venv (avoids: ModuleNotFoundError: No module named 'torch')
+set -euo pipefail
+cd "$(dirname "$0")"
+if [[ ! -d .venv ]]; then
+  echo "No .venv here. First run: python3 -m venv .venv && .venv/bin/pip install -r requirements.txt" >&2
+  exit 1
+fi
+PORT="${PORT:-8000}"
+exec .venv/bin/uvicorn server:app --host 0.0.0.0 --port "$PORT" "$@"

inference_server/server.py

@@ -0,0 +1,493 @@
+"""FastAPI inference server for the Cardiomegaly classifier.
+
+Loads the multi-seed ensemble trained in ``model_training/`` and exposes a
+single ``POST /predict`` endpoint that the frontend (`src/services/predict.ts`)
+already knows how to consume.
+
+Nothing inside ``model_training/`` is modified — we only *import* the model
+factory (``src.model.build_model``) to rebuild the exact architecture that was
+saved to disk, then load the weights on top.
+
+Run locally
+-----------
+    cd inference_server
+    pip install -r requirements.txt
+    uvicorn server:app --host 0.0.0.0 --port 8000
+
+Environment overrides (optional)
+--------------------------------
+    MODEL_BACKBONE        default: CFG.backbone   (e.g. "efficientnet_b0")
+    MODEL_IMG_SIZE        default: CFG.img_size   (e.g. 224)
+    MODEL_THRESHOLD       default: 0.5            (binary cut-off for the label)
+    MODEL_USE_TTA         default: "false"        ("true" → 6-pass TTA per image)
+    ALLOWED_ORIGINS       comma-separated CORS origins (exact match)
+    ALLOWED_ORIGIN_REGEX  regex origin whitelist (e.g. Lovable preview URLs:
+                          "https://.*\\.lovable\\.app")
+    LOG_LEVEL             default: INFO
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import List
+
+import numpy as np
+import pandas as pd
+import torch
+import torch.nn as nn
+import torchvision.transforms as T
+from fastapi import FastAPI, File, HTTPException, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from PIL import Image
+
+# ---------------------------------------------------------------------------
+# Paths — make `from src.model import ...` resolvable without touching
+# `model_training/`. We prepend the training directory to sys.path so its
+# internal `from src.config import CFG` style imports keep working.
+# ---------------------------------------------------------------------------
+REPO_ROOT = Path(__file__).resolve().parent.parent
+TRAINING_DIR = REPO_ROOT / "model_training"
+NOTEBOOKS_DIR = TRAINING_DIR / "notebooks"
+RESULTS_DIR = NOTEBOOKS_DIR / "results"
+
+if str(TRAINING_DIR) not in sys.path:
+    sys.path.insert(0, str(TRAINING_DIR))
+
+# Point torch's hub cache to a writable in-project location so the server
+# works in sandboxed environments where ``~/.cache`` is read-only. Setting
+# this BEFORE importing torchvision is critical.
+os.environ.setdefault("TORCH_HOME", str(REPO_ROOT / ".torch-cache"))
+
+# `build_model` in ``model_training/src/model.py`` constructs torchvision or
+# torchxrayvision backbones WITH their pretrained weights. Those weights are
+# irrelevant at inference time because we immediately overwrite them with the
+# trained checkpoint from ``model_training/notebooks/results/``. We monkey-
+# patch the constructors so the server skips every pretrained-weight
+# download. This avoids needless bandwidth AND cache-dir permission errors
+# when running in sandboxed environments.
+import torchvision.models as _tvm  # noqa: E402  pylint: disable=wrong-import-position
+import torchxrayvision as _xrv  # noqa: E402  pylint: disable=wrong-import-position
+
+for _fn_name in ("efficientnet_b0", "efficientnet_b3", "mobilenet_v3_large"):
+    _orig = getattr(_tvm, _fn_name, None)
+    if _orig is None:
+        continue
+
+    def _no_download_builder(*args, __orig=_orig, **kwargs):
+        kwargs["weights"] = None
+        return __orig(*args, **kwargs)
+
+    setattr(_tvm, _fn_name, _no_download_builder)
+
+# torchxrayvision DenseNet also attempts a download when weights="..." is set.
+# We wrap its __init__ so the caller's weights argument is remembered, but
+# the actual download is skipped. We still restore the canonical label list
+# (``self.pathologies`` / ``self.targets``) that downstream code in
+# ``model_training/src/model.py::cardio_logit`` relies on to locate the
+# Cardiomegaly output index.
+_orig_xrv_densenet_init = _xrv.models.DenseNet.__init__
+
+
+def _xrv_densenet_init_no_download(self, *args, **kwargs):
+    requested_weights = kwargs.get("weights")
+    kwargs["weights"] = None
+    _orig_xrv_densenet_init(self, *args, **kwargs)
+    if requested_weights and requested_weights in _xrv.models.model_urls:
+        labels = _xrv.models.model_urls[requested_weights]["labels"]
+        self.targets = labels
+        self.pathologies = labels
+
+
+_xrv.models.DenseNet.__init__ = _xrv_densenet_init_no_download
+
+from src.config import CFG  # noqa: E402  pylint: disable=wrong-import-position
+from src.model import build_model, cardio_logit  # noqa: E402  pylint: disable=wrong-import-position
+from src.dataset import get_normalize_fn  # noqa: E402  pylint: disable=wrong-import-position
+
+
+def _detect_backbone_from_checkpoint(ckpt_path: Path) -> str:
+    """Inspect a saved state_dict and guess which backbone produced it.
+
+    Rules:
+      * torchxrayvision DenseNet-121  → has ``features.denseblockN.*`` keys
+      * torchvision EfficientNet      → top-level ``features.0.0.weight`` (stem conv)
+                                        and depth ≥ 9 feature groups
+      * torchvision MobileNetV3-Large → ``features.0.0.weight`` with depth ~17
+      * microsoft/rad-dino            → keys under ``features.embeddings`` /
+                                        ``features.encoder.layer.``
+    Defaults to ``CFG.backbone`` if no signature matches.
+    """
+    state = torch.load(ckpt_path, map_location="cpu", weights_only=True)
+    if isinstance(state, dict) and "state_dict" in state:
+        state = state["state_dict"]
+    keys = list(state.keys())
+
+    if any("denseblock" in k for k in keys):
+        return "densenet121"
+    if any(k.startswith("features.embeddings.") for k in keys) or any(
+        k.startswith("features.encoder.layer.") for k in keys
+    ):
+        return "rad-dino"
+    # torchvision feature indices
+    feature_indices = {
+        int(k.split(".")[1])
+        for k in keys
+        if k.startswith("features.") and k.split(".")[1].isdigit()
+    }
+    if feature_indices:
+        # EfficientNet-B0 has 9 groups (features.0 … features.8)
+        # MobileNetV3-Large has 17 groups (features.0 … features.16)
+        if max(feature_indices) >= 12:
+            return "mobilenet_v3_large"
+        if max(feature_indices) >= 7:
+            return "efficientnet_b0"
+    return CFG.backbone
+
+
+# ---------------------------------------------------------------------------
+# Backbone + image size: auto-detected from the checkpoint so the server never
+# runs with a mismatched architecture. Can still be forced via env vars.
+# ---------------------------------------------------------------------------
+def _first_checkpoint_path() -> Path:
+    manifest = RESULTS_DIR / "ensemble_manifest.csv"
+    if manifest.exists():
+        df = pd.read_csv(manifest)
+        first = df["checkpoint"].iloc[0]
+        p = Path(first)
+        if p.is_absolute() and p.exists():
+            return p
+        for candidate in (NOTEBOOKS_DIR / first, RESULTS_DIR / Path(first).name):
+            if candidate.exists():
+                return candidate
+    fallback = RESULTS_DIR / "best_model.pth"
+    if fallback.exists():
+        return fallback
+    raise FileNotFoundError("No checkpoints found under model_training/notebooks/results/")
+
+
+_DETECTED_BACKBONE = _detect_backbone_from_checkpoint(_first_checkpoint_path())
+# DenseNet-121 (torchxrayvision) is trained on 224x224; ViT-B/14 needs 518.
+_DEFAULT_IMG_SIZE = 518 if _DETECTED_BACKBONE == "rad-dino" else 224
+
+BACKBONE: str = os.environ.get("MODEL_BACKBONE", _DETECTED_BACKBONE)
+IMG_SIZE: int = int(os.environ.get("MODEL_IMG_SIZE", str(_DEFAULT_IMG_SIZE)))
+USE_TTA: bool = os.environ.get("MODEL_USE_TTA", "true").lower() in {"1", "true", "yes"}
+
+
+def _default_threshold() -> float:
+    """Use the training-selected threshold when available."""
+    metrics_path = RESULTS_DIR / "val_metrics_final.json"
+    if metrics_path.exists():
+        try:
+            import json
+
+            with open(metrics_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            thr = float(data.get("threshold", 0.5))
+            if 0.0 <= thr <= 1.0:
+                return thr
+        except Exception:  # noqa: BLE001
+            pass
+    return 0.5
+
+
+DECISION_THRESHOLD: float = float(os.environ.get("MODEL_THRESHOLD", str(_default_threshold())))
+
+_DEFAULT_ORIGINS = (
+    "http://localhost:3000,"
+    "http://localhost:5173,"
+    "http://localhost:8080,"
+    "http://127.0.0.1:3000,"
+    "http://127.0.0.1:5173,"
+    "http://127.0.0.1:8080"
+)
+ALLOWED_ORIGINS: list[str] = [
+    o.strip()
+    for o in os.environ.get("ALLOWED_ORIGINS", _DEFAULT_ORIGINS).split(",")
+    if o.strip()
+]
+# Optional regex list — useful when the production frontend is served from a
+# hash-based preview URL (e.g. Lovable / Vercel preview deployments).
+# By default we allow:
+#   * any *.lovable.app and *.lovableproject.com subdomain (deployed Lovable apps)
+#   * any *.ngrok-free.app / *.ngrok.app / *.ngrok.io subdomain (when the user
+#     forwards the dev server through ngrok and previews the app from anywhere)
+# Override with `ALLOWED_ORIGIN_REGEX` to lock things down in production.
+# Include common private LAN dev URLs (Vite "Network" URL is often
+# `http://192.168.x.x:8080` — the Origin header is not localhost, so
+# it must be accepted here or the browser will block with "Network Error").
+_DEFAULT_ORIGIN_REGEX = (
+    r"https://([a-z0-9-]+\.)*lovable\.app"
+    r"|https://([a-z0-9-]+\.)*lovableproject\.com"
+    r"|https://([a-z0-9-]+\.)*ngrok-free\.app"
+    r"|https://([a-z0-9-]+\.)*ngrok\.app"
+    r"|https://([a-z0-9-]+\.)*ngrok\.io"
+    r"|http://(192\.168\.\d{1,3}\.\d{1,3}|10\.\d{1,3}\.\d{1,3}\.\d{1,3}):\d+"
+)
+_ORIGIN_REGEX: str | None = os.environ.get("ALLOWED_ORIGIN_REGEX", _DEFAULT_ORIGIN_REGEX) or None
+
+DEVICE: torch.device = torch.device(
+    "cuda" if torch.cuda.is_available()
+    else "mps" if torch.backends.mps.is_available()
+    else "cpu"
+)
+
+POSITIVE_LABEL = "Cardiomegaly"
+NEGATIVE_LABEL = "No Cardiomegaly indication"
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+logging.basicConfig(
+    level=os.environ.get("LOG_LEVEL", "INFO"),
+    format="%(asctime)s  %(levelname)-5s  %(message)s",
+)
+log = logging.getLogger("inference")
+
+# ---------------------------------------------------------------------------
+# Preprocessing — delegate to the SAME normalization functions the training
+# dataset uses (`xrv_normalize_np` for densenet121, `imagenet_normalize_np`
+# for every other backbone). This guarantees byte-for-byte identical
+# preprocessing between training and inference.
+# ---------------------------------------------------------------------------
+_normalize_fn = get_normalize_fn(BACKBONE)
+
+
+def _pil_hflip(img: Image.Image) -> Image.Image:
+    return img.transpose(Image.FLIP_LEFT_RIGHT)
+
+
+def _tta_pipelines(size: int) -> List[T.Compose]:
+    """Match `src.transforms.make_tta_transforms` (6 deterministic passes)."""
+    s = (size, size)
+    return [
+        T.Compose([T.Resize(s)]),
+        T.Compose([T.Resize(s), T.Lambda(_pil_hflip)]),
+        T.Compose([T.Resize((size + 20, size + 20)), T.CenterCrop(s)]),
+        T.Compose([T.Resize((size - 20, size - 20)), T.Pad(10, fill=0), T.CenterCrop(s)]),
+        T.Compose([T.Resize(s), T.RandomAffine(degrees=(6, 6), fill=0)]),
+        T.Compose([T.Resize(s), T.RandomAffine(degrees=(-6, -6), fill=0)]),
+    ]
+
+
+def _single_eval_pipeline(size: int) -> T.Compose:
+    return T.Compose([T.Resize((size, size))])
+
+
+# ---------------------------------------------------------------------------
+# Ensemble loading
+# ---------------------------------------------------------------------------
+def _resolve_checkpoint(p: str) -> Path:
+    """Manifest paths are stored relative to ``model_training/notebooks/``."""
+    path = Path(p)
+    if path.is_absolute() and path.exists():
+        return path
+    for candidate in (NOTEBOOKS_DIR / p, RESULTS_DIR / Path(p).name):
+        if candidate.exists():
+            return candidate
+    raise FileNotFoundError(f"Checkpoint not found: {p!r}")
+
+
+def _load_ensemble() -> List[nn.Module]:
+    # Align CFG so build_model() reads the right backbone/size internally.
+    CFG.backbone = BACKBONE
+    CFG.img_size = IMG_SIZE
+
+    manifest = RESULTS_DIR / "ensemble_manifest.csv"
+    if manifest.exists():
+        df = pd.read_csv(manifest)
+        checkpoint_paths = [_resolve_checkpoint(p) for p in df["checkpoint"].tolist()]
+        log.info("Loading ensemble of %d models from %s", len(checkpoint_paths), manifest.name)
+    else:
+        best = RESULTS_DIR / "best_model.pth"
+        if not best.exists():
+            raise FileNotFoundError(
+                f"Neither {manifest} nor {best} exist. Train a model before starting the server."
+            )
+        checkpoint_paths = [best]
+        log.info("No manifest found, falling back to single checkpoint: %s", best.name)
+
+    models: list[nn.Module] = []
+    for ckpt_path in checkpoint_paths:
+        log.info("  → loading %s", ckpt_path.name)
+        model = build_model(BACKBONE)
+        state = torch.load(ckpt_path, map_location=DEVICE)
+        if isinstance(state, dict) and "state_dict" in state:
+            state = state["state_dict"]
+        missing, unexpected = model.load_state_dict(state, strict=False)
+        if missing or unexpected:
+            raise RuntimeError(
+                "Checkpoint architecture mismatch. "
+                f"backbone={BACKBONE!r}, checkpoint={ckpt_path.name!r}, "
+                f"missing_keys={len(missing)}, unexpected_keys={len(unexpected)}. "
+                "Use the correct MODEL_BACKBONE / MODEL_IMG_SIZE and ensure "
+                "ensemble_manifest.csv points to checkpoints from that training run."
+            )
+        model.to(DEVICE).eval()
+        models.append(model)
+
+    log.info(
+        "Ensemble ready — %d model(s) · device=%s · backbone=%s (detected=%s) · "
+        "normalize=%s · img_size=%d · tta=%s · threshold=%.4f",
+        len(models), DEVICE, BACKBONE, _DETECTED_BACKBONE,
+        _normalize_fn.__name__, IMG_SIZE, USE_TTA, DECISION_THRESHOLD,
+    )
+    return models
+
+
+# ---------------------------------------------------------------------------
+# FastAPI app
+# ---------------------------------------------------------------------------
+app = FastAPI(title="CardioScan inference", version="1.0")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=ALLOWED_ORIGINS,
+    allow_origin_regex=_ORIGIN_REGEX,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+_ensemble: list[nn.Module] = []
+_loaded_checkpoints: list[str] = []
+
+
+@app.on_event("startup")
+def _startup() -> None:
+    global _ensemble, _loaded_checkpoints
+    manifest = RESULTS_DIR / "ensemble_manifest.csv"
+    if manifest.exists():
+        df = pd.read_csv(manifest)
+        _loaded_checkpoints = [Path(p).name for p in df["checkpoint"].tolist()]
+    else:
+        _loaded_checkpoints = ["best_model.pth"]
+    _ensemble = _load_ensemble()
+
+
+@app.get("/health")
+def health() -> dict:
+    return {
+        "ok": bool(_ensemble),
+        "models": len(_ensemble),
+        "checkpoints": _loaded_checkpoints,
+        "backbone": BACKBONE,
+        "detected_backbone": _DETECTED_BACKBONE,
+        "normalization": _normalize_fn.__name__,
+        "img_size": IMG_SIZE,
+        "device": str(DEVICE),
+        "use_tta": USE_TTA,
+        "threshold": DECISION_THRESHOLD,
+    }
+
+
+@torch.no_grad()
+def _predict_probability_detailed(pil_gray: Image.Image) -> dict:
+    """Run ensemble (+ optional TTA) on a single PIL image.
+
+    Returns a dict with per-model / per-TTA logits for transparency.
+    Matches `tta_predict` / `tta_predict_ensemble` in ``src.train`` exactly:
+    average logits across TTA (per model), then average across models,
+    then sigmoid.
+    """
+    pipelines = _tta_pipelines(IMG_SIZE) if USE_TTA else [_single_eval_pipeline(IMG_SIZE)]
+
+    tensors = [_normalize_fn(pipeline(pil_gray)) for pipeline in pipelines]
+    batch = torch.stack(tensors, dim=0).to(DEVICE)  # (num_tta, 3, H, W)
+
+    per_model_tta_logits: list[np.ndarray] = []
+    per_model_mean_logit: list[float] = []
+    for model in _ensemble:
+        logit_vec = cardio_logit(model, batch).float().cpu().numpy()  # (num_tta,)
+        per_model_tta_logits.append(logit_vec)
+        per_model_mean_logit.append(float(np.mean(logit_vec)))
+
+    ensemble_mean_logit = float(np.mean(per_model_mean_logit))
+    probability = float(1.0 / (1.0 + np.exp(-ensemble_mean_logit)))
+
+    return {
+        "probability": probability,
+        "ensemble_mean_logit": ensemble_mean_logit,
+        "per_model_mean_logit": {
+            name: lg for name, lg in zip(_loaded_checkpoints, per_model_mean_logit)
+        },
+        "per_model_tta_logits": {
+            name: lg.tolist() for name, lg in zip(_loaded_checkpoints, per_model_tta_logits)
+        },
+        "num_tta_passes": batch.shape[0],
+    }
+
+
+@app.post("/predict")
+async def predict(image: UploadFile = File(...)) -> dict:
+    if not _ensemble:
+        raise HTTPException(status_code=503, detail="Model not ready")
+
+    raw = await image.read()
+    if not raw:
+        raise HTTPException(status_code=400, detail="Empty upload")
+
+    try:
+        pil = Image.open(io.BytesIO(raw)).convert("L")
+    except Exception as exc:  # noqa: BLE001
+        raise HTTPException(status_code=400, detail=f"Could not decode image: {exc}") from exc
+
+    try:
+        details = _predict_probability_detailed(pil)
+    except Exception as exc:  # noqa: BLE001
+        log.exception("Inference failed")
+        raise HTTPException(status_code=500, detail=f"Inference error: {exc}") from exc
+
+    probability = details["probability"]
+    is_positive = probability >= DECISION_THRESHOLD
+
+    log.info(
+        "/predict  file=%s  size=%d  prob=%.4f  thr=%.4f  -> %s  (per-model=%s, tta=%d)",
+        image.filename,
+        len(raw),
+        probability,
+        DECISION_THRESHOLD,
+        "Cardiomegaly" if is_positive else "Negative",
+        {k: round(v, 4) for k, v in details["per_model_mean_logit"].items()},
+        details["num_tta_passes"],
+    )
+
+    return {
+        "prediction": POSITIVE_LABEL if is_positive else NEGATIVE_LABEL,
+        "confidence": probability,
+        "heatmap_url": None,
+        "source": "model",
+        "threshold": DECISION_THRESHOLD,
+        "ensemble_size": len(_ensemble),
+        "use_tta": USE_TTA,
+    }
+
+
+@app.post("/debug/predict")
+async def debug_predict(image: UploadFile = File(...)) -> dict:
+    """Same as /predict but returns per-model and per-TTA raw logits for
+    verification against the training notebook's val/test CSVs."""
+    if not _ensemble:
+        raise HTTPException(status_code=503, detail="Model not ready")
+
+    raw = await image.read()
+    if not raw:
+        raise HTTPException(status_code=400, detail="Empty upload")
+
+    try:
+        pil = Image.open(io.BytesIO(raw)).convert("L")
+    except Exception as exc:  # noqa: BLE001
+        raise HTTPException(status_code=400, detail=f"Could not decode image: {exc}") from exc
+
+    details = _predict_probability_detailed(pil)
+    details["prediction"] = (
+        POSITIVE_LABEL if details["probability"] >= DECISION_THRESHOLD else NEGATIVE_LABEL
+    )
+    details["threshold"] = DECISION_THRESHOLD
+    details["use_tta"] = USE_TTA
+    details["checkpoints"] = _loaded_checkpoints
+    return details

model_training/notebooks/results/best_model.pth

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

model_training/notebooks/results/daily_submission-1.csv

@@ -0,0 +1,177 @@
+image_file,prob,pred
+IMG_000018.png,0.816906,1
+IMG_000021.png,0.009301819,0
+IMG_000039.png,0.33299014,0
+IMG_000044.png,0.11926782,0
+IMG_000047.png,0.3057367,0
+IMG_000054.png,0.9174445,1
+IMG_000077.png,0.0068948073,0
+IMG_000094.png,0.010871509,0
+IMG_000096.png,0.97423095,1
+IMG_000108.png,0.03271585,0
+IMG_000111.png,0.37760112,0
+IMG_000128.png,0.8483817,1
+IMG_000129.png,0.98759496,1
+IMG_000135.png,0.8694341,1
+IMG_000149.png,0.20452695,0
+IMG_000160.png,0.8993582,1
+IMG_000174.png,0.9729403,1
+IMG_000180.png,0.3869212,0
+IMG_000232.png,0.10533079,0
+IMG_000242.png,0.064271316,0
+IMG_000248.png,0.055668276,0
+IMG_000249.png,6.6870154e-05,0
+IMG_000255.png,0.011946698,0
+IMG_000273.png,0.0054892018,0
+IMG_000277.png,0.9634049,1
+IMG_000299.png,0.96502954,1
+IMG_000302.png,0.047373675,0
+IMG_000309.png,0.9813534,1
+IMG_000313.png,0.008047514,0
+IMG_000314.png,0.008340702,0
+IMG_000324.png,0.96767646,1
+IMG_000343.png,0.023570525,0
+IMG_000346.png,0.9816032,1
+IMG_000353.png,0.45696247,0
+IMG_000367.png,0.35300097,0
+IMG_000404.png,0.4996281,0
+IMG_000408.png,0.8722059,1
+IMG_000415.png,0.74312115,1
+IMG_000416.png,0.94917625,1
+IMG_000420.png,0.22852376,0
+IMG_000423.png,0.7794522,1
+IMG_000429.png,0.8098528,1
+IMG_000432.png,0.9711745,1
+IMG_000479.png,0.909901,1
+IMG_000483.png,0.832377,1
+IMG_000485.png,0.744525,1
+IMG_000522.png,0.9405937,1
+IMG_000527.png,0.8822646,1
+IMG_000532.png,0.97545457,1
+IMG_000536.png,0.89281857,1
+IMG_000538.png,0.9655915,1
+IMG_000547.png,0.3647764,0
+IMG_000548.png,0.47809702,0
+IMG_000549.png,0.97563666,1
+IMG_000565.png,0.074912064,0
+IMG_000568.png,0.08629721,0
+IMG_000575.png,0.9126054,1
+IMG_000576.png,0.76525265,1
+IMG_000579.png,0.00989682,0
+IMG_000580.png,0.036182728,0
+IMG_000593.png,0.90472263,1
+IMG_000622.png,0.002541845,0
+IMG_000627.png,0.0029941453,0
+IMG_000632.png,0.07461243,0
+IMG_000633.png,0.07481881,0
+IMG_000653.png,0.18598385,0
+IMG_000660.png,0.20837037,0
+IMG_000671.png,0.0016912636,0
+IMG_000675.png,0.1421747,0
+IMG_000683.png,0.025120575,0
+IMG_000688.png,0.57493603,1
+IMG_000694.png,0.94961226,1
+IMG_000696.png,0.3008333,0
+IMG_000708.png,0.012850549,0
+IMG_000710.png,0.9830056,1
+IMG_000773.png,0.0031617412,0
+IMG_000785.png,0.82301766,1
+IMG_000787.png,0.9569242,1
+IMG_000792.png,0.9786517,1
+IMG_000797.png,0.0004634541,0
+IMG_000821.png,0.024412306,0
+IMG_000854.png,0.19797583,0
+IMG_000862.png,0.9750999,1
+IMG_000870.png,0.8686767,1
+IMG_000880.png,0.0010660468,0
+IMG_000893.png,0.96038836,1
+IMG_000910.png,0.07809025,0
+IMG_000914.png,0.26980433,0
+IMG_000917.png,0.98292184,1
+IMG_000925.png,0.0027379196,0
+IMG_000936.png,0.96947944,1
+IMG_000942.png,0.82471883,1
+IMG_000945.png,0.00028870278,0
+IMG_000946.png,0.07984374,0
+IMG_000951.png,0.26128584,0
+IMG_000953.png,0.0010449657,0
+IMG_000981.png,0.090446874,0
+IMG_000985.png,0.018414477,0
+IMG_000988.png,0.9778957,1
+IMG_000991.png,0.036471717,0
+IMG_001026.png,0.59295475,1
+IMG_001027.png,0.9421946,1
+IMG_001056.png,0.5752065,1
+IMG_001063.png,0.028953826,0
+IMG_001071.png,0.024936734,0
+IMG_001083.png,0.95445114,1
+IMG_001084.png,0.90794367,1
+IMG_001085.png,0.7487882,1
+IMG_001100.png,0.92409223,1
+IMG_001112.png,0.1766397,0
+IMG_001113.png,0.93751234,1
+IMG_001121.png,0.80051255,1
+IMG_001148.png,0.1581435,0
+IMG_001154.png,0.001443795,0
+IMG_001155.png,0.99754816,1
+IMG_001158.png,0.21377504,0
+IMG_001160.png,0.8512862,1
+IMG_001162.png,0.55319506,1
+IMG_001166.png,0.013784781,0
+IMG_001168.png,0.6532163,1
+IMG_001179.png,0.11473991,0
+IMG_001180.png,0.057606816,0
+IMG_001184.png,0.3746491,0
+IMG_001205.png,0.0096385535,0
+IMG_001206.png,0.3501062,0
+IMG_001239.png,0.016910465,0
+IMG_001259.png,0.9424403,1
+IMG_001271.png,0.8103772,1
+IMG_001290.png,0.22025856,0
+IMG_001291.png,0.133331,0
+IMG_001304.png,0.9841086,1
+IMG_001317.png,0.75506747,1
+IMG_001321.png,0.014835258,0
+IMG_001334.png,0.03285374,0
+IMG_001336.png,0.36698562,0
+IMG_001349.png,0.03645498,0
+IMG_001352.png,0.72149867,1
+IMG_001363.png,0.00038983554,0
+IMG_001365.png,0.6854751,1
+IMG_001368.png,0.9896269,1
+IMG_001384.png,0.71602064,1
+IMG_001393.png,0.017989887,0
+IMG_001394.png,0.0023077542,0
+IMG_001405.png,0.8804799,1
+IMG_001412.png,0.5575575,1
+IMG_001417.png,0.71472263,1
+IMG_001436.png,0.9894505,1
+IMG_001443.png,0.00088119216,0
+IMG_001495.png,0.005760317,0
+IMG_001504.png,0.017389266,0
+IMG_001506.png,0.012142896,0
+IMG_001508.png,0.81739867,1
+IMG_001511.png,0.9034313,1
+IMG_001528.png,0.025507784,0
+IMG_001536.png,0.5163997,1
+IMG_001570.png,0.014479928,0
+IMG_001572.png,0.004765836,0
+IMG_001577.png,0.03651942,0
+IMG_001581.png,0.0067347363,0
+IMG_001588.png,0.7685501,1
+IMG_001593.png,0.92315125,1
+IMG_001605.png,0.028199496,0
+IMG_001606.png,0.092707306,0
+IMG_001621.png,0.00926323,0
+IMG_001628.png,0.33566543,0
+IMG_001638.png,0.0071623144,0
+IMG_001645.png,0.0010000179,0
+IMG_001671.png,0.0020201257,0
+IMG_001684.png,0.87558657,1
+IMG_001688.png,0.86326087,1
+IMG_001702.png,0.014059455,0
+IMG_001710.png,0.97905207,1
+IMG_001718.png,0.00522173,0
+IMG_001726.png,0.26297852,0
+IMG_001731.png,0.56691897,1
+IMG_001743.png,0.9594168,1

model_training/notebooks/results/ensemble_manifest.csv

@@ -0,0 +1,4 @@
+seed,best_val_auc,checkpoint
+8,0.9496841803043353,results/model_seed8.pth
+7,0.9425782371518806,results/model_seed7.pth
+2024,0.94717197817973,results/model_seed2024.pth

model_training/notebooks/results/model_seed2024.pth

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

model_training/notebooks/results/model_seed42.pth

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

model_training/notebooks/results/model_seed7.pth

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

model_training/notebooks/results/model_seed8.pth

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

model_training/notebooks/results/test_metrics_final.json

@@ -0,0 +1,14 @@
+{
+  "threshold": 0.504486,
+  "auc": 0.9391329313809934,
+  "sensitivity": 0.8703703703703703,
+  "specificity": 0.8527131782945736,
+  "accuracy": 0.8607594936708861,
+  "youden": 0.7230835486649441,
+  "composite": 0.9003373528567327,
+  "precision": 0.831858407079646,
+  "tp": 94,
+  "tn": 110,
+  "fp": 19,
+  "fn": 14
+}

model_training/notebooks/results/test_predictions.csv

@@ -0,0 +1,238 @@
+filename,y_true,prob,pred,correct
+IMG_000824.png,0,0.021219134,0,1
+IMG_000990.png,1,0.7771948,1,1
+IMG_001690.png,1,0.85049516,1,1
+IMG_000879.png,1,0.8450817,1,1
+IMG_000884.png,0,0.11847936,0,1
+IMG_001538.png,1,0.8167436,1,1
+IMG_001404.png,1,0.799158,1,1
+IMG_001043.png,0,0.030076103,0,1
+IMG_001194.png,0,0.20013258,0,1
+IMG_000345.png,0,0.003733192,0,1
+IMG_001019.png,0,0.4092049,0,1
+IMG_000233.png,1,0.754443,1,1
+IMG_000994.png,1,0.8932385,1,1
+IMG_000219.png,0,0.74411124,1,0
+IMG_000758.png,0,0.88436824,1,0
+IMG_001127.png,0,0.0010003505,0,1
+IMG_000185.png,1,0.43144453,0,0
+IMG_000344.png,1,0.7200385,1,1
+IMG_000462.png,1,0.6866032,1,1
+IMG_001243.png,0,0.005522695,0,1
+IMG_000110.png,0,0.00616389,0,1
+IMG_000178.png,1,0.38014814,0,0
+IMG_001282.png,0,0.047400977,0,1
+IMG_000451.png,1,0.95899737,1,1
+IMG_001312.png,1,0.87483233,1,1
+IMG_001298.png,1,0.89103687,1,1
+IMG_000514.png,1,0.9204423,1,1
+IMG_001297.png,0,0.026098764,0,1
+IMG_000941.png,1,0.84286815,1,1
+IMG_000218.png,1,0.32278225,0,0
+IMG_001117.png,0,0.42146167,0,1
+IMG_000001.png,0,0.0846162,0,1
+IMG_001105.png,0,0.34927747,0,1
+IMG_000079.png,0,0.0015609249,0,1
+IMG_000400.png,0,0.06923158,0,1
+IMG_000260.png,1,0.9263501,1,1
+IMG_000998.png,1,0.6549944,1,1
+IMG_001281.png,1,0.71612954,1,1
+IMG_000690.png,0,0.030174967,0,1
+IMG_001627.png,1,0.95443106,1,1
+IMG_001107.png,1,0.7405456,1,1
+IMG_000763.png,0,0.14266923,0,1
+IMG_000545.png,0,0.022861702,0,1
+IMG_001343.png,1,0.78821915,1,1
+IMG_001175.png,1,0.8847534,1,1
+IMG_000682.png,1,0.18611808,0,0
+IMG_001398.png,0,0.010194484,0,1
+IMG_001556.png,1,0.80163234,1,1
+IMG_001225.png,1,0.95753545,1,1
+IMG_001460.png,0,0.39417872,0,1
+IMG_001746.png,1,0.822455,1,1
+IMG_001406.png,1,0.9840471,1,1
+IMG_001052.png,0,0.24067384,0,1
+IMG_001640.png,0,0.022804145,0,1
+IMG_001728.png,1,0.9836304,1,1
+IMG_001592.png,0,0.36900538,0,1
+IMG_001473.png,1,0.9562594,1,1
+IMG_000376.png,0,0.007365662,0,1
+IMG_001390.png,0,0.019877983,0,1
+IMG_000169.png,0,0.030604592,0,1
+IMG_001310.png,0,0.011923165,0,1
+IMG_000151.png,0,0.6607677,1,0
+IMG_001240.png,0,0.013350104,0,1
+IMG_000864.png,1,0.7523066,1,1
+IMG_001741.png,1,0.9743217,1,1
+IMG_001364.png,1,0.35030937,0,0
+IMG_000121.png,0,0.0022226572,0,1
+IMG_000359.png,0,0.004687663,0,1
+IMG_001075.png,1,0.8264759,1,1
+IMG_000187.png,0,0.17870605,0,1
+IMG_000237.png,1,0.9433076,1,1
+IMG_001562.png,1,0.96882564,1,1
+IMG_001114.png,1,0.98810416,1,1
+IMG_000223.png,0,0.021592166,0,1
+IMG_001745.png,0,0.95945805,1,0
+IMG_000826.png,0,0.029931583,0,1
+IMG_001704.png,0,0.23410255,0,1
+IMG_000406.png,0,0.14752638,0,1
+IMG_000634.png,1,0.6518697,1,1
+IMG_001238.png,0,0.08548438,0,1
+IMG_000993.png,1,0.7866735,1,1
+IMG_001736.png,0,0.40755022,0,1
+IMG_000481.png,1,0.001395701,0,0
+IMG_001395.png,1,0.7820107,1,1
+IMG_000553.png,0,0.02335425,0,1
+IMG_000754.png,1,0.7037294,1,1
+IMG_001018.png,0,0.95035726,1,0
+IMG_001492.png,1,0.88814825,1,1
+IMG_000737.png,0,0.00022573896,0,1
+IMG_001617.png,0,0.017841075,0,1
+IMG_000411.png,1,0.46054697,0,0
+IMG_000764.png,1,0.9863303,1,1
+IMG_001198.png,0,0.53324735,1,0
+IMG_001237.png,1,0.40191436,0,0
+IMG_001639.png,1,0.6333021,1,1
+IMG_000829.png,1,0.9704466,1,1
+IMG_001192.png,1,0.8689759,1,1
+IMG_001143.png,0,0.12318405,0,1
+IMG_000860.png,0,0.22503993,0,1
+IMG_001308.png,1,0.9235162,1,1
+IMG_000067.png,1,0.8142528,1,1
+IMG_000899.png,0,0.0091903545,0,1
+IMG_000602.png,1,0.7867315,1,1
+IMG_000022.png,0,0.12565576,0,1
+IMG_001553.png,0,0.5937602,1,0
+IMG_000689.png,0,0.0035498547,0,1
+IMG_001719.png,1,0.97812426,1,1
+IMG_000074.png,0,0.017582327,0,1
+IMG_001584.png,0,0.29081395,0,1
+IMG_000127.png,0,0.13165514,0,1
+IMG_000204.png,0,0.044497356,0,1
+IMG_001663.png,1,0.7866542,1,1
+IMG_001116.png,0,0.031116765,0,1
+IMG_000964.png,1,0.9310901,1,1
+IMG_001677.png,1,0.927338,1,1
+IMG_001418.png,1,0.8989984,1,1
+IMG_000974.png,1,0.9450868,1,1
+IMG_000477.png,1,0.962653,1,1
+IMG_001126.png,0,0.00042581963,0,1
+IMG_001373.png,1,0.84743226,1,1
+IMG_000589.png,1,0.8598813,1,1
+IMG_001389.png,1,0.7277787,1,1
+IMG_001292.png,0,0.30514425,0,1
+IMG_000240.png,1,0.9254172,1,1
+IMG_000437.png,0,0.07736599,0,1
+IMG_000751.png,0,0.21614793,0,1
+IMG_001278.png,0,0.00081374723,0,1
+IMG_000724.png,1,0.8973737,1,1
+IMG_000944.png,1,0.9696045,1,1
+IMG_000930.png,1,0.06275673,0,0
+IMG_001586.png,1,0.85567933,1,1
+IMG_001415.png,0,0.42133018,0,1
+IMG_000235.png,0,0.00044268242,0,1
+IMG_000789.png,0,0.51844907,1,0
+IMG_001722.png,0,0.02285177,0,1
+IMG_000457.png,1,0.9203535,1,1
+IMG_001385.png,1,0.33224016,0,0
+IMG_001545.png,0,0.33094287,0,1
+IMG_001327.png,0,0.0026560111,0,1
+IMG_000693.png,1,0.7572429,1,1
+IMG_001427.png,0,0.18905798,0,1
+IMG_001660.png,0,0.059407346,0,1
+IMG_001189.png,0,0.047472887,0,1
+IMG_000257.png,0,0.8905588,1,0
+IMG_001369.png,0,0.36061272,0,1
+IMG_001691.png,1,0.964177,1,1
+IMG_001732.png,1,0.9945857,1,1
+IMG_001520.png,0,0.22373733,0,1
+IMG_001376.png,1,0.7934236,1,1
+IMG_000436.png,0,0.71353745,1,0
+IMG_000741.png,1,0.98955476,1,1
+IMG_000446.png,0,0.76797557,1,0
+IMG_000876.png,0,0.43126056,0,1
+IMG_001462.png,0,0.013134937,0,1
+IMG_001066.png,0,0.00046867327,0,1
+IMG_000114.png,0,0.3608086,0,1
+IMG_001015.png,0,0.04901976,0,1
+IMG_001372.png,0,0.018457958,0,1
+IMG_000949.png,1,0.99760324,1,1
+IMG_000919.png,0,0.016946174,0,1
+IMG_001172.png,1,0.8392962,1,1
+IMG_001068.png,0,0.8429959,1,0
+IMG_000087.png,0,0.6321575,1,0
+IMG_000888.png,0,0.84551364,1,0
+IMG_000286.png,1,0.9955705,1,1
+IMG_000214.png,1,0.73011214,1,1
+IMG_001065.png,0,0.047320206,0,1
+IMG_000510.png,0,0.00021625705,0,1
+IMG_000315.png,0,0.040586166,0,1
+IMG_000422.png,1,0.86234355,1,1
+IMG_000468.png,1,0.9084235,1,1
+IMG_000749.png,0,0.048509527,0,1
+IMG_000822.png,0,0.00459977,0,1
+IMG_001025.png,0,0.1423657,0,1
+IMG_000777.png,1,0.94110733,1,1
+IMG_001235.png,1,0.955069,1,1
+IMG_001265.png,1,0.4247596,0,0
+IMG_000476.png,0,0.0074078897,0,1
+IMG_000922.png,1,0.4249936,0,0
+IMG_001294.png,0,0.5523263,1,0
+IMG_001181.png,0,0.021967547,0,1
+IMG_000179.png,1,0.6198387,1,1
+IMG_000844.png,0,0.0009595261,0,1
+IMG_001062.png,0,0.02210043,0,1
+IMG_000647.png,0,0.048218727,0,1
+IMG_000629.png,1,0.7496184,1,1
+IMG_000743.png,1,0.94583535,1,1
+IMG_000639.png,0,0.31978914,0,1
+IMG_000207.png,0,0.0010147754,0,1
+IMG_000116.png,0,0.4486534,0,1
+IMG_000412.png,0,0.00072938023,0,1
+IMG_001076.png,0,0.00037972903,0,1
+IMG_000911.png,0,0.21701539,0,1
+IMG_000226.png,1,0.9124851,1,1
+IMG_001434.png,0,0.1508207,0,1
+IMG_001534.png,0,0.007111399,0,1
+IMG_000239.png,1,0.97189856,1,1
+IMG_000729.png,0,0.024547786,0,1
+IMG_000362.png,0,0.0368409,0,1
+IMG_001563.png,1,0.92587185,1,1
+IMG_000850.png,0,0.031102972,0,1
+IMG_001283.png,0,0.0041644424,0,1
+IMG_001077.png,0,0.0043652514,0,1
+IMG_000109.png,1,0.94027257,1,1
+IMG_001039.png,0,0.31002668,0,1
+IMG_000855.png,1,0.9954782,1,1
+IMG_000581.png,0,0.58953196,1,0
+IMG_001670.png,1,0.41889447,0,0
+IMG_001489.png,0,0.0039128903,0,1
+IMG_001488.png,1,0.977498,1,1
+IMG_001247.png,1,0.9217244,1,1
+IMG_001340.png,1,0.9252595,1,1
+IMG_000562.png,0,0.00028323507,0,1
+IMG_001714.png,1,0.9137611,1,1
+IMG_000113.png,1,0.83810467,1,1
+IMG_000519.png,0,0.24291025,0,1
+IMG_000352.png,1,0.89757895,1,1
+IMG_000060.png,0,0.12018548,0,1
+IMG_001689.png,1,0.88260335,1,1
+IMG_001332.png,0,0.021517713,0,1
+IMG_001227.png,0,0.5806698,1,0
+IMG_000952.png,1,0.91132796,1,1
+IMG_001223.png,0,0.0054034726,0,1
+IMG_001662.png,1,0.9796165,1,1
+IMG_001242.png,1,0.89553756,1,1
+IMG_001542.png,1,0.2224111,0,0
+IMG_000150.png,0,0.038930204,0,1
+IMG_001021.png,0,0.00035879802,0,1
+IMG_001516.png,0,0.62845725,1,0
+IMG_001074.png,0,0.7126184,1,0
+IMG_001648.png,1,0.9681084,1,1
+IMG_000300.png,1,0.66993195,1,1
+IMG_000194.png,0,0.16441628,0,1
+IMG_000728.png,0,0.005496844,0,1
+IMG_000818.png,1,0.92287654,1,1
+IMG_001712.png,0,0.29255372,0,1
+IMG_000719.png,0,0.075776406,0,1

model_training/notebooks/results/training_history.csv

@@ -0,0 +1,51 @@
+seed,stage,epoch,train_loss,train_auc,train_acc,train_composite,val_loss,val_auc,val_acc,val_sens,val_spec,val_composite,lr
+8,frozen,1,0.9582490903990609,0.7691765873015873,0.6177536231884058,0.6771676587301587,0.7091568447649479,0.85099052540913,0.6708860759493671,0.37037037037037035,0.9224806201550387,0.7487080103359173,0.001
+8,frozen,2,0.6246700976576124,0.783531746031746,0.6838768115942029,0.726031746031746,0.48649174720048904,0.8657766293425209,0.7552742616033755,0.6574074074074074,0.8372093023255814,0.8065424921045077,0.001
+8,frozen,3,0.5868643377508436,0.7798181216931217,0.6920289855072463,0.7326074735449736,0.45043402910232544,0.8748923341946597,0.7721518987341772,0.7037037037037037,0.8294573643410853,0.8207364341085271,0.001
+8,frozen,4,0.5721473864146641,0.7899371693121694,0.7038043478260869,0.7456233465608466,0.43230215832591057,0.878409417169107,0.7805907172995781,0.7314814814814815,0.8217054263565892,0.8275014355440712,0.001
+8,frozen,5,0.54250961627279,0.8040046296296297,0.7246376811594203,0.7627959656084657,0.4336203671991825,0.8802038472581108,0.7763713080168776,0.7129629629629629,0.8294573643410853,0.8257070054550675,0.001
+8,frozen,6,0.534449862582343,0.8101421957671958,0.7336956521739131,0.7705076058201058,0.40960250422358513,0.8915446454206145,0.7890295358649789,0.7407407407407407,0.8294573643410853,0.8383218489807638,0.001
+8,frozen,7,0.530328972850527,0.814781746031746,0.7454710144927537,0.7780853174603175,0.40932638198137283,0.8911139821992536,0.7932489451476793,0.7407407407407407,0.8372093023255814,0.8400445018662074,0.001
+8,frozen,8,0.5051169097423553,0.8304497354497355,0.7373188405797102,0.7829629629629631,0.4084223732352257,0.8912575366063739,0.7974683544303798,0.75,0.8372093023255814,0.8424310938845824,0.001
+8,frozen,9,0.5022006383963994,0.8348148148148148,0.7672101449275363,0.7998478835978836,0.4024202488362789,0.895205282802182,0.7890295358649789,0.7314814814814815,0.8372093023255814,0.8397753373528568,0.001
+8,frozen,10,0.49878278289522443,0.8352347883597884,0.7518115942028986,0.7921808862433863,0.39458586275577545,0.8993683606086705,0.7890295358649789,0.7314814814814815,0.8372093023255814,0.8418568762561011,0.001
+8,finetune,1,0.4544305384159088,0.8672321428571428,0.7835144927536232,0.8254613095238095,0.38248663768172264,0.919250645994832,0.8270042194092827,0.75,0.8914728682170543,0.8699935400516796,0.0009891830623632338
+8,finetune,2,0.38789899774960107,0.9041567460317461,0.8342391304347826,0.8695585317460318,0.2955472208559513,0.9496841803043353,0.8860759493670886,0.9444444444444444,0.8372093023255814,0.9202555268446742,0.0009572050015330873
+8,finetune,3,0.3507444177355085,0.9221329365079365,0.8469202898550725,0.8848561507936508,0.3256516754627228,0.937123169681309,0.8818565400843882,0.8703703703703703,0.8914728682170543,0.9090223944875107,0.0009054634122155989
+8,finetune,4,0.33837775332587106,0.9301190476190476,0.8641304347826086,0.8962896825396826,0.33792560175061226,0.9344674131495836,0.8607594936708861,0.8425925925925926,0.875968992248062,0.8968741027849554,0.0008362196501476348
+8,finetune,5,0.30863836577960424,0.9406580687830688,0.8586956521739131,0.90088458994709,0.35501030273735523,0.9326729830605799,0.8565400843881856,0.7962962962962963,0.9069767441860465,0.8921547516508757,0.0007524999999999999
+8,finetune,6,0.32643192623342787,0.9347982804232804,0.8523550724637681,0.892974537037037,0.31595958210527897,0.9378409417169108,0.8860759493670886,0.8796296296296297,0.8914728682170543,0.9116960953201263,0.0006579634122155989
+7,frozen,1,0.9370916630540576,0.7815476190476189,0.6204710144927537,0.6849999999999999,0.6874790899455547,0.8518518518518519,0.6708860759493671,0.3888888888888889,0.9069767441860465,0.7498923341946597,0.001
+7,frozen,2,0.6154342787606376,0.801253306878307,0.6983695652173914,0.7406068121693122,0.5005612336099148,0.863982199253517,0.7510548523206751,0.6481481481481481,0.8372093023255814,0.803330462245191,0.001
+7,frozen,3,0.5728206719670977,0.7850958994708995,0.7028985507246377,0.7411193783068782,0.4355204217135906,0.8814958369221936,0.7848101265822784,0.7407407407407407,0.8217054263565892,0.8313594602354293,0.001
+7,frozen,4,0.5409952683108193,0.803399470899471,0.7119565217391305,0.7561838624338624,0.4371259845793247,0.8789836347975883,0.7805907172995781,0.7222222222222222,0.8294573643410853,0.8274117140396211,0.001
+7,frozen,5,0.5573380930083138,0.7994576719576719,0.7346014492753623,0.7652645502645502,0.41805607080459595,0.8866637955785241,0.7805907172995781,0.7407407407407407,0.813953488372093,0.8320054550674706,0.001
+7,frozen,6,0.5511363804340362,0.8038194444444444,0.7355072463768116,0.7692113095238096,0.4179871119558811,0.886017800746483,0.7974683544303798,0.75,0.8372093023255814,0.8398112259546369,0.001
+7,frozen,7,0.5211189142295293,0.8182903439153438,0.7336956521739131,0.7744229497354497,0.40560774877667427,0.8934108527131782,0.7974683544303798,0.75,0.8372093023255814,0.8435077519379844,0.001
+7,frozen,8,0.5251553058624268,0.8196527777777778,0.7391304347826086,0.7777628968253969,0.40271764248609543,0.8944157335630204,0.8059071729957806,0.7685185185185185,0.8372093023255814,0.8486398219925352,0.001
+7,frozen,9,0.5052971592971257,0.8322817460317459,0.7445652173913043,0.7871329365079364,0.3970758095383644,0.8983634797588287,0.8016877637130801,0.7592592592592593,0.8372093023255814,0.8482988802756245,0.001
+7,frozen,10,0.5330768167972565,0.8135284391534392,0.7373188405797102,0.7737086640211641,0.3852919824421406,0.904392764857881,0.810126582278481,0.7870370370370371,0.8294573643410853,0.8563199827734711,0.001
+7,finetune,1,0.47272565024239677,0.8557539682539683,0.7817028985507246,0.8182539682539682,0.44458993524312973,0.8919753086419753,0.7763713080168776,0.6481481481481481,0.8837209302325582,0.8289549239161642,0.0009891830623632338
+7,finetune,2,0.38450789025851656,0.9061078042328042,0.8170289855072463,0.8615062830687831,0.3831586390733719,0.9171691070915876,0.8354430379746836,0.7685185185185185,0.8914728682170543,0.873582400229687,0.0009572050015330873
+7,finetune,3,0.35653283638613564,0.922037037037037,0.8505434782608695,0.8862367724867725,0.31522940658032894,0.9425782371518806,0.8818565400843882,0.9074074074074074,0.8604651162790697,0.9132572494975595,0.0009054634122155989
+7,finetune,4,0.33924023721899305,0.9283333333333333,0.8505434782608695,0.8892261904761904,0.3659691587090492,0.9249210450760839,0.8312236286919831,0.7592592592592593,0.8914728682170543,0.8751435544071202,0.0008362196501476348
+7,finetune,5,0.33330591917037966,0.9319179894179894,0.8623188405797102,0.8970701058201058,0.32207747735083103,0.939420040195234,0.8649789029535865,0.8981481481481481,0.8372093023255814,0.9035493827160493,0.0007524999999999999
+7,finetune,6,0.31548327335289544,0.9377645502645502,0.8596014492753623,0.8990608465608465,0.35484062135219574,0.9318116566178581,0.8438818565400844,0.7962962962962963,0.8837209302325582,0.8859101349411427,0.0006579634122155989
+7,finetune,7,0.287742834006037,0.9492956349206351,0.8731884057971014,0.9116319444444445,0.3438141830265522,0.930304335343095,0.8481012658227848,0.7962962962962963,0.8914728682170543,0.887094458799885,0.0005567415893174885
+2024,frozen,1,0.9445781009537834,0.7710317460317461,0.6304347826086957,0.6849603174603175,0.7147812955081463,0.8519236290554119,0.6666666666666666,0.37037037037037035,0.9147286821705426,0.7472365776629342,0.001
+2024,frozen,2,0.6475456161158425,0.7795568783068784,0.6902173913043478,0.7264847883597884,0.4829690493643284,0.8683606086706861,0.7510548523206751,0.6481481481481481,0.8372093023255814,0.8055196669537755,0.001
+2024,frozen,3,0.557839333159583,0.7974801587301588,0.7119565217391305,0.7520337301587301,0.45181746035814285,0.8722365776629342,0.7721518987341772,0.7037037037037037,0.8294573643410853,0.8194085558426644,0.001
+2024,frozen,4,0.553470607314791,0.7997123015873016,0.717391304347826,0.7562053571428571,0.43246644735336304,0.8798449612403101,0.7805907172995781,0.7314814814814815,0.8217054263565892,0.8282192075796727,0.001
+2024,frozen,5,0.5317457369395665,0.8138822751322751,0.7318840579710145,0.772417328042328,0.41545065492391586,0.8885300028710881,0.7890295358649789,0.75,0.8217054263565892,0.8371913580246914,0.001
+2024,frozen,6,0.5310433038643428,0.8142757936507937,0.7273550724637681,0.7686259920634921,0.41416966915130615,0.8903962101636521,0.7848101265822784,0.7222222222222222,0.8372093023255814,0.835055986218777,0.001
+2024,frozen,7,0.535319973741259,0.810681216931217,0.7336956521739131,0.7706183862433862,0.41076211631298065,0.88946310651737,0.810126582278481,0.7870370370370371,0.8294573643410853,0.8488551536032156,0.001
+2024,frozen,8,0.5011444449424743,0.8314996693121693,0.7472826086956522,0.7886268187830687,0.4013783372938633,0.8952770600057421,0.7932489451476793,0.7407407407407407,0.8372093023255814,0.8421260407694516,0.001
+2024,frozen,9,0.5317847013473511,0.8112169312169313,0.7336956521739131,0.7711243386243387,0.38976578786969185,0.9020241171403963,0.8227848101265823,0.8148148148148148,0.8294573643410853,0.8620801033591732,0.001
+2024,frozen,10,0.5140501362936837,0.8266732804232804,0.7336956521739131,0.7782175925925926,0.3864467516541481,0.9039621016365202,0.8143459915611815,0.7962962962962963,0.8294573643410853,0.8584194659776055,0.001
+2024,finetune,1,0.4775453839983259,0.853396164021164,0.7608695652173914,0.8070949074074074,0.3899293653666973,0.9338931955211025,0.8354430379746836,0.9444444444444444,0.7441860465116279,0.8891042204995693,0.0009891830623632338
+2024,finetune,2,0.38173683881759646,0.9084457671957672,0.8251811594202898,0.8663458994708995,0.3108560163527727,0.9433677863910422,0.890295358649789,0.8888888888888888,0.8914728682170543,0.9167743324720068,0.0009572050015330873
+2024,finetune,3,0.36059877617018565,0.918994708994709,0.8460144927536232,0.8829497354497355,0.30220645666122437,0.94717197817973,0.890295358649789,0.8981481481481481,0.8837209302325582,0.9190532586850415,0.0009054634122155989
+2024,finetune,4,0.3435957955462592,0.9252678571428571,0.8505434782608695,0.8876934523809523,0.32907535694539547,0.9417886879127189,0.8734177215189873,0.9351851851851852,0.8217054263565892,0.910116996841803,0.0008362196501476348
+2024,finetune,5,0.3113635071686336,0.9391468253968255,0.8731884057971014,0.9062400793650794,0.35001079365611076,0.9295147861039335,0.8523206751054853,0.8240740740740741,0.875968992248062,0.8897681596325007,0.0007524999999999999
+2024,finetune,6,0.3115046965224402,0.9414550264550263,0.8605072463768116,0.9017989417989417,0.3371146433055401,0.9364771748492678,0.8312236286919831,0.7870370370370371,0.8682170542635659,0.8820521102497847,0.0006579634122155989
+2024,finetune,7,0.267705562710762,0.9570701058201058,0.8786231884057971,0.9179398148148148,0.3176867663860321,0.9399942578237152,0.8649789029535865,0.8425925925925926,0.8837209302325582,0.9015755096181453,0.0005567415893174885

model_training/notebooks/results/val_metrics_final.json

@@ -0,0 +1,14 @@
+{
+  "threshold": 0.504486,
+  "auc": 0.9499712891185758,
+  "sensitivity": 0.9166666666666666,
+  "specificity": 0.8837209302325582,
+  "accuracy": 0.8987341772151899,
+  "youden": 0.8003875968992249,
+  "composite": 0.9250825437840942,
+  "precision": 0.868421052631579,
+  "tp": 99,
+  "tn": 114,
+  "fp": 15,
+  "fn": 9
+}

model_training/notebooks/results/val_predictions.csv

@@ -0,0 +1,238 @@
+filename,y_true,prob,pred,correct
+IMG_000833.png,0,0.08514188,0,1
+IMG_000868.png,0,0.07656998,0,1
+IMG_000471.png,1,0.926362,1,1
+IMG_001514.png,0,0.042604674,0,1
+IMG_001123.png,0,0.010878541,0,1
+IMG_000311.png,0,0.0019978306,0,1
+IMG_000768.png,0,0.1100046,0,1
+IMG_001354.png,0,0.38976616,0,1
+IMG_000677.png,1,0.9424959,1,1
+IMG_001694.png,1,0.82901657,1,1
+IMG_001249.png,1,0.9801762,1,1
+IMG_001543.png,1,0.5918354,1,1
+IMG_001138.png,1,0.9144192,1,1
+IMG_001279.png,0,0.0023716255,0,1
+IMG_001425.png,1,0.9752167,1,1
+IMG_001664.png,0,0.0030602103,0,1
+IMG_000517.png,0,0.26428953,0,1
+IMG_000238.png,0,0.07020499,0,1
+IMG_001419.png,1,0.9230154,1,1
+IMG_000357.png,0,0.023781383,0,1
+IMG_001413.png,0,0.53677505,1,0
+IMG_001438.png,0,0.003928518,0,1
+IMG_000730.png,1,0.9570253,1,1
+IMG_000043.png,1,0.9750734,1,1
+IMG_000034.png,0,0.006953893,0,1
+IMG_000657.png,0,0.07155775,0,1
+IMG_001544.png,0,0.90743506,1,0
+IMG_000216.png,0,0.029633842,0,1
+IMG_001193.png,0,0.015726507,0,1
+IMG_001046.png,0,0.039458692,0,1
+IMG_001555.png,0,0.3316432,0,1
+IMG_001622.png,1,0.9557772,1,1
+IMG_000170.png,1,0.8454006,1,1
+IMG_000584.png,1,0.7091627,1,1
+IMG_000750.png,0,0.6704473,1,0
+IMG_000168.png,1,0.90156275,1,1
+IMG_000230.png,0,0.66135454,1,0
+IMG_000534.png,1,0.9762868,1,1
+IMG_001523.png,0,0.5044856,0,1
+IMG_000926.png,1,0.96041846,1,1
+IMG_000776.png,0,0.22449876,0,1
+IMG_000842.png,1,0.9752196,1,1
+IMG_001338.png,1,0.29997367,0,0
+IMG_000126.png,1,0.8138403,1,1
+IMG_000377.png,1,0.8908096,1,1
+IMG_001713.png,1,0.92572457,1,1
+IMG_000996.png,0,0.3828967,0,1
+IMG_000278.png,0,0.009509609,0,1
+IMG_001392.png,1,0.96734214,1,1
+IMG_000666.png,0,0.005913499,0,1
+IMG_001012.png,0,0.0072901817,0,1
+IMG_000515.png,0,0.18308273,0,1
+IMG_000177.png,1,0.0014123927,0,0
+IMG_000099.png,1,0.71664655,1,1
+IMG_001485.png,0,0.07025461,0,1
+IMG_000599.png,1,0.7633101,1,1
+IMG_001377.png,0,0.00014443095,0,1
+IMG_001490.png,1,0.9397476,1,1
+IMG_000612.png,0,0.04453209,0,1
+IMG_001293.png,1,0.92839843,1,1
+IMG_001679.png,1,0.75982463,1,1
+IMG_000783.png,0,0.102033496,0,1
+IMG_001396.png,0,0.06896914,0,1
+IMG_001047.png,0,0.0027958185,0,1
+IMG_000090.png,0,0.3977522,0,1
+IMG_000601.png,1,0.37769222,0,0
+IMG_001475.png,1,0.89420277,1,1
+IMG_000494.png,1,0.63474864,1,1
+IMG_001216.png,0,0.025922079,0,1
+IMG_001564.png,1,0.97837263,1,1
+IMG_000928.png,0,0.057339218,0,1
+IMG_001161.png,0,0.016286755,0,1
+IMG_000024.png,0,0.8985922,1,0
+IMG_000319.png,0,0.648694,1,0
+IMG_001416.png,0,0.04064005,0,1
+IMG_000478.png,1,0.9229935,1,1
+IMG_001122.png,0,0.049890943,0,1
+IMG_001740.png,1,0.93487585,1,1
+IMG_001500.png,0,0.09520903,0,1
+IMG_000140.png,1,0.98620355,1,1
+IMG_001289.png,1,0.9263547,1,1
+IMG_000937.png,1,0.60724884,1,1
+IMG_000184.png,1,0.56130826,1,1
+IMG_001060.png,0,0.0008340298,0,1
+IMG_001379.png,1,0.72570825,1,1
+IMG_000051.png,1,0.9593886,1,1
+IMG_000684.png,0,0.031647827,0,1
+IMG_000173.png,1,0.54984164,1,1
+IMG_001529.png,0,0.37173158,0,1
+IMG_001540.png,0,0.0022377113,0,1
+IMG_000469.png,0,0.011063429,0,1
+IMG_000452.png,0,0.5156396,1,0
+IMG_000732.png,0,0.40668148,0,1
+IMG_000546.png,0,0.8375038,1,0
+IMG_000506.png,1,0.9919884,1,1
+IMG_001633.png,0,0.33360916,0,1
+IMG_000082.png,0,0.371273,0,1
+IMG_000206.png,0,0.16295624,0,1
+IMG_000975.png,0,0.00403203,0,1
+IMG_000426.png,1,0.98051214,1,1
+IMG_000441.png,0,0.07469518,0,1
+IMG_000117.png,0,0.031310383,0,1
+IMG_000973.png,0,0.00051067735,0,1
+IMG_000881.png,1,0.8859954,1,1
+IMG_000247.png,1,0.94318277,1,1
+IMG_000574.png,0,0.014506694,0,1
+IMG_000381.png,1,0.9848424,1,1
+IMG_001618.png,0,0.012155103,0,1
+IMG_001053.png,1,0.24243784,0,0
+IMG_001400.png,0,0.25488326,0,1
+IMG_000590.png,1,0.95325905,1,1
+IMG_000342.png,1,0.8786827,1,1
+IMG_001213.png,0,0.0063149747,0,1
+IMG_000075.png,0,0.18751769,0,1
+IMG_000608.png,0,0.09344582,0,1
+IMG_000493.png,1,0.74505854,1,1
+IMG_000630.png,0,0.37733248,0,1
+IMG_001676.png,1,0.50721115,1,1
+IMG_001102.png,1,0.90345204,1,1
+IMG_000095.png,0,0.0039746515,0,1
+IMG_001303.png,0,0.02584564,0,1
+IMG_001266.png,0,0.0027153727,0,1
+IMG_000755.png,1,0.5398157,1,1
+IMG_001295.png,1,0.89617956,1,1
+IMG_000832.png,1,0.985641,1,1
+IMG_001705.png,0,0.017828463,0,1
+IMG_001306.png,0,0.0074857906,0,1
+IMG_000246.png,0,0.33929592,0,1
+IMG_001530.png,1,0.72100955,1,1
+IMG_000970.png,0,0.32502642,0,1
+IMG_000059.png,1,0.9853226,1,1
+IMG_001149.png,1,0.92740005,1,1
+IMG_001200.png,1,0.95928955,1,1
+IMG_001055.png,1,0.76670074,1,1
+IMG_000995.png,0,0.8288552,1,0
+IMG_000038.png,0,0.20308095,0,1
+IMG_000524.png,0,0.005141989,0,1
+IMG_001568.png,0,0.14497586,0,1
+IMG_000122.png,0,0.051262774,0,1
+IMG_000333.png,1,0.8129171,1,1
+IMG_001109.png,0,0.18362695,0,1
+IMG_000698.png,0,0.01703381,0,1
+IMG_001573.png,1,0.9943408,1,1
+IMG_001625.png,1,0.91411126,1,1
+IMG_000509.png,0,0.0028896236,0,1
+IMG_001448.png,1,0.9428977,1,1
+IMG_000331.png,1,0.9803683,1,1
+IMG_000008.png,0,0.038054988,0,1
+IMG_000521.png,0,0.0010172316,0,1
+IMG_000012.png,1,0.9812463,1,1
+IMG_000780.png,1,0.6871019,1,1
+IMG_000428.png,1,0.49723867,0,0
+IMG_000463.png,0,0.016233142,0,1
+IMG_001423.png,1,0.8972441,1,1
+IMG_000287.png,1,0.61366016,1,1
+IMG_001173.png,1,0.17359304,0,0
+IMG_001357.png,1,0.6145142,1,1
+IMG_001329.png,1,0.9680075,1,1
+IMG_001119.png,0,0.013847093,0,1
+IMG_001675.png,0,0.01776683,0,1
+IMG_000877.png,0,0.9286344,1,0
+IMG_000402.png,0,0.25376308,0,1
+IMG_001176.png,1,0.9541638,1,1
+IMG_000068.png,0,0.0027813588,0,1
+IMG_000091.png,0,0.06692752,0,1
+IMG_000600.png,0,0.68098706,1,0
+IMG_000765.png,1,0.9324583,1,1
+IMG_000965.png,0,0.0155419195,0,1
+IMG_000361.png,1,0.4985782,0,0
+IMG_000414.png,1,0.95493746,1,1
+IMG_000969.png,0,0.06441665,0,1
+IMG_001087.png,0,0.0050179944,0,1
+IMG_000124.png,1,0.6126341,1,1
+IMG_000013.png,0,0.14956698,0,1
+IMG_001140.png,1,0.98292345,1,1
+IMG_001088.png,1,0.9412705,1,1
+IMG_001655.png,0,0.10415509,0,1
+IMG_000720.png,1,0.5776679,1,1
+IMG_001687.png,0,0.054884706,0,1
+IMG_000654.png,1,0.80313796,1,1
+IMG_000200.png,0,0.016887484,0,1
+IMG_001131.png,0,0.59535867,1,0
+IMG_000236.png,1,0.9608375,1,1
+IMG_001004.png,1,0.91360044,1,1
+IMG_000869.png,1,0.9747172,1,1
+IMG_001630.png,0,0.0015267566,0,1
+IMG_000374.png,1,0.32337222,0,0
+IMG_001203.png,0,0.00011447017,0,1
+IMG_000853.png,0,0.06780861,0,1
+IMG_000638.png,0,0.02331572,0,1
+IMG_000620.png,1,0.9309563,1,1
+IMG_000167.png,1,0.9887361,1,1
+IMG_000811.png,0,0.26473084,0,1
+IMG_001061.png,1,0.905426,1,1
+IMG_000456.png,0,0.00062740117,0,1
+IMG_000438.png,1,0.7869287,1,1
+IMG_000292.png,1,0.9418937,1,1
+IMG_000644.png,0,0.5747625,1,0
+IMG_000491.png,0,0.014190746,0,1
+IMG_000564.png,0,0.0036469798,0,1
+IMG_000738.png,0,0.8187067,1,0
+IMG_000886.png,1,0.7505375,1,1
+IMG_000387.png,0,0.24593168,0,1
+IMG_000492.png,0,0.33065897,0,1
+IMG_001057.png,1,0.9879611,1,1
+IMG_001195.png,0,0.0053326027,0,1
+IMG_000088.png,1,0.91581327,1,1
+IMG_000014.png,0,0.08517947,0,1
+IMG_000830.png,0,0.02413497,0,1
+IMG_000779.png,0,0.021322682,0,1
+IMG_001510.png,0,0.06587305,0,1
+IMG_000556.png,0,0.019615667,0,1
+IMG_000744.png,1,0.8163302,1,1
+IMG_001059.png,0,0.012555552,0,1
+IMG_001013.png,1,0.12594076,0,0
+IMG_000901.png,1,0.9905481,1,1
+IMG_000983.png,0,0.13618241,0,1
+IMG_001359.png,1,0.90301836,1,1
+IMG_001604.png,0,0.0092756525,0,1
+IMG_001050.png,0,0.41582817,0,1
+IMG_000662.png,0,0.0009655981,0,1
+IMG_000225.png,0,0.059564617,0,1
+IMG_001261.png,0,0.00012916393,0,1
+IMG_001401.png,1,0.8134201,1,1
+IMG_001136.png,0,0.03423228,0,1
+IMG_000031.png,1,0.9828577,1,1
+IMG_001547.png,0,0.028171018,0,1
+IMG_000023.png,1,0.96932787,1,1
+IMG_000261.png,1,0.89618427,1,1
+IMG_001125.png,1,0.9938845,1,1
+IMG_000210.png,1,0.9844753,1,1
+IMG_000305.png,0,0.96544015,1,0
+IMG_001426.png,0,0.23876508,0,1
+IMG_001204.png,1,0.9547577,1,1
+IMG_000081.png,1,0.88376915,1,1
+IMG_001683.png,1,0.7803761,1,1
+IMG_000069.png,1,0.9368211,1,1

model_training/src/__init__.py

@@ -0,0 +1 @@
+# src package

model_training/src/config.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import List
+
+import torch
+
+
+@dataclass
+class Config:
+    # ── Data paths ────────────────────────────────────────────────────────
+    csv_path:            str = "../../data/train_val.csv"
+    image_dir:           str = "../../data/images"
+    submission_test_dir: str = "../../data/test_images"
+    output_dir:          str = "results"
+    results_log_path:    str = "results_log.csv"   # global run log (one row per training run)
+
+    # ── Reproducibility ──────────────────────────────────────────────────
+    seed: int = 42
+
+    # ── Image / DataLoader ───────────────────────────────────────────────
+    img_size:    int = 224   # torchxrayvision DenseNet-121 native resolution
+    batch_size:  int = 32
+    num_workers: int = 4
+
+    # ── Train / val / test split ─────────────────────────────────────────
+    val_size:  float = 0.15
+    test_size: float = 0.15
+
+    # ── Training schedule (two-stage) ────────────────────────────────────
+    frozen_epochs:   int = 3       # stage 1: head-only warmup
+    finetune_epochs: int = 22      # stage 2: full unfreeze with cosine LR
+    early_stop_patience: int = 6   # early stop on val AUC during stage 2
+
+    # ── Optimiser ────────────────────────────────────────────────────────
+    head_lr:      float = 3e-4     # classifier LR (both stages)
+    backbone_lr:  float = 1e-4     # features LR (stage 2 only)
+    weight_decay: float = 1e-4
+    grad_clip:    float = 1.0
+
+    # ── Data augmentation ────────────────────────────────────────────────
+    # Mixup: interpolates two samples and their labels in every training batch.
+    #   mixup_alpha > 0 enables it; λ ~ Beta(α, α).  0 = disabled.
+    #   Typical range: 0.2 – 0.4.
+    mixup_alpha:     float = 0.0
+    # Label smoothing: prevents overconfidence by softening hard {0,1} targets.
+    #   y_smooth = y*(1-ε) + 0.5*ε.  0 = disabled.  Typical range: 0.05 – 0.15.
+    label_smoothing: float = 0.0
+
+    # ── Architecture ─────────────────────────────────────────────────────
+    # Options: "densenet121" | "rad-dino" | "mobilenet_v3_large" | "efficientnet_b0" | "efficientnet_b3"
+    # densenet121        — torchxrayvision DenseNet-121, pretrained on ~1M chest X-rays (recommended)
+    # rad-dino           — microsoft/rad-dino, DINOv2 ViT-B/14 pretrained on ~1M chest X-rays;
+    #                      use img_size=518 (native: 37×37 patches at 14 px); 12 frozen_blocks max
+    # mobilenet_v3_large — torchvision MobileNetV3-Large, pretrained on ImageNet (faster, lighter)
+    # efficientnet_b0    — torchvision EfficientNet-B0,  pretrained on ImageNet (good accuracy/size trade-off)
+    # efficientnet_b3    — torchvision EfficientNet-B3,  pretrained on ImageNet (higher accuracy, more params)
+    backbone: str = "efficientnet_b0"
+
+    # ── Ensemble ─────────────────────────────────────────────────────────
+    # True:  train one model per entry in `seeds` and average predictions
+    # False: train a single model using only `seed` (faster experimentation)
+    use_ensemble: bool = True
+
+    # ── Multi-seed ensemble ──────────────────────────────────────────────
+    seeds: List[int] = field(default_factory=lambda: [42, 7, 2024])
+
+    # ── Loss function ─────────────────────────────────────────────────────
+    # False: standard BCE  |  True: 0.5*BCE + 0.5*(1 - soft_composite)
+    use_composite_loss:    bool  = False
+    # Blend weight α: α·BCE + (1-α)·(1-soft_composite).  0 = pure composite, 1 = pure BCE.
+    composite_loss_alpha:  float = 0.5
+    # Temperature for the pairwise-sigmoid soft-AUC term (higher → sharper ranking signal)
+    composite_loss_gamma:  float = 1.0
+
+    # ── Inference ────────────────────────────────────────────────────────
+    tta_passes:  int = 6           # number of deterministic TTA transforms (max 6)
+    n_bootstrap: int = 1000        # bootstrap iterations for threshold stabilisation
+
+    # ── Device (auto-detected) ───────────────────────────────────────────
+    device: str = (
+        "cuda" if torch.cuda.is_available()
+        else "mps" if torch.backends.mps.is_available()
+        else "cpu"
+    )
+
+    def setup(self) -> "Config":
+        """Create output directory and return self (for chaining)."""
+        os.makedirs(self.output_dir, exist_ok=True)
+        return self
+
+
+# Global singleton — import and use directly, or override fields before training
+CFG = Config().setup()

model_training/src/data.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import os
+from typing import Tuple
+
+import numpy as np
+import pandas as pd
+from sklearn.model_selection import train_test_split
+
+from src.config import CFG
+
+
+# ---------------------------------------------------------------------------
+# Column auto-detection
+# ---------------------------------------------------------------------------
+FILENAME_CANDIDATES = [
+    "image_name", "filename", "file", "image", "image_id", "img", "name",
+    "image index", "image_index",                    # NIH ChestX-ray14
+]
+LABEL_CANDIDATES = [
+    "label", "cardiomegaly", "class", "target", "y",
+    "finding_labels", "finding labels", "finding",   # NIH ChestX-ray14
+    "labels",
+]
+POSITIVE_KEYWORD = "cardiomegaly"
+
+
+def _autodetect(df: pd.DataFrame, candidates: list[str]) -> str:
+    """Return the first column in *df* whose lowercase name is in *candidates*."""
+    lower = {c.lower(): c for c in df.columns}
+    for cand in candidates:
+        if cand in lower:
+            return lower[cand]
+    raise ValueError(f"None of {candidates} found in columns: {list(df.columns)}")
+
+
+def _coerce_to_binary(series: pd.Series) -> pd.Series:
+    """Map mixed label encodings (0/1, 'cardiomegaly', 'no finding', bool, ...) to 0/1."""
+    def to_int(v):
+        if pd.isna(v):
+            return 0
+        if isinstance(v, (int, np.integer)):
+            return int(v != 0)
+        if isinstance(v, (float, np.floating)):
+            return int(v != 0)
+        if isinstance(v, bool):
+            return int(v)
+        s = str(v).strip().lower()
+        if s in {"1", "true", "yes", "y", "positive", "pos"}:
+            return 1
+        if s in {"0", "false", "no", "n", "negative", "neg", "no finding", ""}:
+            return 0
+        return int(POSITIVE_KEYWORD in s)
+    return series.apply(to_int).astype(int)
+
+
+def _resolve_filenames(df: pd.DataFrame, filename_col: str, image_dir: str) -> pd.DataFrame:
+    """Add an `image_path` column. Drops rows whose file cannot be found.
+
+    Tolerates different case, trailing spaces, and missing/wrong extensions.
+    """
+    disk: dict[str, str] = {}
+    for entry in os.scandir(image_dir):
+        if not entry.is_file():
+            continue
+        name = entry.name
+        disk[name.lower()] = name
+        stem = os.path.splitext(name)[0].lower()
+        disk.setdefault(stem, name)
+
+    resolved, missing = [], []
+    for fn in df[filename_col].astype(str):
+        raw = fn.strip()
+        raw_l = raw.lower()
+        hit = disk.get(raw_l) or disk.get(os.path.splitext(raw_l)[0])
+        if hit is None:
+            for ext in (".png", ".jpg", ".jpeg"):
+                if raw_l + ext in disk:
+                    hit = disk[raw_l + ext]
+                    break
+        if hit is None:
+            missing.append(raw)
+            resolved.append(None)
+        else:
+            resolved.append(os.path.join(image_dir, hit))
+
+    df = df.copy()
+    df["image_path"] = resolved
+    keep = df["image_path"].notna()
+    if (~keep).any():
+        print(f"Warning: {(~keep).sum()} rows dropped (file not found). Examples: {missing[:5]}")
+    return df[keep].reset_index(drop=True)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+def load_labels(csv_path: str, image_dir: str) -> pd.DataFrame:
+    """Read CSV, auto-detect filename + label columns, coerce labels, resolve paths.
+
+    Returned DataFrame columns: filename, label, image_path
+    """
+    df = pd.read_csv(csv_path)
+    fn_col = _autodetect(df, FILENAME_CANDIDATES)
+    lb_col = _autodetect(df, LABEL_CANDIDATES)
+    print(f"Detected filename column: {fn_col!r}   label column: {lb_col!r}")
+
+    df = df[[fn_col, lb_col]].rename(columns={fn_col: "filename", lb_col: "label"})
+    df["label"] = _coerce_to_binary(df["label"])
+    df = _resolve_filenames(df, "filename", image_dir)
+    df = df.drop_duplicates(subset=["filename"]).reset_index(drop=True)
+
+    if len(df) == 0:
+        raise ValueError("No valid labelled images found.")
+
+    n_pos = int(df["label"].sum())
+    n_neg = int((df["label"] == 0).sum())
+    print(f"Loaded {len(df)} labelled images   pos={n_pos}   neg={n_neg}")
+    return df
+
+
+def split_dataframe(
+    df: pd.DataFrame,
+    val_size: float | None = None,
+    test_size: float | None = None,
+    seed: int | None = None,
+) -> Tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+    """Stratified train / val / test split.
+
+    Falls back to CFG values when parameters are not supplied.
+    """
+    val_size  = val_size  if val_size  is not None else CFG.val_size
+    test_size = test_size if test_size is not None else CFG.test_size
+    seed      = seed      if seed      is not None else CFG.seed
+
+    train_tmp_df, test_df = train_test_split(
+        df, test_size=test_size, stratify=df["label"], random_state=seed,
+    )
+    rel_val = val_size / (1.0 - test_size)
+    train_df, val_df = train_test_split(
+        train_tmp_df, test_size=rel_val,
+        stratify=train_tmp_df["label"], random_state=seed,
+    )
+    return (
+        train_df.reset_index(drop=True),
+        val_df.reset_index(drop=True),
+        test_df.reset_index(drop=True),
+    )

model_training/src/dataset.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+import torch
+from PIL import Image
+from torch.utils.data import Dataset
+import torchvision.transforms as T
+
+import torchxrayvision as xrv
+
+
+# ---------------------------------------------------------------------------
+# Normalisation functions (one per backbone family)
+# ---------------------------------------------------------------------------
+def xrv_normalize_np(pil_img: Image.Image) -> torch.Tensor:
+    """PIL grayscale → (1, H, W) float tensor in [-1024, 1024] (torchxrayvision)."""
+    arr = np.array(pil_img, dtype=np.float32)          # (H, W) in [0, 255]
+    arr = xrv.datasets.normalize(arr, 255)             # → [-1024, 1024]
+    arr = arr[None, ...]                               # (1, H, W)
+    return torch.from_numpy(arr).float()
+
+
+_IMAGENET_MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32).reshape(3, 1, 1)
+_IMAGENET_STD  = np.array([0.229, 0.224, 0.225], dtype=np.float32).reshape(3, 1, 1)
+
+
+def imagenet_normalize_np(pil_img: Image.Image) -> torch.Tensor:
+    """PIL grayscale → (3, H, W) float tensor normalized with ImageNet stats.
+
+    The single grayscale channel is replicated to 3 channels so that ImageNet-
+    pretrained backbones (MobileNet, EfficientNet) receive the expected input shape.
+    """
+    arr = np.array(pil_img, dtype=np.float32) / 255.0           # [0, 1]
+    arr = np.stack([arr, arr, arr], axis=0)                      # (3, H, W)
+    arr = (arr - _IMAGENET_MEAN) / _IMAGENET_STD
+    return torch.from_numpy(arr).float()
+
+
+def get_normalize_fn(backbone: str):
+    """Return the correct normalization callable for the given backbone name.
+
+    "densenet121" / "densenet121-res224-all"
+        → xrv_normalize_np  (grayscale, [-1024, 1024])
+    "rad-dino"
+        → imagenet_normalize_np  (3-ch RGB replicated, ImageNet stats)
+          RAD-DINO is a ViT-B/14; feed at 518×518 for best accuracy.
+    all other torchvision backbones
+        → imagenet_normalize_np
+    """
+    if backbone in ("densenet121", "densenet121-res224-all"):
+        return xrv_normalize_np
+    return imagenet_normalize_np
+
+
+# ---------------------------------------------------------------------------
+# Labelled dataset (train / val / test)
+# ---------------------------------------------------------------------------
+class ChestXrayDataset(Dataset):
+    """Returns (image_tensor, label, filename) triples.
+
+    backbone controls the normalization applied after PIL transforms:
+        "densenet121"         → single-channel tensor in [-1024, 1024] (xrv)
+        any torchvision model → 3-channel tensor with ImageNet normalization
+    """
+
+    def __init__(
+        self,
+        df: pd.DataFrame,
+        pil_transform=None,
+        use_erasing: bool = False,
+        backbone: str | None = None,
+    ) -> None:
+        from src.config import CFG
+        self.df = df.reset_index(drop=True)
+        self.pil_transform = pil_transform
+        self.use_erasing = use_erasing
+        self._normalize = get_normalize_fn(backbone or CFG.backbone)
+        self._erasing = T.RandomErasing(
+            p=0.5, scale=(0.02, 0.08), ratio=(0.3, 3.3), value=0
+        )
+
+    def __len__(self) -> int:
+        return len(self.df)
+
+    def __getitem__(self, idx: int):
+        row = self.df.iloc[idx]
+        img = Image.open(row["image_path"]).convert("L")
+        if self.pil_transform is not None:
+            img = self.pil_transform(img)
+        normalize = getattr(self, "_normalize", xrv_normalize_np)
+        tensor = normalize(img)
+        if self.use_erasing:
+            tensor = self._erasing(tensor)
+        label = torch.tensor(float(row["label"]), dtype=torch.float32)
+        return tensor, label, row["filename"]
+
+
+# ---------------------------------------------------------------------------
+# TTA dataset — flexible source (DataFrame with image_path, or external dir)
+# ---------------------------------------------------------------------------
+class TTADataset(Dataset):
+    """Used by inference passes (one TTA transform per pass)."""
+
+    def __init__(
+        self,
+        df: pd.DataFrame,
+        pil_transform,
+        image_dir: Optional[str] = None,
+        backbone: str | None = None,
+    ) -> None:
+        from src.config import CFG
+        self.df = df.reset_index(drop=True)
+        self.pil_transform = pil_transform
+        self.image_dir = image_dir
+        self._normalize = get_normalize_fn(backbone or CFG.backbone)
+
+    def __len__(self) -> int:
+        return len(self.df)
+
+    def __getitem__(self, idx: int):
+        row = self.df.iloc[idx]
+        if "image_path" in row and pd.notna(row.get("image_path")):
+            path = row["image_path"]
+        else:
+            path = os.path.join(self.image_dir, row["filename"])
+        img = Image.open(path).convert("L")
+        img = self.pil_transform(img)
+        normalize = getattr(self, "_normalize", xrv_normalize_np)
+        tensor = normalize(img)
+        label = float(row["label"]) if "label" in row and not pd.isna(row.get("label", np.nan)) else 0.0
+        name = row["filename"] if "filename" in row else os.path.basename(path)
+        return tensor, torch.tensor(label, dtype=torch.float32), name
+
+
+# ---------------------------------------------------------------------------
+# Submission dataset (unlabelled images in a flat directory)
+# ---------------------------------------------------------------------------
+class SubmissionDataset(Dataset):
+    """Unlabelled test images for final inference.
+
+    Returns (image_tensor, filename).
+    """
+
+    def __init__(
+        self,
+        image_dir: str,
+        pil_transform=None,
+        backbone: str | None = None,
+    ) -> None:
+        from src.config import CFG
+        self.image_dir = image_dir
+        self.pil_transform = pil_transform
+        self._normalize = get_normalize_fn(backbone or CFG.backbone)
+        self.image_files = sorted(
+            f for f in os.listdir(image_dir)
+            if f.lower().endswith((".png", ".jpg", ".jpeg"))
+        )
+
+    def __len__(self) -> int:
+        return len(self.image_files)
+
+    def __getitem__(self, idx: int):
+        fname = self.image_files[idx]
+        img = Image.open(os.path.join(self.image_dir, fname)).convert("L")
+        if self.pil_transform is not None:
+            img = self.pil_transform(img)
+        normalize = getattr(self, "_normalize", xrv_normalize_np)
+        tensor = normalize(img)
+        return tensor, fname

model_training/src/model.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+from typing import List
+
+import torch
+import torch.nn as nn
+import torchxrayvision as xrv
+
+
+# ---------------------------------------------------------------------------
+# RAD-DINO wrapper
+# ---------------------------------------------------------------------------
+class RadDinoWrapper(nn.Module):
+    """microsoft/rad-dino — DINOv2 ViT-B/14 pretrained on ~1 M chest X-rays.
+
+    Wraps the HuggingFace model to expose the same ``.features`` / ``.classifier``
+    contract used by every other backbone, so freeze helpers and the two-stage
+    optimiser work without modification.
+
+    Architecture
+    ────────────
+    .features   — the full Dinov2Model (embeddings + 12 transformer blocks + layernorm)
+    .classifier — nn.Linear(hidden_size=768, out_features=1)
+
+    Forward pass
+    ────────────
+    x : (B, 3, H, W) float tensor — ImageNet-normalised, any multiple of 14 px.
+        Recommended resolution: 518 × 518 (native: 37 × 37 patches at 14 px).
+    Returns (B,) logit tensor.
+
+    Freeze / unfreeze
+    ─────────────────
+    freeze_backbone()    → freezes .features (all 12 blocks + embeddings)
+    partial_unfreeze(N)  → unfreeze last (12 − N) blocks + layernorm;
+                          keep embeddings + first N blocks frozen.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        from transformers import AutoModel  # lazy — only loaded when this backbone is used
+        dinov2 = AutoModel.from_pretrained("microsoft/rad-dino")
+        self.features   = dinov2
+        self.classifier = nn.Linear(dinov2.config.hidden_size, 1)
+        nn.init.trunc_normal_(self.classifier.weight, std=0.02)
+        nn.init.zeros_(self.classifier.bias)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        out = self.features(pixel_values=x)   # Dinov2ModelOutput
+        cls = out.last_hidden_state[:, 0]     # CLS token  (B, 768)
+        return self.classifier(cls)           # (B, 1)
+
+
+# ---------------------------------------------------------------------------
+# Backbone factory
+# ---------------------------------------------------------------------------
+def build_model(backbone: str | None = None) -> nn.Module:
+    """Build a backbone model for Cardiomegaly classification.
+
+    backbone options (also set via CFG.backbone):
+        "densenet121"        — torchxrayvision DenseNet-121, pretrained on ~1M chest
+                               X-rays; outputs raw Cardiomegaly logit via pathology index.
+        "rad-dino"           — microsoft/rad-dino, DINOv2 ViT-B/14 pretrained on ~1M
+                               chest X-rays (HuggingFace); 518×518 recommended input.
+        "mobilenet_v3_large" — torchvision MobileNetV3-Large (ImageNet); final linear
+                               replaced with a single-output head.
+        "efficientnet_b0"    — torchvision EfficientNet-B0  (ImageNet); same replacement.
+        "efficientnet_b3"    — torchvision EfficientNet-B3  (ImageNet); same replacement.
+
+    All returned models expose .features and .classifier so that freeze_backbone()
+    and the two-stage optimizer in train_one_seed() work unchanged.
+    Input tensor format differs by backbone — use dataset.get_normalize_fn(backbone).
+    """
+    from src.config import CFG  # lazy to avoid circular import at module load
+    backbone = backbone or CFG.backbone
+
+    if backbone in ("densenet121", "densenet121-res224-all"):
+        model = xrv.models.DenseNet(weights="densenet121-res224-all")
+        model.op_threshs = None      # raw logits at every output
+        model.apply_sigmoid = False  # belt + suspenders
+        return model
+
+    if backbone == "rad-dino":
+        return RadDinoWrapper()
+
+    import torchvision.models as tvm
+
+    if backbone == "mobilenet_v3_large":
+        model = tvm.mobilenet_v3_large(weights=tvm.MobileNet_V3_Large_Weights.IMAGENET1K_V2)
+        in_features = model.classifier[-1].in_features
+        model.classifier[-1] = nn.Linear(in_features, 1)
+        return model
+
+    if backbone in ("efficientnet_b0", "efficientnet_b3"):
+        if backbone == "efficientnet_b0":
+            model = tvm.efficientnet_b0(weights=tvm.EfficientNet_B0_Weights.IMAGENET1K_V1)
+        else:
+            model = tvm.efficientnet_b3(weights=tvm.EfficientNet_B3_Weights.IMAGENET1K_V1)
+        in_features = model.classifier[-1].in_features
+        model.classifier[-1] = nn.Linear(in_features, 1)
+        return model
+
+    raise ValueError(
+        f"Unknown backbone: {backbone!r}. "
+        "Choose from: densenet121, rad-dino, mobilenet_v3_large, efficientnet_b0, efficientnet_b3"
+    )
+
+
+def cardio_logit(model: nn.Module, x: torch.Tensor) -> torch.Tensor:
+    """Forward pass returning a (B,) tensor of raw logits for Cardiomegaly.
+
+    For torchxrayvision DenseNet the logit is extracted from the pathology head.
+    For all other backbones (MobileNet, EfficientNet, RadDinoWrapper) the model
+    outputs (B, 1) which is squeezed to (B,).
+    """
+    if isinstance(model, xrv.models.DenseNet):
+        out = model(x)                                       # (B, num_pathologies)
+        idx = model.pathologies.index("Cardiomegaly")
+        return out[:, idx]
+    return model(x).squeeze(1)                              # (B, 1) → (B,)
+
+
+# ---------------------------------------------------------------------------
+# Backbone management helpers
+# ---------------------------------------------------------------------------
+def freeze_backbone(model: nn.Module) -> nn.Module:
+    """Freeze all params in .features; keep .classifier trainable."""
+    for p in model.features.parameters():
+        p.requires_grad = False
+    for p in model.classifier.parameters():
+        p.requires_grad = True
+    return model
+
+
+def unfreeze_all(model: nn.Module) -> nn.Module:
+    """Unfreeze every parameter. Kept for backwards compatibility; prefer partial_unfreeze."""
+    for p in model.parameters():
+        p.requires_grad = True
+    return model
+
+
+# DenseNet-121 block groups: (block_name, transition_name) for blocks 1–4
+_DENSENET_BLOCK_GROUPS = [
+    ("denseblock1", "transition1"),
+    ("denseblock2", "transition2"),
+    ("denseblock3", "transition3"),
+    ("denseblock4", "norm5"),
+]
+
+
+def partial_unfreeze(model: nn.Module, frozen_blocks: int = 0) -> nn.Module:
+    """Selectively unfreeze the model for stage-2 fine-tuning.
+
+    frozen_blocks — how many feature blocks to keep frozen:
+        0  → unfreeze everything (same as unfreeze_all)
+
+    DenseNet-121 (4 dense block groups):
+        1  → keep denseblock1 (+transition1) frozen
+        2  → keep denseblock1–2 frozen
+        3  → keep denseblock1–3 frozen
+        4  → keep all dense blocks frozen (only classifier trains)
+
+    RAD-DINO / ViT-B (12 transformer blocks):
+        1–12 → keep embeddings + first N transformer blocks frozen
+               (last 12−N blocks + layernorm are unfrozen)
+        ≥12  → keep all transformer blocks frozen (only classifier trains)
+
+    torchvision models (MobileNet, EfficientNet):
+        N    → freeze first N indexed children of model.features.
+    """
+    for p in model.parameters():
+        p.requires_grad = True
+
+    if frozen_blocks <= 0:
+        return model
+
+    if isinstance(model, xrv.models.DenseNet):
+        frozen_names: set[str] = set()
+        for i in range(min(frozen_blocks, len(_DENSENET_BLOCK_GROUPS))):
+            frozen_names.update(_DENSENET_BLOCK_GROUPS[i])
+        for name, module in model.features.named_children():
+            if name in frozen_names:
+                for p in module.parameters():
+                    p.requires_grad = False
+
+    elif isinstance(model, RadDinoWrapper):
+        # Always freeze the patch/position embeddings
+        for p in model.features.embeddings.parameters():
+            p.requires_grad = False
+        # Freeze the first `frozen_blocks` transformer blocks
+        encoder_layers = model.features.encoder.layer
+        for block in encoder_layers[:frozen_blocks]:
+            for p in block.parameters():
+                p.requires_grad = False
+
+    else:
+        for module in list(model.features.children())[:frozen_blocks]:
+            for p in module.parameters():
+                p.requires_grad = False
+
+    return model
+
+
+def trainable_params(model: nn.Module) -> List[nn.Parameter]:
+    """List of parameters with `requires_grad=True` (for optimiser construction)."""
+    return [p for p in model.parameters() if p.requires_grad]

model_training/src/train.py

@@ -0,0 +1,697 @@
+from __future__ import annotations
+
+import copy
+import json
+import os
+from typing import List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from sklearn.metrics import confusion_matrix, roc_auc_score
+from torch.utils.data import DataLoader
+
+from src.config import CFG
+from src.dataset import ChestXrayDataset, SubmissionDataset, TTADataset
+from src.model import (
+    build_model,
+    cardio_logit,
+    freeze_backbone,
+    partial_unfreeze,
+    trainable_params,
+    unfreeze_all,
+)
+from src.transforms import make_tta_transforms
+from src.utils import free_device_cache, log_run, set_seed
+
+
+# ---------------------------------------------------------------------------
+# Mixup helper
+# ---------------------------------------------------------------------------
+def mixup_data(
+    x: torch.Tensor,
+    y: torch.Tensor,
+    alpha: float = 0.4,
+) -> Tuple[torch.Tensor, torch.Tensor]:
+    """Return a randomly mixed batch and the corresponding soft labels.
+
+    λ ~ Beta(α, α).  When α ≤ 0 the original batch is returned unchanged.
+
+    Args:
+        x:     Image tensor  (B, C, H, W)  on the training device.
+        y:     Label tensor  (B,)  – may already be soft (e.g. after smoothing).
+        alpha: Beta distribution parameter.  Typical: 0.2 – 0.4.
+    """
+    if alpha <= 0:
+        return x, y
+    lam = float(np.random.beta(alpha, alpha))
+    idx = torch.randperm(x.size(0), device=x.device)
+    mixed_x = lam * x + (1.0 - lam) * x[idx]
+    mixed_y = lam * y + (1.0 - lam) * y[idx]
+    return mixed_x, mixed_y
+
+
+# ---------------------------------------------------------------------------
+# Differentiable composite loss
+# ---------------------------------------------------------------------------
+class SoftCompositeLoss(nn.Module):
+    """Differentiable approximation of composite = 0.5·AUC + 0.25·sens + 0.25·spec.
+
+    Minimises ``1 - soft_composite``, blended with standard BCE for stability.
+
+    Soft-AUC
+        Pairwise sigmoid over all (positive, negative) logit pairs in the batch:
+        ``soft_auc = mean( σ(γ · (logit⁺ − logit⁻)) )``
+        where γ (``auc_gamma``) is a sharpness temperature.
+
+    Soft-sens / soft-spec
+        ``soft_sens = mean( σ(logit) | y=1 )``
+        ``soft_spec = mean( 1 − σ(logit) | y=0 )``
+
+    Total loss
+        ``α · BCE  +  (1 − α) · (1 − soft_composite)``
+
+    Args:
+        alpha:     Weight of BCE in the blend (0 = pure composite, 1 = pure BCE).
+        auc_gamma: Temperature for the pairwise sigmoid (higher → sharper AUC signal).
+        eps:       Numerical stability floor.
+    """
+
+    def __init__(self, alpha: float = 0.5, auc_gamma: float = 1.0, eps: float = 1e-7):
+        super().__init__()
+        self.alpha     = alpha
+        self.auc_gamma = auc_gamma
+        self.eps       = eps
+        self._bce      = nn.BCEWithLogitsLoss()
+
+    def forward(self, logit: torch.Tensor, target: torch.Tensor) -> torch.Tensor:
+        bce_loss = self._bce(logit, target)
+
+        prob     = torch.sigmoid(logit)
+        # Use > 0.5 so the masks work correctly for both hard labels {0,1}
+        # and soft targets produced by mixup or label smoothing.
+        pos_mask = (target > 0.5)
+        neg_mask = ~pos_mask
+        n_pos    = pos_mask.sum()
+        n_neg    = neg_mask.sum()
+
+        # ── Soft AUC (pairwise) ──────────────────────────────────────────────
+        if n_pos > 0 and n_neg > 0:
+            pos_logits = logit[pos_mask]                                  # (n_pos,)
+            neg_logits = logit[neg_mask]                                  # (n_neg,)
+            diff       = pos_logits.unsqueeze(1) - neg_logits.unsqueeze(0)  # (n_pos, n_neg)
+            soft_auc   = torch.sigmoid(self.auc_gamma * diff).mean()
+        else:
+            soft_auc = torch.tensor(0.5, device=logit.device, dtype=logit.dtype)
+
+        # ── Soft sensitivity / specificity ──────────────────────────────────
+        soft_sens = prob[pos_mask].mean() if n_pos > 0 else torch.tensor(
+            0.0, device=logit.device, dtype=logit.dtype)
+        soft_spec = (1.0 - prob[neg_mask]).mean() if n_neg > 0 else torch.tensor(
+            0.0, device=logit.device, dtype=logit.dtype)
+
+        soft_composite  = 0.5 * soft_auc + 0.25 * soft_sens + 0.25 * soft_spec
+        composite_loss  = 1.0 - soft_composite
+
+        return self.alpha * bce_loss + (1.0 - self.alpha) * composite_loss
+
+
+# ---------------------------------------------------------------------------
+# Epoch runner
+# ---------------------------------------------------------------------------
+def run_one_epoch(
+    model: nn.Module,
+    loader: DataLoader,
+    criterion: Optional[nn.Module] = None,
+    optimizer: Optional[optim.Optimizer] = None,
+    scaler: Optional[torch.cuda.amp.GradScaler] = None,
+    grad_clip: Optional[float] = None,
+    mixup_alpha: float = 0.0,
+    label_smoothing: float = 0.0,
+) -> dict:
+    """Single forward pass over *loader*.
+
+    Pass ``optimizer=None`` for evaluation (mixup and smoothing are skipped).
+    Expects (image, label, name) batches. Uses CUDA AMP when available.
+
+    Hard original labels are always accumulated for metric computation;
+    the (potentially mixed + smoothed) soft labels are only used for the loss.
+    """
+    is_train = optimizer is not None
+    model.train(is_train)
+
+    losses, logits_all, labels_all, names_all = [], [], [], []
+    pin = (CFG.device == "cuda")
+    grad_clip = grad_clip if grad_clip is not None else CFG.grad_clip
+
+    amp_ctx = torch.cuda.amp.autocast(enabled=(CFG.device == "cuda"))
+    for x, y, names in loader:
+        x = x.to(CFG.device, non_blocking=pin)
+        y = y.to(CFG.device, non_blocking=pin)
+
+        # Keep hard labels for metric accumulation (before any augmentation)
+        y_hard = y.detach().clone()
+
+        if is_train:
+            # Mixup: interpolate two samples + their labels in-place
+            if mixup_alpha > 0.0:
+                x, y = mixup_data(x, y, alpha=mixup_alpha)
+            # Label smoothing: y_smooth = y*(1-ε) + 0.5*ε
+            if label_smoothing > 0.0:
+                y = y * (1.0 - label_smoothing) + 0.5 * label_smoothing
+
+        with torch.set_grad_enabled(is_train):
+            with amp_ctx:
+                logit = cardio_logit(model, x)
+                loss = criterion(logit, y) if criterion is not None else None
+
+            if is_train:
+                optimizer.zero_grad(set_to_none=True)
+                if scaler is not None and scaler.is_enabled():
+                    scaler.scale(loss).backward()
+                    scaler.unscale_(optimizer)
+                    torch.nn.utils.clip_grad_norm_(trainable_params(model), grad_clip)
+                    scaler.step(optimizer)
+                    scaler.update()
+                else:
+                    loss.backward()
+                    torch.nn.utils.clip_grad_norm_(trainable_params(model), grad_clip)
+                    optimizer.step()
+
+        if loss is not None:
+            losses.append(loss.item())
+        logits_all.append(logit.detach().float().cpu().numpy())
+        labels_all.append(y_hard.float().cpu().numpy())   # always hard labels
+        names_all.extend(list(names))
+
+    y_true  = np.concatenate(labels_all)
+    y_logit = np.concatenate(logits_all)
+    y_prob  = 1.0 / (1.0 + np.exp(-y_logit))
+    auc     = roc_auc_score(y_true, y_prob) if len(np.unique(y_true)) > 1 else float("nan")
+
+    # Per-epoch metrics at threshold=0.5 (used for progress logging)
+    y_pred = (y_prob >= 0.5).astype(int)
+    tn, fp, fn, tp = confusion_matrix(y_true, y_pred, labels=[0, 1]).ravel()
+    acc  = float((tp + tn) / (tp + tn + fp + fn)) if (tp + tn + fp + fn) > 0 else float("nan")
+    sens = float(tp / (tp + fn)) if (tp + fn) > 0 else 0.0
+    spec = float(tn / (tn + fp)) if (tn + fp) > 0 else 0.0
+    composite = 0.5 * (auc if not np.isnan(auc) else 0.0) + 0.25 * sens + 0.25 * spec
+
+    return {
+        "loss":      float(np.mean(losses)) if losses else float("nan"),
+        "auc":       float(auc),
+        "acc":       acc,
+        "sens":      sens,
+        "spec":      spec,
+        "composite": float(composite),
+        "y_true":    y_true,
+        "y_prob":    y_prob,
+        "names":     names_all,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Single-seed two-stage training
+# ---------------------------------------------------------------------------
+def train_one_seed(
+    seed: int,
+    train_loader: DataLoader,
+    val_loader: DataLoader,
+    output_dir: Optional[str] = None,
+    config=None,
+) -> Tuple[nn.Module, float, str, list[dict]]:
+    """Train ONE model end-to-end (frozen warmup → full fine-tune).
+
+    Returns (best_model, best_val_auc, checkpoint_path, history).
+    """
+    cfg = config or CFG
+    output_dir = output_dir or cfg.output_dir
+    os.makedirs(output_dir, exist_ok=True)
+
+    set_seed(seed)
+
+    model        = build_model(cfg.backbone).to(cfg.device)
+    total_params = sum(p.numel() for p in model.parameters())
+
+    print("\n" + "=" * 80)
+    print(f"  Seed    : {seed}")
+    print(f"  Model   : {model.__class__.__name__}  ({total_params:,} total params)")
+    print(f"  Backbone: {cfg.backbone}")
+    print(f"  Device  : {cfg.device}")
+    print("=" * 80)
+
+    if cfg.use_composite_loss:
+        criterion = SoftCompositeLoss(
+            alpha=cfg.composite_loss_alpha,
+            auc_gamma=cfg.composite_loss_gamma,
+        )
+        print(
+            f"  Loss    : SoftCompositeLoss  "
+            f"(α={cfg.composite_loss_alpha}, γ={cfg.composite_loss_gamma})"
+        )
+    else:
+        criterion = nn.BCEWithLogitsLoss()
+        print("  Loss    : BCEWithLogitsLoss")
+
+    mixup_alpha     = getattr(cfg, "mixup_alpha",     0.0)
+    label_smoothing = getattr(cfg, "label_smoothing", 0.0)
+    if mixup_alpha > 0:
+        print(f"  Mixup   : α={mixup_alpha}")
+    if label_smoothing > 0:
+        print(f"  Smoothing: ε={label_smoothing}")
+
+    scaler    = torch.cuda.amp.GradScaler(enabled=(cfg.device == "cuda"))
+    history: list[dict] = []
+
+    _aug_kw = dict(mixup_alpha=mixup_alpha, label_smoothing=label_smoothing)
+
+    # ── Stage 1: frozen backbone, head-only warmup ─────────────────────────
+    freeze_backbone(model)
+    n_trainable = sum(p.numel() for p in trainable_params(model))
+    print(f"\n  Stage 1 — all backbone blocks FROZEN  |  {n_trainable:,} trainable params")
+    opt_frozen = optim.AdamW(
+        trainable_params(model), lr=cfg.head_lr, weight_decay=cfg.weight_decay,
+    )
+    for ep in range(1, cfg.frozen_epochs + 1):
+        t = run_one_epoch(model, train_loader, criterion, opt_frozen, scaler, **_aug_kw)
+        v = run_one_epoch(model, val_loader, criterion)
+        history.append({
+            "seed": seed, "stage": "frozen", "epoch": ep,
+            "train_loss": t["loss"], "train_auc": t["auc"],
+            "train_acc": t["acc"], "train_composite": t["composite"],
+            "val_loss":  v["loss"], "val_auc":   v["auc"],
+            "val_acc":   v["acc"], "val_sens":   v["sens"],
+            "val_spec":  v["spec"], "val_composite": v["composite"],
+            "lr": opt_frozen.param_groups[0]["lr"],
+        })
+        print(
+            f"  [frozen] {ep}/{cfg.frozen_epochs}  "
+            f"loss={t['loss']:.4f}  train_acc={t['acc']*100:.1f}%  |  "
+            f"val_auc={v['auc']:.4f}  val_acc={v['acc']*100:.1f}%  "
+            f"sens={v['sens']:.3f}  spec={v['spec']:.3f}  comp={v['composite']:.4f}"
+        )
+
+    # ── Stage 2: partial or full fine-tune ───────────────────────────────
+    frozen_blocks = getattr(cfg, "frozen_blocks", 0)
+    partial_unfreeze(model, frozen_blocks)
+    n_trainable = sum(p.numel() for p in trainable_params(model))
+    if frozen_blocks == 0:
+        stage2_label = "all blocks UNFROZEN"
+    else:
+        stage2_label = f"{frozen_blocks} block(s) still FROZEN"
+    print(f"\n  Stage 2 — {stage2_label}  |  {n_trainable:,} trainable params")
+
+    opt_ft = optim.AdamW(
+        [
+            {"params": model.features.parameters(),   "lr": cfg.backbone_lr},
+            {"params": model.classifier.parameters(), "lr": cfg.head_lr},
+        ],
+        weight_decay=cfg.weight_decay,
+    )
+    sched = optim.lr_scheduler.CosineAnnealingLR(
+        opt_ft, T_max=cfg.finetune_epochs, eta_min=cfg.backbone_lr * 0.01,
+    )
+
+    best_auc, best_state, patience_ctr = -1.0, None, 0
+    for ep in range(1, cfg.finetune_epochs + 1):
+        t = run_one_epoch(model, train_loader, criterion, opt_ft, scaler, **_aug_kw)
+        v = run_one_epoch(model, val_loader, criterion)
+        sched.step()
+        history.append({
+            "seed": seed, "stage": "finetune", "epoch": ep,
+            "train_loss": t["loss"], "train_auc": t["auc"],
+            "train_acc": t["acc"], "train_composite": t["composite"],
+            "val_loss":  v["loss"], "val_auc":   v["auc"],
+            "val_acc":   v["acc"], "val_sens":   v["sens"],
+            "val_spec":  v["spec"], "val_composite": v["composite"],
+            "lr": opt_ft.param_groups[0]["lr"],
+        })
+        print(
+            f"  [ft]     {ep}/{cfg.finetune_epochs}  "
+            f"loss={t['loss']:.4f}  train_acc={t['acc']*100:.1f}%  |  "
+            f"val_auc={v['auc']:.4f}  val_acc={v['acc']*100:.1f}%  "
+            f"sens={v['sens']:.3f}  spec={v['spec']:.3f}  comp={v['composite']:.4f}  "
+            f"lr={opt_ft.param_groups[0]['lr']:.2e}"
+        )
+
+        if v["auc"] > best_auc:
+            best_auc, best_state, patience_ctr = (
+                v["auc"], copy.deepcopy(model.state_dict()), 0
+            )
+        else:
+            patience_ctr += 1
+            if patience_ctr >= cfg.early_stop_patience:
+                print(f"  [ft]     early stop at epoch {ep} (best val AUC = {best_auc:.4f})")
+                break
+
+    if best_state is not None:
+        model.load_state_dict(best_state)
+
+    ckpt_path = os.path.join(output_dir, f"model_seed{seed}.pth")
+    torch.save(best_state if best_state is not None else model.state_dict(), ckpt_path)
+    print(f"[seed={seed}] Best val AUC = {best_auc:.4f}   checkpoint → {ckpt_path}")
+
+    return model, best_auc, ckpt_path, history
+
+
+# ---------------------------------------------------------------------------
+# Multi-seed ensemble training
+# ---------------------------------------------------------------------------
+def train_ensemble(
+    train_loader: DataLoader,
+    val_loader: DataLoader,
+    seeds: Optional[List[int]] = None,
+    output_dir: Optional[str] = None,
+    config=None,
+) -> Tuple[List[Tuple[int, nn.Module, float, str]], pd.DataFrame]:
+    """Train one model per seed and return (models_list, full_history_df).
+
+    `models_list` items: (seed, trained_model, best_val_auc, checkpoint_path).
+    """
+    cfg = config or CFG
+    seeds = seeds if seeds is not None else cfg.seeds
+    output_dir = output_dir or cfg.output_dir
+
+    print(f"  ENSEMBLE TRAINING STARTED")
+
+    models, all_history = [], []
+    for seed in seeds:
+        m, auc, ckpt, hist = train_one_seed(
+            seed, train_loader, val_loader,
+            output_dir=output_dir, config=cfg,
+        )
+        models.append((seed, m, auc, ckpt))
+        all_history.extend(hist)
+        free_device_cache(cfg.device)
+
+    history_df = pd.DataFrame(all_history)
+    history_df.to_csv(os.path.join(output_dir, "training_history.csv"), index=False)
+
+    frozen_blocks = getattr(cfg, "frozen_blocks", 0)
+    stage2_label  = "all blocks unfrozen" if frozen_blocks == 0 else f"{frozen_blocks} block(s) frozen"
+
+    print("\n" + "═" * 80)
+    print(f"  ENSEMBLE COMPLETE")
+    print(f"  Backbone      : {cfg.backbone}")
+    print(f"  Frozen blocks : {frozen_blocks}  ({stage2_label} in Stage 2)")
+    print(f"  Seeds trained : {len(models)}")
+    print("  Per-seed best val AUC:")
+    for seed, _, auc, _ in models:
+        print(f"    seed {seed:>5} : {auc:.4f}")
+    best_seed = max(models, key=lambda x: x[2])
+    print(f"  Best seed     : {best_seed[0]}  (AUC={best_seed[2]:.4f})")
+    print("═" * 80)
+
+    return models, history_df
+
+
+# ---------------------------------------------------------------------------
+# Unified entry point (respects CFG.use_ensemble)
+# ---------------------------------------------------------------------------
+def train(
+    train_loader: DataLoader,
+    val_loader: DataLoader,
+    output_dir: Optional[str] = None,
+    config=None,
+) -> Tuple[List[Tuple[int, nn.Module, float, str]], pd.DataFrame]:
+    """Train and return (models_list, history_df) — same format as train_ensemble.
+
+    Behaviour is controlled by CFG.use_ensemble:
+        True  → delegates to train_ensemble (one model per seed in CFG.seeds)
+        False → trains a single model with CFG.seed and wraps result in the
+                same list format so the rest of the pipeline works unchanged.
+    """
+    cfg = config or CFG
+    if cfg.use_ensemble:
+        return train_ensemble(train_loader, val_loader, output_dir=output_dir, config=cfg)
+
+    m, auc, ckpt, hist = train_one_seed(
+        cfg.seed, train_loader, val_loader, output_dir=output_dir, config=cfg,
+    )
+    history_df = pd.DataFrame(hist)
+    history_df.to_csv(
+        os.path.join(output_dir or cfg.output_dir, "training_history.csv"), index=False,
+    )
+    return [(cfg.seed, m, auc, ckpt)], history_df
+
+
+# ---------------------------------------------------------------------------
+# TTA inference
+# ---------------------------------------------------------------------------
+def tta_predict(
+    model: nn.Module,
+    df: pd.DataFrame,
+    image_dir: Optional[str] = None,
+    has_labels: bool = True,
+    tta_transforms: Optional[List] = None,
+    config=None,
+) -> dict:
+    """Run TTA inference for ONE model on a DataFrame.
+
+    Predictions are averaged in **logit space** across all TTA passes.
+    """
+    cfg = config or CFG
+    tta_transforms = tta_transforms or make_tta_transforms(cfg.img_size)
+    tta_transforms = tta_transforms[:cfg.tta_passes]
+
+    all_logits: list[np.ndarray] = []
+    names_ref, labels_ref = None, None
+
+    pin = (cfg.device == "cuda")
+    amp_ctx = torch.cuda.amp.autocast(enabled=(cfg.device == "cuda"))
+
+    for tf in tta_transforms:
+        ds = TTADataset(df, tf, image_dir)
+        loader = DataLoader(
+            ds, batch_size=cfg.batch_size, num_workers=cfg.num_workers,
+            pin_memory=pin, shuffle=False,
+        )
+        pass_logits, pass_names, pass_labels = [], [], []
+        model.eval()
+        with torch.no_grad(), amp_ctx:
+            for x, y, names in loader:
+                x = x.to(cfg.device, non_blocking=pin)
+                logit = cardio_logit(model, x).float().cpu().numpy()
+                pass_logits.append(logit)
+                pass_names.extend(list(names))
+                if has_labels:
+                    pass_labels.append(y.numpy())
+        all_logits.append(np.concatenate(pass_logits))
+        if names_ref is None:
+            names_ref  = pass_names
+            labels_ref = np.concatenate(pass_labels) if has_labels else None
+
+    mean_logit = np.stack(all_logits, axis=0).mean(axis=0)
+    mean_prob  = (1.0 / (1.0 + np.exp(-mean_logit))).astype(np.float32)
+    return {
+        "names":      names_ref,
+        "y_prob":     mean_prob,
+        "y_true":     labels_ref,
+        "mean_logit": mean_logit,
+    }
+
+
+def tta_predict_ensemble(
+    models_list: List[Tuple[int, nn.Module, float, str]],
+    df: pd.DataFrame,
+    image_dir: Optional[str] = None,
+    has_labels: bool = True,
+    tta_transforms: Optional[List] = None,
+    config=None,
+) -> dict:
+    """Run TTA for every model in `models_list` and average in logit space."""
+    cfg = config or CFG
+    all_logits: list[np.ndarray] = []
+    names_ref, labels_ref = None, None
+
+    for (seed, model, _, _) in models_list:
+        print(f"  TTA with seed={seed}...")
+        pred = tta_predict(
+            model, df, image_dir=image_dir, has_labels=has_labels,
+            tta_transforms=tta_transforms, config=cfg,
+        )
+        all_logits.append(pred["mean_logit"])
+        if names_ref is None:
+            names_ref  = pred["names"]
+            labels_ref = pred["y_true"]
+
+    mean_logit = np.stack(all_logits, axis=0).mean(axis=0)
+    mean_prob  = (1.0 / (1.0 + np.exp(-mean_logit))).astype(np.float32)
+    return {"names": names_ref, "y_prob": mean_prob, "y_true": labels_ref}
+
+
+# ---------------------------------------------------------------------------
+# Submission inference
+# ---------------------------------------------------------------------------
+def predict_submission(
+    models_list: List[Tuple[int, nn.Module, float, str]],
+    submission_dir: str,
+    tta_transforms: Optional[List] = None,
+    config=None,
+) -> dict:
+    """TTA + ensemble inference on an unlabelled submission directory.
+
+    Wraps the directory in a DataFrame so we can reuse `tta_predict_ensemble`.
+    """
+    cfg = config or CFG
+    files = sorted(
+        f for f in os.listdir(submission_dir)
+        if os.path.isfile(os.path.join(submission_dir, f))
+        and f.lower().endswith((".png", ".jpg", ".jpeg"))
+    )
+    sub_df = pd.DataFrame({"filename": files})
+    return tta_predict_ensemble(
+        models_list, sub_df,
+        image_dir=submission_dir, has_labels=False,
+        tta_transforms=tta_transforms, config=cfg,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Metrics
+# ---------------------------------------------------------------------------
+def metrics_at_threshold(y_true, y_prob, threshold: float) -> dict:
+    """Composite-grading-aware metric set at a given threshold.
+
+    composite = 0.5·AUC + 0.25·sensitivity + 0.25·specificity
+    """
+    y_pred = (y_prob >= threshold).astype(int)
+    tn, fp, fn, tp = confusion_matrix(y_true, y_pred, labels=[0, 1]).ravel()
+
+    sens = tp / (tp + fn) if (tp + fn) > 0 else 0.0
+    spec = tn / (tn + fp) if (tn + fp) > 0 else 0.0
+    acc  = (tp + tn) / (tp + tn + fp + fn)
+    auc  = roc_auc_score(y_true, y_prob) if len(np.unique(y_true)) > 1 else float("nan")
+    composite = 0.5 * auc + 0.25 * sens + 0.25 * spec
+    precision = tp / (tp + fp) if (tp + fp) > 0 else 0.0
+
+    return {
+        "threshold":   float(threshold),
+        "auc":         float(auc),
+        "sensitivity": float(sens),
+        "specificity": float(spec),
+        "accuracy":    float(acc),
+        "youden":      float(sens + spec - 1.0),
+        "composite":   float(composite),
+        "precision":   float(precision),
+        "tp": int(tp), "tn": int(tn), "fp": int(fp), "fn": int(fn),
+    }
+
+
+# Backwards-compatible alias (used by older notebook cells)
+compute_basic_metrics = metrics_at_threshold
+
+
+def find_best_threshold(y_true, y_prob) -> Tuple[float, dict]:
+    """Pick the threshold that maximises sensitivity + specificity (Youden's J)."""
+    candidates = np.unique(np.round(np.concatenate([[0.0], y_prob, [1.0]]), 6))
+    best_score, best_row = -np.inf, None
+    for thr in candidates:
+        m = metrics_at_threshold(y_true, y_prob, thr)
+        score = m["sensitivity"] + m["specificity"]
+        if score > best_score:
+            best_score, best_row = score, m
+    return float(best_row["threshold"]), best_row
+
+
+def bootstrap_threshold(
+    y_true, y_prob,
+    n_boot: Optional[int] = None,
+    seed: Optional[int] = None,
+) -> float:
+    """Bootstrap-stabilised threshold (median across resamples).
+
+    Generalises better than a single-shot pick on the raw val set.
+    """
+    n_boot = n_boot if n_boot is not None else CFG.n_bootstrap
+    seed   = seed   if seed   is not None else CFG.seed
+
+    rng = np.random.RandomState(seed)
+    thrs: list[float] = []
+    n = len(y_true)
+    for _ in range(n_boot):
+        idx = rng.randint(0, n, size=n)
+        if len(np.unique(y_true[idx])) < 2:
+            continue
+        thr, _ = find_best_threshold(y_true[idx], y_prob[idx])
+        thrs.append(thr)
+    return float(np.median(thrs)) if thrs else 0.5
+
+
+def select_threshold(y_true, y_prob, config=None) -> Tuple[float, dict, dict]:
+    """Pick the better of (single-shot) vs (bootstrap) thresholds on composite.
+
+    Bootstrap is preferred unless its composite is clearly worse (margin 0.005).
+    Returns (chosen_threshold, single_metrics, bootstrap_metrics).
+    """
+    cfg = config or CFG
+    thr_single, _ = find_best_threshold(y_true, y_prob)
+    thr_boot      = bootstrap_threshold(y_true, y_prob, n_boot=cfg.n_bootstrap, seed=cfg.seed)
+    m_single = metrics_at_threshold(y_true, y_prob, thr_single)
+    m_boot   = metrics_at_threshold(y_true, y_prob, thr_boot)
+    chosen = thr_boot if m_boot["composite"] >= m_single["composite"] - 0.005 else thr_single
+    return float(chosen), m_single, m_boot
+
+
+# ---------------------------------------------------------------------------
+# Saving results
+# ---------------------------------------------------------------------------
+def save_results(
+    models_list: List[Tuple[int, nn.Module, float, str]],
+    history: pd.DataFrame,
+    val_out: dict,
+    test_out: dict,
+    best_threshold: float,
+    output_dir: str,
+    model_name: str = "model",
+    config=None,
+) -> None:
+    """Persist per-seed checkpoints, history, metrics, predictions, and global log.
+
+    Per-seed `.pth` files are already written by `train_one_seed`; here we
+    only re-save them under the conventional name and write the metrics +
+    per-image prediction CSVs.
+    """
+    cfg = config or CFG
+    os.makedirs(output_dir, exist_ok=True)
+
+    # ── Metric files + per-image predictions ─────────────────────────────
+    val_metrics  = metrics_at_threshold(val_out["y_true"],  val_out["y_prob"],  best_threshold)
+    test_metrics = metrics_at_threshold(test_out["y_true"], test_out["y_prob"], best_threshold)
+
+    for split_name, metrics in [("val", val_metrics), ("test", test_metrics)]:
+        with open(os.path.join(output_dir, f"{split_name}_metrics_final.json"), "w") as f:
+            json.dump(metrics, f, indent=2)
+
+    history.to_csv(os.path.join(output_dir, "training_history.csv"), index=False)
+
+    for split_name, out in [("val", val_out), ("test", test_out)]:
+        y_true = out["y_true"].astype(int)
+        y_pred = (out["y_prob"] >= best_threshold).astype(int)
+        pd.DataFrame({
+            "filename": out["names"],
+            "y_true":   y_true,
+            "prob":     out["y_prob"],
+            "pred":     y_pred,
+            "correct":  (y_pred == y_true).astype(int),
+        }).to_csv(os.path.join(output_dir, f"{split_name}_predictions.csv"), index=False)
+
+    # ── Ensemble manifest (which seeds + which checkpoints) ──────────────
+    pd.DataFrame([
+        {"seed": s, "best_val_auc": auc, "checkpoint": ckpt}
+        for (s, _, auc, ckpt) in models_list
+    ]).to_csv(os.path.join(output_dir, "ensemble_manifest.csv"), index=False)
+
+    print(f"Results saved → {output_dir}")
+
+    # ── Append to global results log ─────────────────────────────────────
+    log_run(
+        model_name=model_name,
+        val_metrics=val_metrics,
+        test_metrics=test_metrics,
+        config=cfg,
+        n_seeds=len(models_list),
+        log_path=cfg.results_log_path,
+    )

model_training/src/transforms.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import List, Tuple
+
+import torchvision.transforms as T
+from PIL import Image
+
+from src.config import CFG
+
+
+# ---------------------------------------------------------------------------
+# PIL helpers (TTA expects PIL → PIL transforms; xrv normalisation is applied
+# downstream inside the Dataset).
+# ---------------------------------------------------------------------------
+def _pil_hflip(img: Image.Image) -> Image.Image:
+    return img.transpose(Image.FLIP_LEFT_RIGHT)
+
+
+# ---------------------------------------------------------------------------
+# Training and evaluation transforms
+# ---------------------------------------------------------------------------
+def make_transforms(img_size: int | None = None) -> Tuple[T.Compose, T.Compose]:
+    """Return (train_transform, eval_transform) PIL-space pipelines.
+
+    All transforms produce a PIL grayscale image of size (img_size, img_size).
+    The downstream Dataset converts it to a single-channel xrv-normalised
+    tensor in [-1024, 1024].
+
+    Train pipeline: small affine, mild jitter, light hflip; random erasing
+                    happens after xrv normalisation inside the Dataset.
+    Eval pipeline:  deterministic resize.
+    """
+    img_size = img_size if img_size is not None else CFG.img_size
+
+    train_tf = T.Compose([
+        T.Resize((img_size + 16, img_size + 16)),
+        T.RandomCrop((img_size, img_size)),
+        T.RandomHorizontalFlip(p=0.5),
+        T.RandomAffine(
+            degrees=8,
+            translate=(0.04, 0.04),
+            scale=(0.95, 1.05),
+            fill=0,
+        ),
+        T.ColorJitter(brightness=0.15, contrast=0.15),
+    ])
+
+    eval_tf = T.Compose([
+        T.Resize((img_size, img_size)),
+    ])
+
+    return train_tf, eval_tf
+
+
+# ---------------------------------------------------------------------------
+# Test-time augmentation (TTA) transforms
+# ---------------------------------------------------------------------------
+def make_tta_transforms(img_size: int | None = None) -> List[T.Compose]:
+    """Six deterministic PIL-space transforms.
+
+    All end with a resized PIL image ready for xrv_normalize_np().
+    Predictions are averaged across all passes (in logit space) inside
+    `tta_predict` / `tta_predict_ensemble`.
+    """
+    img_size = img_size if img_size is not None else CFG.img_size
+    size = (img_size, img_size)
+
+    return [
+        T.Compose([T.Resize(size)]),
+        T.Compose([T.Resize(size), T.Lambda(_pil_hflip)]),
+        T.Compose([T.Resize((img_size + 20, img_size + 20)), T.CenterCrop(size)]),
+        T.Compose([T.Resize((img_size - 20, img_size - 20)),
+                   T.Pad(10, fill=0), T.CenterCrop(size)]),
+        T.Compose([T.Resize(size),
+                   T.RandomAffine(degrees=(6, 6), fill=0)]),
+        T.Compose([T.Resize(size),
+                   T.RandomAffine(degrees=(-6, -6), fill=0)]),
+    ]

model_training/src/utils.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import dataclasses
+import os
+import random
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+import torch
+
+if TYPE_CHECKING:
+    from src.config import Config
+
+
+def set_seed(seed: int) -> None:
+    """Set all relevant random seeds for reproducibility."""
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed_all(seed)
+    elif torch.backends.mps.is_available():
+        torch.mps.manual_seed(seed)
+
+
+def free_device_cache(device: str) -> None:
+    """Release unused memory on GPU / MPS (useful between seeds / Optuna trials)."""
+    if device == "mps":
+        torch.mps.empty_cache()
+    elif device == "cuda":
+        torch.cuda.empty_cache()
+
+
+def log_run(
+    model_name: str,
+    val_metrics: dict,
+    test_metrics: dict,
+    config: "Config",
+    n_seeds: int,
+    log_path: str = "results_log.csv",
+) -> pd.DataFrame:
+    """Append one training run to the global results log CSV.
+
+    Creates the file with a header if it does not exist yet, otherwise appends.
+
+    Columns
+    ───────
+    run_id, model_name, created_at,
+    <all Config fields except device/csv_path/image_dir/submission_test_dir/output_dir>,
+    n_seeds,
+    val_*  (auc, sensitivity, specificity, accuracy, youden, composite,
+            precision, tp, tn, fp, fn, threshold)
+    test_* (same set)
+
+    Parameters
+    ──────────
+    model_name   : human-readable name for this run (e.g. "xrv_densenet_ensemble")
+    val_metrics  : dict returned by metrics_at_threshold on the validation split
+    test_metrics : dict returned by metrics_at_threshold on the test split
+    config       : the Config instance used for this run
+    n_seeds      : number of seeds in the ensemble
+    log_path     : path to the CSV results log (created if missing)
+    """
+    cfg_dict = dataclasses.asdict(config)
+
+    # exclude path/device fields — not meaningful for comparison
+    skip = {"csv_path", "image_dir", "submission_test_dir", "output_dir", "device"}
+    hyperparams = {k: v for k, v in cfg_dict.items() if k not in skip}
+
+    # `seeds` is a list — flatten to a string so the CSV stays readable
+    if "seeds" in hyperparams and isinstance(hyperparams["seeds"], list):
+        hyperparams["seeds"] = ",".join(str(s) for s in hyperparams["seeds"])
+
+    row: dict = {
+        "run_id":     datetime.now().strftime("%Y%m%d_%H%M%S"),
+        "model_name": model_name,
+        "created_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+        "n_seeds":    n_seeds,
+        **hyperparams,
+    }
+
+    for prefix, metrics in [("val", val_metrics), ("test", test_metrics)]:
+        for key, value in metrics.items():
+            if key != "threshold":
+                row[f"{prefix}_{key}"] = value
+        row[f"{prefix}_threshold"] = metrics.get("threshold", float("nan"))
+
+    new_row_df = pd.DataFrame([row])
+
+    if os.path.exists(log_path):
+        log_df = pd.read_csv(log_path)
+        log_df = pd.concat([log_df, new_row_df], ignore_index=True)
+    else:
+        log_df = new_row_df
+
+    log_df.to_csv(log_path, index=False)
+    print(f"Run logged → {log_path}  ({len(log_df)} total runs)")
+    return log_df