Deploy CellQuant

.gitattributes

@@ -1,35 +1,2 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow 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
+examples/F100_crop_512.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,13 +1,120 @@
 ---
-title: Cellquant
-emoji: 🌍
-colorFrom: green
-colorTo: purple
+title: CellQuant
+emoji: "⬜"
+colorFrom: gray
+colorTo: gray
 sdk: gradio
-sdk_version: 6.30.0
-python_version: '3.13'
+sdk_version: 5.49.1
+python_version: "3.11"
 app_file: app.py
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# CellQuant: nucleus, antibody and puncta counting for fluorescence sections
+
+CellQuant counts the six categories that were annotated in CVAT on 35-day spinal-cord
+sections stained with DAPI (blue), an antibody (green: Iba1 or TMEM119) and a red punctum
+marker that the lab calls **"Nostril"**:
+
+| Label | Meaning |
+|---|---|
+| Cell, Antibody + | nucleus with green antibody signal, no punctum |
+| Cell, Antibody − | nucleus without antibody signal, no punctum |
+| Cell, Nostril, Antibody + | nucleus containing a red punctum, antibody positive |
+| Cell, Nostril, Antibody − | nucleus containing a red punctum, antibody negative |
+| Nostril in Nucleus | red punctum inside a nucleus |
+| Nostril External of Nucleus | red punctum outside every nucleus |
+
+Every nucleus receives exactly one of the four *Cell* labels.
+
+## How it works
+
+* **Model** – a UNet with an ImageNet-pretrained ResNet34 encoder (`cellquant/model.py`) that
+  predicts, per pixel: nucleus interior / border / background, P(antibody +), P(nucleus has
+  punctum) and punctum in-nucleus / external / background. A full-resolution refinement stage
+  keeps 5-pixel puncta.
+* **Instances** – a marker-controlled watershed on the interior/border maps separates touching
+  nuclei; puncta are connected components (`cellquant/postprocess.py`).
+* **Labels** – antibody status is the mean probability inside each nucleus; a nucleus is
+  "Nostril" when a punctum classified "in nucleus" lies inside it (the annotation protocol;
+  the network's own nucleus-level head is available as an alternative in *Advanced*);
+  punctum type comes from the network (switchable to a purely geometric rule).
+* **Training data** – nine 1024×1024 RGB images with 1,569 nucleus outlines and 1,057
+  punctum outlines, parsed directly from the CVAT zip exports (`cellquant/annotations.py`).
+
+## Validation (see `reports/SUMMARY.md` and `reports/cv/cv_report.md`)
+
+Leave-one-image-out cross-validation: nine models, each tested on an image it never saw, and
+each image tested 23 times (repeat runs, TTA settings, 8 rotations/flips, 6 photometric
+perturbations, rule variants). Micro-averaged over the nine held-out images:
+
+| Measure | Precision | Recall | F1 |
+|---|---:|---:|---:|
+| Nucleus detection, IoU ≥ 0.5 | 77.5% | 78.4% | 77.9% |
+| Nucleus detection, centroid inside the annotated nucleus | 87.0% | 88.0% | 87.5% |
+| Punctum detection (centroid within 6 px) | 77.3% | 82.8% | 79.9% |
+
+Among matched nuclei the antibody +/− call is right for 94% and the Nostril attribute for
+96%; puncta are classified in-nucleus vs external correctly 93% of the time. Scores vary by
+at most ±2 F1 points across the 14 rotated/perturbed runs of each image, and repeated runs are
+bit-identical. The weak spots are antibody-negative nuclei (F1 32%; only 102 examples, 62 of
+them in one image), the five-example "Cell, Nostril, Antibody −" class, and clusters of touching
+nuclei that are sometimes merged. The shipped `weights/cellquant.pt` was trained on all nine
+images with the same recipe.
+
+## Using the Space
+
+1. Upload one or more images (TIF/PNG/JPG, blue = nuclei, green = antibody, red = puncta).
+   Use the 8-bit RGB export of the microscope software (what the model was trained on);
+   16-bit inputs are auto-scaled so that their 99.95th percentile maps to 255. Multi-channel
+   TIFs with one channel per page (ImageJ composites, OME-TIFF) are supported; greyscale
+   inputs are flagged. Images larger than 1536 px are processed in overlapping tiles.
+2. Optional: enable test-time augmentation (slower, slightly more stable).
+3. Click **Analyse**. You get a counts table, colour overlays and a zip with
+   `counts.csv`, `objects.csv` (every nucleus and punctum with centroid, area, probabilities)
+   and `results.json`.
+4. Optional Gemini summary: add a Space secret `GEMINI_API_KEY` (and optionally
+   `GEMINI_MODEL`, default `gemini-4-argon`). Gemini only rewrites the counts in prose and
+   comments on image quality; it never changes a number.
+
+## Deploying to Hugging Face
+
+The checkpoint is ~98 MB, so it must go through Git LFS (`.gitattributes` already tracks
+`*.pt`). The simplest route uploads the folder with the CLI, which handles LFS automatically:
+
+```bash
+pip install -U huggingface_hub
+huggingface-cli login
+huggingface-cli upload <your-user>/cellquant . . --repo-type space --exclude "runs/*" --exclude "tests/*" --exclude ".pytest_cache/*"
+```
+
+Create the Space first (SDK: Gradio, hardware: free CPU) or add `--create`. Add the optional
+`GEMINI_API_KEY` secret under *Settings → Variables and secrets*.
+
+## Running locally
+
+```bash
+pip install -r requirements.txt
+python app.py                       # http://localhost:7860
+python -m pytest -q tests           # unit + integration tests
+```
+
+Retrain when more annotated images are available (put the TIFs and the CVAT zips in one folder):
+
+```bash
+python train.py --data-dir /path/to/folder --out weights/cellquant.pt --iters 3000
+python evaluate.py cv --data-dir /path/to/folder --runs-dir runs/cv --iters 3000
+```
+
+Training uses Apple-silicon MPS, CUDA or CPU automatically.
+
+## Limitations
+
+* The annotator skipped faint / out-of-focus nuclei; the model learned that criterion only
+  approximately, so very dim nuclei may be counted or not. Raise *Minimum nucleus area* or the
+  thresholds in *Advanced* to tune for your images.
+* "Cell, Nostril, Antibody −" had only five training examples; its predictions are the
+  product of the (well-trained) antibody and punctum heads rather than a learned class.
+* Images must have the same channel convention (blue nuclei, green antibody, red puncta) and a
+  similar magnification (nuclei ≈ 20–35 px across). The model tolerates ±25 % scale.

app.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""CellQuant Gradio app (Hugging Face Space entry point).
+
+Upload one or more fluorescence images (TIF/PNG/JPG; blue nuclei, green antibody,
+red puncta) and get per-image counts of the six annotation categories, colour
+overlays, and downloadable CSV/JSON of every detected object.
+"""
+from __future__ import annotations
+
+import csv
+import io
+import json
+import os
+import sys
+import tempfile
+import zipfile
+
+os.environ.setdefault("GRADIO_ANALYTICS_ENABLED", "False")
+
+import gradio as gr  # noqa: E402
+import numpy as np  # noqa: E402
+from PIL import Image  # noqa: E402
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))  # run from any cwd / python -I
+
+from cellquant import __version__  # noqa: E402
+from cellquant.annotations import load_image
+from cellquant.gemini_summary import enabled as gemini_enabled
+from cellquant.gemini_summary import summarize as gemini_summarize
+from cellquant.infer import Predictor
+from cellquant.labels import ALL_LABELS, LABEL_COLORS
+from cellquant.postprocess import PostConfig, render_overlay, result_to_json
+
+WEIGHTS = os.environ.get("CELLQUANT_WEIGHTS", os.path.join(os.path.dirname(os.path.abspath(__file__)), "weights", "cellquant.pt"))
+DEVICE = os.environ.get("CELLQUANT_DEVICE", "cpu")
+
+EX_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "examples")
+
+_predictors: dict[int, Predictor] = {}
+
+
+def get_predictor(tta: int) -> Predictor:
+    if tta not in _predictors:
+        if not os.path.exists(WEIGHTS):
+            raise gr.Error(f"Model weights not found at {WEIGHTS}. Train with train.py or set CELLQUANT_WEIGHTS.")
+        _predictors[tta] = Predictor(WEIGHTS, device=DEVICE, tta=tta)
+    return _predictors[tta]
+
+
+def _legend_html() -> str:
+    items = "".join(
+        f'<span style="display:inline-block;margin:2px 10px 2px 0"><span style="display:inline-block;width:14px;height:14px;'
+        f'background:rgb{c};border:1px solid #888;vertical-align:middle;margin-right:4px"></span>{lab}</span>'
+        for lab, c in LABEL_COLORS.items()
+    )
+    return f"<div>{items}</div>"
+
+
+def analyze_files(files, tta_choice, antibody_thr, cellnos_thr, min_cell_area, nostril_rule, cellnos_rule,
+                  want_summary, progress=gr.Progress()):
+    if not files:
+        raise gr.Error("Upload at least one image.")
+    tta = {"none (fastest)": 1, "4x flips": 4, "8x rotations+flips": 8}[tta_choice]
+    cfg = PostConfig(antibody_thr=float(antibody_thr), cellnos_thr=float(cellnos_thr),
+                     min_cell_area=int(min_cell_area), nostril_rule=nostril_rule, cellnos_rule=cellnos_rule)
+    pred = get_predictor(tta)
+    rows, gallery, per_image_json, csv_objects = [], [], {}, []
+    tmpdir = tempfile.mkdtemp(prefix="cellquant_")
+    overlays = {}
+    warnings_: list[str] = []
+    seen: dict[str, int] = {}
+    for i, f in enumerate(files):
+        path = f if isinstance(f, str) else f.name
+        name = os.path.basename(path)
+        k = seen.get(name, 0)
+        seen[name] = k + 1
+        if k:  # two uploads with the same file name: keep both
+            stem, ext = os.path.splitext(name)
+            name = f"{stem}_{k + 1}{ext}"
+        progress((i, len(files)), desc=f"analysing {name}")
+        try:
+            img = load_image(path)
+        except Exception as e:  # noqa: BLE001
+            raise gr.Error(f"{name}: cannot read image ({e})")
+        if np.array_equal(img[..., 0], img[..., 1]) and np.array_equal(img[..., 1], img[..., 2]):
+            warnings_.append(f"{name}: all three channels are identical (greyscale input); the model needs blue nuclei, green antibody and red puncta.")
+        res, _ = pred.predict(img, cfg)
+        ov = render_overlay(img, res, thickness=1)
+        overlays[name] = ov
+        out_png = os.path.join(tmpdir, os.path.splitext(name)[0] + "_overlay.png")
+        Image.fromarray(ov).save(out_png)
+        gallery.append((out_png, f"{name}: {res.counts['Cell, Antibody +'] + res.counts['Cell, Antibody -'] + res.counts['Cell, Nostril, Antibody +'] + res.counts['Cell, Nostril, Antibody -']} nuclei"))
+        rows.append([name] + [res.counts[lab] for lab in ALL_LABELS])
+        per_image_json[name] = {"image_size_hw": list(img.shape[:2]), **result_to_json(res)}
+        for c in res.cells:
+            csv_objects.append([name, "nucleus", c["id"], c["label"], round(c["area_px"], 1), round(c["centroid_xy"][0], 1), round(c["centroid_xy"][1], 1), round(c["p_antibody"], 3), round(c["p_nostril"], 3), c["n_puncta_inside"]])
+        for n_ in res.nostrils:
+            csv_objects.append([name, "punctum", n_["id"], n_["label"], round(n_["area_px"], 1), round(n_["centroid_xy"][0], 1), round(n_["centroid_xy"][1], 1), "", round(n_["p_in_nucleus"], 3), n_["cell_id"]])
+    # downloads
+    counts_csv = os.path.join(tmpdir, "counts.csv")
+    with open(counts_csv, "w", newline="") as fh:
+        w = csv.writer(fh)
+        w.writerow(["image"] + list(ALL_LABELS))
+        w.writerows(rows)
+    objects_csv = os.path.join(tmpdir, "objects.csv")
+    with open(objects_csv, "w", newline="") as fh:
+        w = csv.writer(fh)
+        w.writerow(["image", "kind", "id", "label", "area_px", "centroid_x", "centroid_y", "p_antibody", "p_nostril_or_in_nucleus", "n_puncta_inside_or_cell_id"])
+        w.writerows(csv_objects)
+    json_path = os.path.join(tmpdir, "results.json")
+    with open(json_path, "w") as fh:
+        json.dump({"cellquant_version": __version__, "weights": os.path.basename(WEIGHTS), "tta": tta,
+                   "postprocess": cfg.__dict__, "images": per_image_json}, fh, indent=1)
+    zip_path = os.path.join(tmpdir, "cellquant_results.zip")
+    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for p in (counts_csv, objects_csv, json_path):
+            zf.write(p, os.path.basename(p))
+        for p, _ in gallery:
+            zf.write(p, os.path.basename(p))
+    summary = "\n\n".join(f"Warning: {w}" for w in warnings_)
+    if want_summary:
+        if gemini_enabled():
+            first = next(iter(overlays.values()))
+            summary += ("\n\n" if summary else "") + gemini_summarize(
+                [{"image": r[0], "counts": dict(zip(ALL_LABELS, r[1:]))} for r in rows], overlay=Image.fromarray(first))
+        else:
+            summary += ("\n\n" if summary else "") + "Gemini summary is off: add a GEMINI_API_KEY secret to this Space to enable it."
+    return rows, gallery, zip_path, summary
+
+
+FORCE_LIGHT_JS = """
+function refresh() {
+    const url = new URL(window.location);
+    if (url.searchParams.get('__theme') !== 'light') {
+        url.searchParams.set('__theme', 'light');
+        window.location.href = url.href;
+    }
+}
+"""
+
+CSS = """
+body, .gradio-container { background: #fff !important; }
+.gradio-container .prose, .gradio-container .prose * { color: #000; }
+.gradio-container .prose a { color: #000; text-decoration: underline; }
+.gradio-container table, .gradio-container td, .gradio-container th { color: #000; }
+footer { display: none !important; }
+"""
+
+
+def build_demo() -> gr.Blocks:
+    theme = gr.themes.Monochrome(primary_hue="neutral", neutral_hue="neutral",
+                                 font=["Helvetica Neue", "Helvetica", "Arial", "sans-serif"],
+                                 font_mono=["Menlo", "Consolas", "monospace"])
+    with gr.Blocks(title="CellQuant", theme=theme, css=CSS, js=FORCE_LIGHT_JS) as demo:
+        gr.Markdown(
+            f"# CellQuant {__version__}\n"
+            "Counts nuclei (antibody positive or negative), nuclei containing a red punctum (\"Nostril\") and puncta "
+            "inside or outside nuclei in RGB fluorescence images (blue = DAPI, green = antibody, red = puncta). "
+            "Trained on CVAT outlines of 35-day spinal-cord sections stained for Iba1 or TMEM119."
+        )
+        gr.HTML(_legend_html())
+        with gr.Row():
+            with gr.Column(scale=1):
+                files = gr.File(label="Images (TIF / PNG / JPG)", file_count="multiple", file_types=["image", ".tif", ".tiff"])
+                tta = gr.Radio(["none (fastest)", "4x flips", "8x rotations+flips"], value="none (fastest)", label="Test-time augmentation")
+                want_summary = gr.Checkbox(value=False, label="Plain-language summary (Gemini)", visible=True)
+                with gr.Accordion("Advanced", open=False):
+                    antibody_thr = gr.Slider(0.1, 0.9, value=0.5, step=0.05, label="Antibody + threshold")
+                    cellnos_thr = gr.Slider(0.1, 0.9, value=0.5, step=0.05, label="Nucleus 'Nostril' threshold")
+                    min_cell_area = gr.Slider(10, 300, value=50, step=5, label="Minimum nucleus area (px)")
+                    nostril_rule = gr.Radio(["head", "geometric"], value="head", label="Punctum type from: network head / position relative to nuclei")
+                    cellnos_rule = gr.Radio(["contains", "either", "head"], value="contains", label="Nucleus gets 'Nostril' if: contains an in-nucleus punctum / that OR the network head / head only")
+                run = gr.Button("Analyse", variant="primary")
+                examples = sorted(os.path.join(EX_DIR, f) for f in os.listdir(EX_DIR)
+                                  if f.lower().endswith((".png", ".jpg", ".jpeg", ".tif", ".tiff"))) if os.path.isdir(EX_DIR) else []
+                if examples:
+                    gr.Examples(examples=[[[e]] for e in examples], inputs=[files], label="Example (512 px crop of a training image)")
+            with gr.Column(scale=2):
+                table = gr.Dataframe(headers=["image"] + list(ALL_LABELS), label="Counts", interactive=False, wrap=True)
+                gallery = gr.Gallery(label="Overlays", columns=2, height="auto")
+                zip_out = gr.File(label="Download results (CSV + JSON + overlays)")
+                summary = gr.Markdown()
+        run.click(analyze_files, [files, tta, antibody_thr, cellnos_thr, min_cell_area, nostril_rule, cellnos_rule, want_summary],
+                  [table, gallery, zip_out, summary])
+        gr.Markdown(
+            "Nucleus outlines come from a watershed over the network's interior and border maps. "
+            "A nucleus is labelled Nostril when a punctum classified as in-nucleus lies inside it. "
+            "Images larger than 1536 px are processed in overlapping tiles. Nothing leaves the Space except, "
+            "optionally, the counts and an overlay thumbnail sent to Gemini when the summary is requested."
+        )
+    return demo
+
+
+if __name__ == "__main__":
+    if not os.path.exists(WEIGHTS):
+        raise SystemExit(f"CellQuant weights not found at {WEIGHTS}: run train.py --out weights/cellquant.pt or set CELLQUANT_WEIGHTS")
+    build_demo().launch(server_name="0.0.0.0", server_port=int(os.environ.get("PORT", 7860)),
+                        allowed_paths=[EX_DIR], show_error=True)

cellquant/__init__.py

@@ -0,0 +1,6 @@
+"""CellQuant: nucleus / antibody / puncta ("Nostril") quantification for fluorescence microscopy.
+
+Trained on CVAT polygon annotations of 1024x1024 RGB images (blue = DAPI nuclei,
+green = antibody stain such as Iba1 or Tmem119, red = puncta).
+"""
+__version__ = "1.0.0"

cellquant/annotations.py

@@ -0,0 +1,555 @@
+"""Read CVAT exports and rasterise them into instance label maps.
+
+Supported inputs
+----------------
+* ``annotations.xml`` in the "CVAT for images 1.1" format (``<image>`` with
+  ``<polygon>``, ``<polyline>``, ``<ellipse>`` children).
+* CVAT task-backup zips containing ``annotations.json`` + ``task.json``.
+* Either may be given as a path to a ``.zip`` or an extracted file.
+
+Cells were traced as *closed* polylines (first and last vertex coincide within a
+pixel in every file we received), so polylines are treated as polygons.
+"""
+from __future__ import annotations
+
+import io
+import json
+import math
+import os
+import re
+import zipfile
+from dataclasses import dataclass, field
+import xml.etree.ElementTree as ET
+
+import numpy as np
+from skimage.draw import polygon as _sk_polygon
+
+from .labels import (
+    ALL_LABELS,
+    cell_attributes,
+    is_cell_label,
+    is_nostril_label,
+    nostril_in_nucleus,
+)
+
+
+@dataclass
+class Shape:
+    label: str
+    kind: str                      # "polygon" or "ellipse"
+    points: np.ndarray             # (N, 2) float32 x,y vertices (ellipses are sampled)
+    source: str = "manual"
+
+    @property
+    def centroid(self) -> np.ndarray:
+        return self.points.mean(axis=0)
+
+    @property
+    def area(self) -> float:
+        x, y = self.points[:, 0], self.points[:, 1]
+        return 0.5 * abs(float(np.dot(x, np.roll(y, 1)) - np.dot(y, np.roll(x, 1))))
+
+
+@dataclass
+class ImageAnnotation:
+    image_name: str
+    width: int
+    height: int
+    shapes: list[Shape] = field(default_factory=list)
+
+    @property
+    def key(self) -> str:
+        return image_key(self.image_name)
+
+    @property
+    def norm_name(self) -> str:
+        return normalized_name(self.image_name)
+
+    def count(self, label: str) -> int:
+        return sum(1 for s in self.shapes if s.label == label)
+
+    def counts(self) -> dict[str, int]:
+        return {lab: self.count(lab) for lab in ALL_LABELS}
+
+
+# ----------------------------------------------------------------------------
+# helpers
+
+
+def image_key(name: str) -> str:
+    """First whitespace-delimited token of a file name, e.g. ``C110`` for
+    ``C110 F 35D SC Iba W001 - Focused EDF Document_RGB copy.tif`` (the animal id)."""
+    base = os.path.basename(name)
+    tok = re.split(r"\s+", base.strip())[0]
+    return tok
+
+
+def normalized_name(name: str) -> str:
+    """Canonical form of an image file name used to pair annotations with images:
+    basename without extension, lower-cased, whitespace collapsed, and trailing
+    "copy" / "(n)" suffixes removed (``F110 ... RGB copy.tif`` == ``F110 ... RGB.tif``)."""
+    base = os.path.splitext(os.path.basename(name))[0].strip().lower()
+    base = re.sub(r"\s+", " ", base)
+    while True:
+        new = re.sub(r"\s*\(\d+\)$", "", base)
+        new = re.sub(r"(\s|-|_)copy$", "", new)
+        if new == base:
+            return base
+        base = new.strip()
+
+
+def short_keys(basenames: list[str]) -> list[str]:
+    """Short unique keys for image file names: the animal id (first token, original
+    case), extended with the well token (``W001``) or an index only when two
+    images share the animal id."""
+    firsts = [image_key(b) for b in basenames]
+    keys = []
+    for b, f in zip(basenames, firsts):
+        if firsts.count(f) == 1:
+            keys.append(f)
+            continue
+        m = re.search(r"\b(w\d+)\b", normalized_name(b))
+        keys.append(f"{f}_{m.group(1).upper()}" if m else f)
+    # still colliding (same animal and well): append an index
+    seen: dict[str, int] = {}
+    out = []
+    for k in keys:
+        if keys.count(k) > 1:
+            seen[k] = seen.get(k, 0) + 1
+            out.append(f"{k}_{seen[k]}")
+        else:
+            out.append(k)
+    return out
+
+
+def ellipse_points(cx: float, cy: float, rx: float, ry: float, rotation_deg: float = 0.0,
+                   n: int = 48) -> np.ndarray:
+    t = np.linspace(0.0, 2.0 * math.pi, n, endpoint=False)
+    x = rx * np.cos(t)
+    y = ry * np.sin(t)
+    if rotation_deg:
+        a = math.radians(rotation_deg)
+        x, y = x * math.cos(a) - y * math.sin(a), x * math.sin(a) + y * math.cos(a)
+    return np.stack([cx + x, cy + y], axis=1).astype(np.float32)
+
+
+def _parse_points(s: str) -> np.ndarray:
+    pts = [[float(v) for v in p.split(",")] for p in s.strip().split(";") if p.strip()]
+    return np.asarray(pts, dtype=np.float32).reshape(-1, 2)
+
+
+# ----------------------------------------------------------------------------
+# readers
+
+
+def parse_cvat_xml(xml_bytes: bytes) -> list[ImageAnnotation]:
+    root = ET.fromstring(xml_bytes)
+    out: list[ImageAnnotation] = []
+    for im in root.iter("image"):
+        ann = ImageAnnotation(image_name=im.get("name"), width=int(im.get("width")),
+                              height=int(im.get("height")))
+        for sh in im:
+            label = sh.get("label")
+            if label is None:
+                continue
+            src = sh.get("source", "manual")
+            if sh.tag in ("polygon", "polyline"):
+                pts = _parse_points(sh.get("points", ""))
+                if len(pts) < 3:
+                    continue
+                ann.shapes.append(Shape(label, "polygon", pts, src))
+            elif sh.tag == "ellipse":
+                cx, cy, rx, ry = (float(sh.get(k)) for k in ("cx", "cy", "rx", "ry"))
+                rot = float(sh.get("rotation", 0.0) or 0.0)
+                ann.shapes.append(Shape(label, "ellipse", ellipse_points(cx, cy, rx, ry, rot), src))
+            elif sh.tag == "box":
+                xtl, ytl, xbr, ybr = (float(sh.get(k)) for k in ("xtl", "ytl", "xbr", "ybr"))
+                pts = np.array([[xtl, ytl], [xbr, ytl], [xbr, ybr], [xtl, ybr]], dtype=np.float32)
+                ann.shapes.append(Shape(label, "polygon", pts, src))
+            # points / masks / tags are not used by this project
+        out.append(ann)
+    return out
+
+
+def parse_cvat_backup(zf: zipfile.ZipFile) -> list[ImageAnnotation]:
+    """CVAT task backup: annotations.json (list of jobs with shapes) + manifest."""
+    ann_json = json.loads(zf.read("annotations.json"))
+    frames: list[tuple[str, int, int]] = []
+    for name in zf.namelist():
+        if name.endswith("manifest.jsonl"):
+            for line in zf.read(name).decode("utf-8").splitlines():
+                line = line.strip()
+                if not line:
+                    continue
+                rec = json.loads(line)
+                if "name" in rec and "width" in rec:
+                    frames.append((rec["name"] + rec.get("extension", ""), int(rec["width"]), int(rec["height"])))
+    out: list[ImageAnnotation] = []
+    jobs = ann_json if isinstance(ann_json, list) else [ann_json]
+    by_frame: dict[int, ImageAnnotation] = {}
+    for job in jobs:
+        for sh in job.get("shapes", []):
+            fr = int(sh.get("frame", 0))
+            if fr not in by_frame:
+                name, w, h = frames[fr] if fr < len(frames) else (f"frame_{fr}", 0, 0)
+                by_frame[fr] = ImageAnnotation(name, w, h)
+            label = sh.get("label")
+            pts = np.asarray(sh.get("points", []), dtype=np.float32).reshape(-1, 2)
+            kind = sh.get("type")
+            if kind in ("polygon", "polyline") and len(pts) >= 3:
+                by_frame[fr].shapes.append(Shape(label, "polygon", pts, sh.get("source", "manual")))
+            elif kind == "ellipse" and len(pts) >= 2:
+                # CVAT stores ellipse as [cx, cy, right_x, top_y]
+                cx, cy, rxp, typ = pts[0, 0], pts[0, 1], pts[1, 0], pts[1, 1]
+                rx, ry = abs(rxp - cx), abs(cy - typ)
+                by_frame[fr].shapes.append(Shape(label, "ellipse", ellipse_points(cx, cy, rx, ry, float(sh.get("rotation", 0.0) or 0.0)), sh.get("source", "manual")))
+            elif kind == "rectangle" and len(pts) >= 2:
+                (x0, y0), (x1, y1) = pts[0], pts[1]
+                by_frame[fr].shapes.append(Shape(label, "polygon", np.array([[x0, y0], [x1, y0], [x1, y1], [x0, y1]], np.float32), sh.get("source", "manual")))
+    for fr in sorted(by_frame):
+        out.append(by_frame[fr])
+    return out
+
+
+def load_annotation_file(path: str) -> list[ImageAnnotation]:
+    """Load a CVAT export given as .zip (xml or backup), .xml or .json."""
+    if path.lower().endswith(".zip"):
+        with zipfile.ZipFile(path) as zf:
+            names = zf.namelist()
+            if "annotations.xml" in names:
+                return parse_cvat_xml(zf.read("annotations.xml"))
+            xmls = [n for n in names if n.lower().endswith(".xml")]
+            if xmls:
+                return parse_cvat_xml(zf.read(xmls[0]))
+            if "annotations.json" in names:
+                return parse_cvat_backup(zf)
+            raise ValueError(f"{path}: no annotations.xml / annotations.json inside the zip")
+    if path.lower().endswith(".xml"):
+        with open(path, "rb") as f:
+            return parse_cvat_xml(f.read())
+    raise ValueError(f"unsupported annotation file: {path}")
+
+
+# ----------------------------------------------------------------------------
+# rasterisation
+
+
+def rasterize_shape(shape: Shape, height: int, width: int) -> tuple[np.ndarray, np.ndarray]:
+    """Return (rows, cols) of the pixels covered by a shape, clipped to the image.
+
+    Shapes too thin to enclose any pixel centre still mark their rounded
+    centroid, so that tiny puncta (area < 3 px^2) are never lost.
+    """
+    pts = shape.points
+    rr, cc = _sk_polygon(pts[:, 1], pts[:, 0], shape=(height, width))
+    if rr.size == 0:
+        cx, cy = shape.centroid
+        r, c = int(round(cy)), int(round(cx))
+        if 0 <= r < height and 0 <= c < width:
+            rr, cc = np.array([r]), np.array([c])
+    return rr, cc
+
+
+@dataclass
+class RasterAnnotation:
+    """Instance maps plus per-instance attribute tables (index 0 = background)."""
+    cell_inst: np.ndarray            # int32 (H, W), 0 = background
+    cell_labels: list[str]           # len = n_cells + 1, [0] = ""
+    nostril_inst: np.ndarray         # int32 (H, W)
+    nostril_labels: list[str]        # len = n_nostrils + 1
+
+    @property
+    def n_cells(self) -> int:
+        return len(self.cell_labels) - 1
+
+    @property
+    def n_nostrils(self) -> int:
+        return len(self.nostril_labels) - 1
+
+    def cell_antibody(self) -> np.ndarray:
+        """bool per instance id (index 0 unused)."""
+        return np.array([False] + [cell_attributes(l)[0] for l in self.cell_labels[1:]])
+
+    def cell_has_nostril(self) -> np.ndarray:
+        return np.array([False] + [cell_attributes(l)[1] for l in self.cell_labels[1:]])
+
+    def nostril_inside(self) -> np.ndarray:
+        return np.array([False] + [nostril_in_nucleus(l) for l in self.nostril_labels[1:]])
+
+
+def rasterize(ann: ImageAnnotation, height: int | None = None, width: int | None = None) -> RasterAnnotation:
+    H = height or ann.height
+    W = width or ann.width
+    cells = [s for s in ann.shapes if is_cell_label(s.label)]
+    nos = [s for s in ann.shapes if is_nostril_label(s.label)]
+    # Paint large shapes first so that any (rare) overlap keeps the smaller one.
+    cells.sort(key=lambda s: -s.area)
+    nos.sort(key=lambda s: -s.area)
+    cell_inst = np.zeros((H, W), dtype=np.int32)
+    cell_labels = [""]
+    for s in cells:
+        rr, cc = rasterize_shape(s, H, W)
+        if rr.size == 0:
+            continue
+        cell_labels.append(s.label)
+        cell_inst[rr, cc] = len(cell_labels) - 1
+    nos_inst = np.zeros((H, W), dtype=np.int32)
+    nos_labels = [""]
+    for s in nos:
+        rr, cc = rasterize_shape(s, H, W)
+        if rr.size == 0:
+            continue
+        nos_labels.append(s.label)
+        nos_inst[rr, cc] = len(nos_labels) - 1
+    # Drop instances that were completely over-painted (keeps ids contiguous).
+    cell_inst, cell_labels = _compact(cell_inst, cell_labels)
+    nos_inst, nos_labels = _compact(nos_inst, nos_labels)
+    return RasterAnnotation(cell_inst, cell_labels, nos_inst, nos_labels)
+
+
+def _compact(inst: np.ndarray, labels: list[str]) -> tuple[np.ndarray, list[str]]:
+    present = np.unique(inst)
+    present = present[present > 0]
+    if len(present) == len(labels) - 1:
+        return inst, labels
+    remap = np.zeros(len(labels), dtype=np.int32)
+    new_labels = [""]
+    for old in present:
+        new_labels.append(labels[old])
+        remap[old] = len(new_labels) - 1
+    return remap[inst], new_labels
+
+
+# ----------------------------------------------------------------------------
+# dataset discovery
+
+
+IMAGE_EXTS = (".tif", ".tiff", ".png", ".jpg", ".jpeg")
+ANN_EXTS = (".zip", ".xml")
+
+
+@dataclass
+class Sample:
+    key: str
+    image_path: str
+    annotation: ImageAnnotation
+    annotation_path: str
+
+
+class _quiet_tifffile:
+    """Silence tifffile's log line about the inconsistent OME block in the Keyence exports."""
+
+    def __enter__(self):
+        import logging
+        self.lg = logging.getLogger("tifffile")
+        self.lvl = self.lg.level
+        self.lg.setLevel(logging.ERROR)
+        return self
+
+    def __exit__(self, *exc):
+        self.lg.setLevel(self.lvl)
+        return False
+
+
+def image_size(path: str) -> tuple[int, int]:
+    """(height, width) read from the file header only."""
+    if path.lower().endswith((".tif", ".tiff")):
+        import tifffile
+        with _quiet_tifffile(), tifffile.TiffFile(path) as tf:
+            try:
+                shp = tf.series[0].shape
+            except Exception:  # noqa: BLE001
+                shp = tf.pages[0].shape
+        if len(shp) == 3 and shp[0] in (3, 4) and shp[-1] > 4:
+            return int(shp[1]), int(shp[2])
+        return int(shp[0]), int(shp[1])
+    from PIL import Image
+    with Image.open(path) as im:
+        w, h = im.size
+    return h, w
+
+
+def discover(data_dir: str, verbose: bool = True, check_sizes: bool = True) -> tuple[list[Sample], list[str]]:
+    """Pair every annotation export in ``data_dir`` with its image.
+
+    Returns (samples, unannotated_image_paths). Pairing uses the image name
+    recorded *inside* the annotation (not the zip name): first an exact match on
+    the normalised file name (extension, case, whitespace and "copy"/"(n)"
+    suffixes ignored), else the animal id (first token) when it is unambiguous.
+    Byte-identical duplicate copies of an image collapse to one entry; two
+    *different* images or two different annotation files that map to the same
+    name are reported and refused rather than silently dropped. Sample keys are
+    the animal id, extended with the well token when one animal has several
+    sections (``F110_W002``).
+    """
+    files = sorted(os.listdir(data_dir))
+    images: dict[str, list[str]] = {}
+    for f in files:
+        if f.lower().endswith(IMAGE_EXTS):
+            images.setdefault(normalized_name(f), []).append(os.path.join(data_dir, f))
+    # collapse byte-identical copies; refuse different files with the same normalised name
+    image_path: dict[str, str] = {}
+    for n, paths in images.items():
+        if len(paths) > 1:
+            digests = {_digest(p) for p in paths}
+            if len(digests) > 1:
+                raise ValueError(f"{data_dir}: {len(paths)} different image files share the name '{n}': {[os.path.basename(p) for p in paths]}")
+        image_path[n] = paths[0]
+    by_first: dict[str, list[str]] = {}
+    for n in image_path:
+        by_first.setdefault(image_key(n), []).append(n)
+
+    paired: dict[str, tuple[ImageAnnotation, str]] = {}   # norm image name -> (annotation, annotation path)
+    for f in files:
+        if not f.lower().endswith(ANN_EXTS):
+            continue
+        path = os.path.join(data_dir, f)
+        try:
+            anns = load_annotation_file(path)
+        except Exception as e:  # noqa: BLE001
+            if verbose:
+                print(f"[discover] skip {f}: {e}")
+            continue
+        for ann in anns:
+            n = ann.norm_name
+            if n not in image_path:
+                cands = by_first.get(image_key(n), [])
+                if len(cands) == 1:
+                    n = cands[0]
+                else:
+                    if verbose:
+                        print(f"[discover] {f}: no image for '{ann.image_name}'" + (f" (ambiguous: {cands})" if cands else ""))
+                    continue
+            if n in paired:
+                prev_ann, prev_path = paired[n]
+                if _shapes_equal(prev_ann, ann):
+                    if verbose:
+                        print(f"[discover] {f}: same annotations as {os.path.basename(prev_path)} for '{ann.image_name}', keeping the first")
+                    continue
+                raise ValueError(f"{data_dir}: two different annotation files for image '{ann.image_name}': "
+                                 f"{os.path.basename(prev_path)} and {f}")
+            paired[n] = (ann, path)
+    names = sorted(paired)
+    keys = short_keys([os.path.basename(image_path[n]) for n in names])
+    samples = []
+    for n, k in zip(names, keys):
+        ann, apath = paired[n]
+        ipath = image_path[n]
+        if check_sizes:
+            h, w = image_size(ipath)
+            if (h, w) != (ann.height, ann.width):
+                raise ValueError(f"{os.path.basename(ipath)}: image is {w}x{h} but the annotation canvas is {ann.width}x{ann.height}")
+        samples.append(Sample(k, ipath, ann, apath))
+    unannotated = [p for n, p in image_path.items() if n not in paired]
+    return samples, sorted(unannotated)
+
+
+def _digest(path: str) -> str:
+    import hashlib
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _shapes_equal(a: ImageAnnotation, b: ImageAnnotation, tol: float = 0.5) -> bool:
+    """Same labels and the same shapes (centroids within ``tol`` px, same vertex
+    count), in any order. Tolerant to the coordinate rounding that differs
+    between CVAT's XML (2 decimals) and JSON exports."""
+    if len(a.shapes) != len(b.shapes):
+        return False
+    pool = list(b.shapes)
+    for s in a.shapes:
+        c = s.centroid
+        hit = None
+        for j, t in enumerate(pool):
+            if t.label == s.label and len(t.points) == len(s.points) and float(np.abs(t.centroid - c).max()) <= tol:
+                hit = j
+                break
+        if hit is None:
+            return False
+        pool.pop(hit)
+    return True
+
+
+def load_image(path: str) -> np.ndarray:
+    """Load an RGB uint8 image (H, W, 3) from tif/png/jpg.
+
+    * TIFFs are read as a whole series, so channel-per-page files (ImageJ
+      composites, OME-TIFF ``CYX``) load as 3 channels; stacks with more than
+      four planes are refused rather than silently reduced to one plane.
+    * Compressed TIFFs that tifffile cannot decode fall back to Pillow.
+    * Palette / CMYK / LA images are converted to RGB(A) by Pillow.
+    * 16-bit inputs are rescaled by their 99.95th percentile (see to_rgb_uint8).
+    """
+    if path.lower().endswith((".tif", ".tiff")):
+        import logging
+        import tifffile
+        lg = logging.getLogger("tifffile")
+        lvl = lg.level
+        lg.setLevel(logging.ERROR)   # the Keyence exports carry an inconsistent OME block; tifffile logs it
+        try:
+            with tifffile.TiffFile(path) as tf:
+                try:
+                    a = tf.series[0].asarray()
+                except Exception:  # noqa: BLE001 - malformed series metadata: stack the pages
+                    pages = [p.asarray() for p in tf.pages]
+                    a = pages[0] if len(pages) == 1 else np.stack(pages)
+        except Exception as e:  # noqa: BLE001 - e.g. LZW/JPEG without imagecodecs
+            lg.setLevel(lvl)
+            from PIL import Image
+            try:
+                a = _pil_array(Image.open(path))
+            except Exception:
+                raise ValueError(f"cannot decode TIFF {os.path.basename(path)}: {e}") from e
+        finally:
+            lg.setLevel(lvl)
+        a = np.asarray(a)
+        if a.ndim == 3 and a.shape[0] > 4 and a.shape[-1] > 4:
+            raise ValueError(f"{os.path.basename(path)}: {a.shape[0]}-plane stack; export a single RGB plane (blue nuclei, green antibody, red puncta)")
+        if a.ndim == 4:
+            raise ValueError(f"{os.path.basename(path)}: unsupported {a.ndim}-D TIFF of shape {a.shape}")
+    else:
+        from PIL import Image
+        a = _pil_array(Image.open(path))
+    return to_rgb_uint8(a)
+
+
+def _pil_array(im) -> np.ndarray:
+    """Pillow image -> array with a known mode (keeps 16-bit/float grey untouched)."""
+    if im.mode in ("RGB", "RGBA", "L", "I", "I;16", "I;16B", "I;16L", "F"):
+        return np.asarray(im)
+    if im.mode in ("LA", "PA"):
+        return np.asarray(im.convert("RGBA"))
+    return np.asarray(im.convert("RGB"))
+
+
+def to_rgb_uint8(a: np.ndarray) -> np.ndarray:
+    a = np.asarray(a)
+    if a.ndim == 3 and a.shape[0] in (3, 4) and a.shape[-1] > 4:
+        a = np.moveaxis(a, 0, -1)                      # channel-first (C, H, W) -> channel-last
+    if a.ndim == 2:
+        a = np.repeat(a[..., None], 3, axis=-1)
+    if a.ndim != 3:
+        raise ValueError(f"expected an RGB image, got shape {a.shape}")
+    if a.shape[-1] == 4:
+        a = a[..., :3]
+    if a.shape[-1] != 3:
+        raise ValueError(f"expected an RGB image, got shape {a.shape}")
+    if a.dtype != np.uint8:
+        a = a.astype(np.float32)
+        if a.size == 0:
+            return np.zeros(a.shape, np.uint8)
+        hi = float(a.max())
+        if np.issubdtype(np.asarray(a).dtype, np.floating) and hi <= 1.0 and float(a.min()) >= 0.0:
+            scale = 255.0                              # float image in [0, 1]
+        else:
+            # Robust auto-scale for 16-bit / float data: the 99.95th percentile maps to 255,
+            # so one saturated pixel cannot darken the whole image.
+            ref = float(np.percentile(a, 99.95))
+            if ref <= 0:
+                ref = hi if hi > 0 else 1.0
+            scale = 255.0 / ref
+        a = np.clip(np.round(a * scale), 0, 255).astype(np.uint8)
+    return np.ascontiguousarray(a)

cellquant/data.py

@@ -0,0 +1,181 @@
+"""Training targets and augmentation.
+
+Targets built from a :class:`RasterAnnotation` (all (H, W)):
+    cell3     int64  0 bg, 1 nucleus interior, 2 nucleus border (2-px inner ring)
+    antibody  float  1 where nucleus is antibody+, 0 where antibody-; valid on nucleus px
+    cellnos   float  1 where nucleus has a punctum ("Nostril"); valid on nucleus px
+    cellmask  float  1 on nucleus pixels (loss mask for the two attribute heads)
+    nos3      int64  0 bg, 1 punctum in nucleus, 2 punctum external
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+import torch
+from scipy import ndimage as ndi
+from skimage.segmentation import find_boundaries
+
+from .annotations import RasterAnnotation
+
+BORDER_WIDTH = 2  # pixels of the inner border ring
+
+
+def make_targets(R: RasterAnnotation) -> dict[str, np.ndarray]:
+    inst = R.cell_inst
+    fg = inst > 0
+    border = find_boundaries(inst, mode="inner")
+    if BORDER_WIDTH > 1:
+        border = ndi.binary_dilation(border, iterations=BORDER_WIDTH - 1) & fg
+    cell3 = np.zeros(inst.shape, dtype=np.int64)
+    cell3[fg] = 1
+    cell3[border] = 2
+    ab = R.cell_antibody().astype(np.float32)[inst]
+    cn = R.cell_has_nostril().astype(np.float32)[inst]
+    ninst = R.nostril_inst
+    nin = R.nostril_inside()
+    nos3 = np.zeros(inst.shape, dtype=np.int64)
+    nos3[ninst > 0] = np.where(nin[ninst[ninst > 0]], 1, 2)
+    return {
+        "cell3": cell3,
+        "antibody": ab,
+        "cellnos": cn,
+        "cellmask": fg.astype(np.float32),
+        "nos3": nos3,
+    }
+
+
+@dataclass
+class AugConfig:
+    crop: int = 512
+    scale_min: float = 0.8
+    scale_max: float = 1.25
+    gain_min: float = 0.6
+    gain_max: float = 1.5
+    gamma_min: float = 0.7
+    gamma_max: float = 1.4
+    noise_max: float = 0.03
+    blur_max: float = 1.0
+    p_blur: float = 0.3
+    p_channel_shift: float = 0.5   # per-channel additive offset
+    offset_max: float = 0.03
+
+
+class PatchSampler:
+    """Random augmented patches from whole images kept in memory.
+
+    Geometric: random scale (zoom), random crop, random dihedral transform.
+    Photometric: per-channel gain, gamma, additive offset, Gaussian noise, blur.
+    Label maps use nearest-neighbour resampling.
+    """
+
+    def __init__(self, images: list[np.ndarray], targets: list[dict[str, np.ndarray]],
+                 cfg: AugConfig | None = None, seed: int = 0):
+        assert len(images) == len(targets) and len(images) > 0
+        self.images = images
+        self.targets = targets
+        self.cfg = cfg or AugConfig()
+        self.rng = np.random.default_rng(seed)
+
+    def _one(self) -> tuple[np.ndarray, dict[str, np.ndarray]]:
+        cfg, rng = self.cfg, self.rng
+        i = int(rng.integers(len(self.images)))
+        img, tg = self.images[i], self.targets[i]
+        H, W = img.shape[:2]
+        s = float(rng.uniform(cfg.scale_min, cfg.scale_max))      # zoom factor applied to the crop
+        src = int(round(cfg.crop / s))                              # source window size
+        src = max(32, min(src, H, W))
+        y0 = int(rng.integers(0, H - src + 1))
+        x0 = int(rng.integers(0, W - src + 1))
+        patch = img[y0:y0 + src, x0:x0 + src].astype(np.float32) / 255.0
+        tpatch = {k: v[y0:y0 + src, x0:x0 + src] for k, v in tg.items()}
+        if src != cfg.crop:
+            zoom = cfg.crop / src
+            patch = ndi.zoom(patch, (zoom, zoom, 1), order=1)
+            tpatch = {k: ndi.zoom(v, (zoom, zoom), order=0) for k, v in tpatch.items()}
+            patch = patch[:cfg.crop, :cfg.crop]
+            tpatch = {k: v[:cfg.crop, :cfg.crop] for k, v in tpatch.items()}
+            if patch.shape[0] != cfg.crop or patch.shape[1] != cfg.crop:  # rounding guard
+                ph, pw = cfg.crop - patch.shape[0], cfg.crop - patch.shape[1]
+                patch = np.pad(patch, ((0, ph), (0, pw), (0, 0)), mode="reflect")
+                tpatch = {k: np.pad(v, ((0, ph), (0, pw)), mode="reflect") for k, v in tpatch.items()}
+        # dihedral
+        k = int(rng.integers(4))
+        flip = bool(rng.integers(2))
+        patch = np.rot90(patch, k, axes=(0, 1))
+        tpatch = {kk: np.rot90(v, k, axes=(0, 1)) for kk, v in tpatch.items()}
+        if flip:
+            patch = patch[:, ::-1]
+            tpatch = {kk: v[:, ::-1] for kk, v in tpatch.items()}
+        # photometric
+        gain = rng.uniform(cfg.gain_min, cfg.gain_max, size=3).astype(np.float32)
+        gamma = float(rng.uniform(cfg.gamma_min, cfg.gamma_max))
+        patch = np.clip(patch * gain, 0, 1) ** gamma
+        if rng.random() < cfg.p_channel_shift:
+            patch = patch + rng.uniform(-cfg.offset_max, cfg.offset_max, size=3).astype(np.float32)
+        if rng.random() < cfg.p_blur:
+            sig = float(rng.uniform(0.3, cfg.blur_max))
+            patch = ndi.gaussian_filter(patch, sigma=(sig, sig, 0))
+        sigma_n = float(rng.uniform(0, cfg.noise_max))
+        if sigma_n > 0:
+            patch = patch + rng.normal(0, sigma_n, size=patch.shape).astype(np.float32)
+        patch = np.clip(patch, 0, 1).astype(np.float32)
+        return np.ascontiguousarray(patch), {k: np.ascontiguousarray(v) for k, v in tpatch.items()}
+
+    def batch(self, n: int) -> tuple[torch.Tensor, dict[str, torch.Tensor]]:
+        xs, ts = [], []
+        for _ in range(n):
+            x, t = self._one()
+            xs.append(x)
+            ts.append(t)
+        x = torch.from_numpy(np.stack(xs)).permute(0, 3, 1, 2).contiguous()
+        out = {}
+        for k in ts[0]:
+            arr = np.stack([t[k] for t in ts])
+            out[k] = torch.from_numpy(arr)
+        return x, out
+
+
+class Prefetcher:
+    """Builds augmented batches in background threads so the GPU never waits.
+
+    Each worker owns its own sampler (independent RNG stream) and its own
+    queue; ``next()`` round-robins over the workers, so the batch sequence is
+    fully determined by (seed, workers) regardless of thread scheduling.
+    """
+
+    def __init__(self, images, targets, cfg: AugConfig, batch: int, seed: int = 0, workers: int = 3, depth: int = 6):
+        import queue
+        import threading
+        workers = max(1, int(workers))
+        self.batch = batch
+        self.workers = workers
+        self._i = 0
+        self._stop = threading.Event()
+        self.qs: list["queue.Queue"] = [queue.Queue(maxsize=max(1, depth // workers)) for _ in range(workers)]
+        self._threads = []
+        for w in range(workers):
+            s = PatchSampler(images, targets, cfg, seed=seed * 1000 + w)
+            th = threading.Thread(target=self._work, args=(s, self.qs[w]), daemon=True)
+            th.start()
+            self._threads.append(th)
+
+    def _work(self, sampler: PatchSampler, q) -> None:
+        import queue
+        while not self._stop.is_set():
+            b = sampler.batch(self.batch)
+            while not self._stop.is_set():
+                try:
+                    q.put(b, timeout=0.5)
+                    break
+                except queue.Full:
+                    continue
+
+    def next(self):
+        q = self.qs[self._i]
+        self._i = (self._i + 1) % self.workers
+        return q.get()
+
+    def close(self) -> None:
+        self._stop.set()

cellquant/gemini_summary.py

@@ -0,0 +1,71 @@
+"""Optional plain-language summary of the counts via Gemini.
+
+Enabled only when the ``GEMINI_API_KEY`` environment variable (a Hugging Face
+Space *secret*) is set. The model id comes from ``GEMINI_MODEL``. Gemini never
+produces or alters any count: it only receives the numbers computed by the
+trained network and a thumbnail of the overlay, and is instructed to report
+them verbatim.
+"""
+from __future__ import annotations
+
+import os
+
+from PIL import Image
+
+DEFAULT_MODEL = os.environ.get("GEMINI_MODEL", "gemini-4-argon")
+FALLBACK_MODELS = ("gemini-3.8-flash", "gemini-2.5-flash")
+
+
+def enabled() -> bool:
+    return bool(os.environ.get("GEMINI_API_KEY"))
+
+
+def _prompt(rows: list[dict]) -> str:
+    lines = []
+    for r in rows:
+        lines.append(f"- {r['image']}: " + ", ".join(f"{k} = {v}" for k, v in r["counts"].items()))
+    return (
+        "You are helping a neuroscience lab read the output of an automated image analysis "
+        "of spinal-cord fluorescence sections (blue = DAPI nuclei, green = microglial antibody "
+        "stain such as Iba1 or TMEM119, red = puncta that the lab calls 'Nostril').\n"
+        "A trained segmentation network produced these counts per image:\n"
+        + "\n".join(lines)
+        + "\n\nLabel meanings: every nucleus is in exactly ONE of the four 'Cell' categories (they are mutually "
+        "exclusive, so total nuclei = sum of the four). 'Cell, Antibody +' = nucleus with green antibody signal and no "
+        "punctum; 'Cell, Antibody -' = nucleus without antibody signal and no punctum; 'Cell, Nostril, Antibody +/-' = "
+        "nucleus containing a red punctum, with/without antibody signal. 'Nostril in Nucleus' = punctum inside a nucleus; "
+        "'Nostril External of Nucleus' = punctum outside nuclei.\n"
+        "Write a concise summary (max 150 words) for the lab notebook: restate the counts exactly as given "
+        "(do not round, estimate or invent numbers), give the fraction of nuclei that are antibody positive "
+        "and the fraction that contain a punctum, and mention anything in the overlay thumbnail that looks "
+        "like a quality problem (out of focus, very dark, debris, edge artefacts). If nothing looks wrong, say so."
+    )
+
+
+def summarize(rows: list[dict], overlay: Image.Image | None = None, model: str | None = None) -> str:
+    """rows: [{"image": name, "counts": {label: int}}]. Returns the summary text or an error message."""
+    key = os.environ.get("GEMINI_API_KEY")
+    if not key:
+        return "Gemini summary disabled: set the GEMINI_API_KEY secret."
+    try:
+        from google import genai
+    except ImportError:
+        return "Gemini summary unavailable: install google-genai."
+    contents: list = [_prompt(rows)]
+    if overlay is not None:
+        thumb = overlay.copy()
+        thumb.thumbnail((768, 768))
+        contents.append(thumb)
+    client = genai.Client(api_key=key)
+    candidates = [model or DEFAULT_MODEL] + [m for m in FALLBACK_MODELS if m != (model or DEFAULT_MODEL)]
+    last = ""
+    for mid in candidates:
+        try:
+            resp = client.models.generate_content(model=mid, contents=contents)
+            text = (resp.text or "").strip()
+            return text if text else "Gemini returned an empty response."
+        except Exception as e:  # noqa: BLE001 - try the next model id, then surface the error to the UI
+            last = f"{type(e).__name__}: {e}"
+            if "NOT_FOUND" not in str(e) and "not found" not in str(e).lower():
+                break
+    return f"Gemini summary failed ({last})"

cellquant/infer.py

@@ -0,0 +1,107 @@
+"""Inference: image -> probabilities -> instances. CPU-friendly, optional TTA and tiling."""
+from __future__ import annotations
+
+import numpy as np
+import torch
+
+from .annotations import to_rgb_uint8
+from .model import CellUNet, load_checkpoint, pad_to_multiple
+from .postprocess import PostConfig, Result, analyze, logits_to_probs
+
+
+def pick_device(pref: str = "auto") -> torch.device:
+    if pref != "auto":
+        return torch.device(pref)
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    if torch.backends.mps.is_available():
+        return torch.device("mps")
+    return torch.device("cpu")
+
+
+# The 8 dihedral transforms as (k rotations, flip) with their inverses handled below.
+DIHEDRAL = [(k, f) for f in (False, True) for k in range(4)]
+
+
+def _fwd_t(x: torch.Tensor, k: int, flip: bool) -> torch.Tensor:
+    if flip:
+        x = torch.flip(x, dims=[-1])
+    return torch.rot90(x, k, dims=[-2, -1])
+
+
+def _inv_t(x: torch.Tensor, k: int, flip: bool) -> torch.Tensor:
+    x = torch.rot90(x, -k, dims=[-2, -1])
+    if flip:
+        x = torch.flip(x, dims=[-1])
+    return x
+
+
+class Predictor:
+    def __init__(self, weights: str | CellUNet, device: str = "auto", tta: int = 1,
+                 tile: int = 1024, overlap: int = 96, max_whole: int = 1536):
+        """tta: 1 (none), 4 (flips + 180 rotation) or 8 (full dihedral group)."""
+        self.device = pick_device(device)
+        if isinstance(weights, CellUNet):
+            self.model, self.meta = weights, {}
+        else:
+            self.model, self.meta = load_checkpoint(weights)
+        self.model.to(self.device).eval()
+        assert tta in (1, 4, 8)
+        self.tta = tta
+        self.tile, self.overlap, self.max_whole = tile, overlap, max_whole
+
+    @torch.no_grad()
+    def _probs_tensor(self, x: torch.Tensor) -> torch.Tensor:
+        """x: (1, 3, H, W) float in [0,1] on device, H, W multiples of 32 -> (8-ch probabilities) (1, 8, H, W)."""
+        transforms = DIHEDRAL[:1] if self.tta == 1 else ([(0, False), (2, False), (0, True), (2, True)] if self.tta == 4 else DIHEDRAL)
+        acc = None
+        for k, f in transforms:
+            out = self.model(_fwd_t(x, k, f))
+            out = _inv_t(out, k, f)
+            p = torch.cat([out[:, 0:3].softmax(1), out[:, 3:4].sigmoid(), out[:, 4:5].sigmoid(), out[:, 5:8].softmax(1)], dim=1)
+            acc = p if acc is None else acc + p
+        return acc / len(transforms)
+
+    @torch.no_grad()
+    def probs(self, img: np.ndarray) -> dict[str, np.ndarray]:
+        img = to_rgb_uint8(img)
+        H, W = img.shape[:2]
+        x = torch.from_numpy(img).permute(2, 0, 1).float().div_(255.0).unsqueeze(0)
+        if max(H, W) <= self.max_whole:
+            xp, _ = pad_to_multiple(x, 32)
+            p = self._probs_tensor(xp.to(self.device))[0, :, :H, :W].cpu().numpy()
+        else:
+            p = self._tiled(x)[:, :H, :W]
+        return {"cell": p[0:3], "antibody": p[3], "cellnos": p[4], "nos": p[5:8]}
+
+    def _tiled(self, x: torch.Tensor) -> np.ndarray:
+        """Overlapping tiles blended with a linear ramp (no visible seams)."""
+        _, _, H, W = x.shape
+        t, o = self.tile, self.overlap
+        step = t - o
+        acc = np.zeros((8, H, W), np.float32)
+        wsum = np.zeros((1, H, W), np.float32)
+        ramp = np.minimum(np.arange(t) + 1, np.arange(t)[::-1] + 1).astype(np.float32)
+        ramp = np.minimum(ramp, o) / o
+        w2 = (ramp[:, None] * ramp[None, :])[None]
+        ys = list(range(0, max(H - t, 0) + 1, step)) or [0]
+        xs = list(range(0, max(W - t, 0) + 1, step)) or [0]
+        if ys[-1] + t < H:
+            ys.append(H - t)
+        if xs[-1] + t < W:
+            xs.append(W - t)
+        for y0 in ys:
+            for x0 in xs:
+                y0c, x0c = max(0, y0), max(0, x0)
+                tile = x[:, :, y0c:y0c + t, x0c:x0c + t]
+                th, tw = tile.shape[-2:]
+                tp, _ = pad_to_multiple(tile, 32)
+                p = self._probs_tensor(tp.to(self.device))[0, :, :th, :tw].cpu().numpy()
+                w = w2[:, :th, :tw]
+                acc[:, y0c:y0c + th, x0c:x0c + tw] += p * w
+                wsum[:, y0c:y0c + th, x0c:x0c + tw] += w
+        return acc / np.maximum(wsum, 1e-6)
+
+    def predict(self, img: np.ndarray, cfg: PostConfig | None = None) -> tuple[Result, dict[str, np.ndarray]]:
+        probs = self.probs(img)
+        return analyze(probs, cfg), probs

cellquant/labels.py

@@ -0,0 +1,58 @@
+"""Label vocabulary shared by training, post-processing and the app."""
+from __future__ import annotations
+
+# The six CVAT labels exactly as they appear in the annotation exports.
+CELL_LABELS = (
+    "Cell, Antibody +",
+    "Cell, Antibody -",
+    "Cell, Nostril, Antibody +",
+    "Cell, Nostril, Antibody -",
+)
+NOSTRIL_LABELS = (
+    "Nostril in Nucleus",
+    "Nostril External of Nucleus",
+)
+ALL_LABELS = CELL_LABELS + NOSTRIL_LABELS
+
+# Display colours (RGB) used for overlays, one per label.
+LABEL_COLORS = {
+    "Cell, Antibody +": (0, 255, 0),
+    "Cell, Antibody -": (255, 0, 0),
+    "Cell, Nostril, Antibody +": (0, 255, 255),
+    "Cell, Nostril, Antibody -": (255, 0, 255),
+    "Nostril in Nucleus": (255, 255, 0),
+    "Nostril External of Nucleus": (255, 128, 0),
+}
+
+
+def is_cell_label(label: str) -> bool:
+    return label.startswith("Cell")
+
+
+def is_nostril_label(label: str) -> bool:
+    return label.startswith("Nostril")
+
+
+def cell_attributes(label: str) -> tuple[bool, bool]:
+    """Return (antibody_positive, has_nostril) for a cell label."""
+    if not is_cell_label(label):
+        raise ValueError(f"not a cell label: {label!r}")
+    antibody_positive = label.rstrip().endswith("+")
+    has_nostril = "Nostril" in label
+    return antibody_positive, has_nostril
+
+
+def cell_label(antibody_positive: bool, has_nostril: bool) -> str:
+    """Compose the CVAT cell label from its two attributes."""
+    sign = "+" if antibody_positive else "-"
+    return f"Cell, Nostril, Antibody {sign}" if has_nostril else f"Cell, Antibody {sign}"
+
+
+def nostril_label(in_nucleus: bool) -> str:
+    return "Nostril in Nucleus" if in_nucleus else "Nostril External of Nucleus"
+
+
+def nostril_in_nucleus(label: str) -> bool:
+    if not is_nostril_label(label):
+        raise ValueError(f"not a nostril label: {label!r}")
+    return "in Nucleus" in label

cellquant/losses.py

@@ -0,0 +1,48 @@
+"""Loss for the multi-head output (see model.py for the channel layout)."""
+from __future__ import annotations
+
+import torch
+import torch.nn.functional as F
+
+from .model import ANTIBODY_CH, CELLNOS_CH, CELL_SLICE, NOS_SLICE
+
+
+def soft_dice(probs: torch.Tensor, target_onehot: torch.Tensor, eps: float = 1.0) -> torch.Tensor:
+    """Mean soft Dice loss over the given channels (B, C, H, W)."""
+    dims = (0, 2, 3)
+    inter = (probs * target_onehot).sum(dims)
+    denom = probs.sum(dims) + target_onehot.sum(dims)
+    return (1 - (2 * inter + eps) / (denom + eps)).mean()
+
+
+def masked_bce(logit: torch.Tensor, target: torch.Tensor, mask: torch.Tensor) -> torch.Tensor:
+    l = F.binary_cross_entropy_with_logits(logit, target, reduction="none")
+    return (l * mask).sum() / mask.sum().clamp_min(1.0)
+
+
+def multitask_loss(out: torch.Tensor, t: dict[str, torch.Tensor]) -> tuple[torch.Tensor, dict[str, float]]:
+    dev = out.device
+    cell_logits = out[:, CELL_SLICE]
+    nos_logits = out[:, NOS_SLICE]
+    cell3 = t["cell3"].to(dev)
+    nos3 = t["nos3"].to(dev)
+    w_cell = torch.tensor([1.0, 1.0, 2.0], device=dev)
+    w_nos = torch.tensor([1.0, 4.0, 4.0], device=dev)
+    ce_cell = F.cross_entropy(cell_logits, cell3, weight=w_cell)
+    ce_nos = F.cross_entropy(nos_logits, nos3, weight=w_nos)
+    p_cell = cell_logits.softmax(1)
+    p_nos = nos_logits.softmax(1)
+    oh_cell = F.one_hot(cell3, 3).permute(0, 3, 1, 2).float()
+    oh_nos = F.one_hot(nos3, 3).permute(0, 3, 1, 2).float()
+    dice_cell = soft_dice(p_cell[:, 1:], oh_cell[:, 1:])
+    dice_nos = soft_dice(p_nos[:, 1:], oh_nos[:, 1:])
+    mask = t["cellmask"].to(dev)
+    bce_ab = masked_bce(out[:, ANTIBODY_CH], t["antibody"].to(dev), mask)
+    bce_cn = masked_bce(out[:, CELLNOS_CH], t["cellnos"].to(dev), mask)
+    total = ce_cell + dice_cell + ce_nos + dice_nos + bce_ab + bce_cn
+    parts = {
+        "ce_cell": ce_cell.item(), "dice_cell": dice_cell.item(),
+        "ce_nos": ce_nos.item(), "dice_nos": dice_nos.item(),
+        "bce_ab": bce_ab.item(), "bce_cn": bce_cn.item(), "total": total.item(),
+    }
+    return total, parts

cellquant/metrics.py

@@ -0,0 +1,167 @@
+"""Instance-level evaluation against CVAT ground truth."""
+from __future__ import annotations
+
+import numpy as np
+from scipy import ndimage as ndi
+from scipy.optimize import linear_sum_assignment
+
+from .labels import ALL_LABELS, CELL_LABELS, NOSTRIL_LABELS, cell_attributes, nostril_in_nucleus
+
+
+def iou_matrix(gt: np.ndarray, pred: np.ndarray) -> np.ndarray:
+    ng, npred = int(gt.max()), int(pred.max())
+    if ng == 0 or npred == 0:
+        return np.zeros((ng, npred), dtype=np.float64)
+    pairs = gt.astype(np.int64) * (npred + 1) + pred.astype(np.int64)
+    counts = np.bincount(pairs.ravel(), minlength=(ng + 1) * (npred + 1)).reshape(ng + 1, npred + 1)
+    inter = counts[1:, 1:].astype(np.float64)
+    area_g = counts[1:, :].sum(1, keepdims=True)
+    area_p = counts[:, 1:].sum(0, keepdims=True)
+    union = area_g + area_p - inter
+    return inter / np.maximum(union, 1)
+
+
+def match_by_iou(gt: np.ndarray, pred: np.ndarray, thr: float = 0.5) -> list[tuple[int, int, float]]:
+    """Hungarian one-to-one matching; returns (gt_id, pred_id, iou) pairs with iou >= thr."""
+    iou = iou_matrix(gt, pred)
+    if iou.size == 0:
+        return []
+    valid = iou >= thr
+    if not valid.any():
+        return []
+    # maximise the number of valid matches first, IoU only as a tie-break
+    r, c = linear_sum_assignment(-(valid.astype(np.float64) + iou * 1e-3))
+    return [(int(i) + 1, int(j) + 1, float(iou[i, j])) for i, j in zip(r, c) if valid[i, j]]
+
+
+def centroids(inst: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    n = int(inst.max())
+    if n == 0:
+        return np.zeros((0, 2)), np.zeros(0)
+    idx = np.arange(1, n + 1)
+    ones = np.ones_like(inst, dtype=np.float32)
+    c = np.array(ndi.center_of_mass(ones, inst, idx), dtype=np.float64)
+    a = np.array(ndi.sum_labels(ones, inst, idx), dtype=np.float64)
+    return c, a
+
+
+def match_by_centroid(gt: np.ndarray, pred: np.ndarray, base_thr: float = 6.0) -> list[tuple[int, int, float]]:
+    """Hungarian matching on centroid distance; a pair matches when the distance
+    is below max(base_thr, equivalent radius of the GT object)."""
+    cg, ag = centroids(gt)
+    cp, _ = centroids(pred)
+    if len(cg) == 0 or len(cp) == 0:
+        return []
+    d = np.sqrt(((cg[:, None, :] - cp[None, :, :]) ** 2).sum(-1))
+    thr = np.maximum(base_thr, np.sqrt(ag / np.pi))[:, None]
+    cost = np.where(d <= thr, d, 1e6)
+    r, c = linear_sum_assignment(cost)
+    return [(int(i) + 1, int(j) + 1, float(d[i, j])) for i, j in zip(r, c) if d[i, j] <= thr[i, 0]]
+
+
+def prf(tp: int, fp: int, fn: int) -> dict[str, float]:
+    p = tp / (tp + fp) if tp + fp else 0.0
+    r = tp / (tp + fn) if tp + fn else 0.0
+    f = 2 * p * r / (p + r) if p + r else 0.0
+    return {"tp": tp, "fp": fp, "fn": fn, "precision": p, "recall": r, "f1": f}
+
+
+def _class_scores(gt_labels: list[str], pred_labels: list[str], matches, classes) -> dict:
+    """Per-class P/R/F1 where a TP needs a matched instance with the same label."""
+    gt_matched = {g: p for g, p, _ in matches}
+    pred_matched = {p: g for g, p, _ in matches}
+    out = {}
+    for c in classes:
+        tp = sum(1 for g, p, _ in matches if gt_labels[g] == c and pred_labels[p] == c)
+        n_gt = sum(1 for l in gt_labels[1:] if l == c)
+        n_pred = sum(1 for l in pred_labels[1:] if l == c)
+        out[c] = prf(tp, n_pred - tp, n_gt - tp)
+        out[c]["gt_count"] = n_gt
+        out[c]["pred_count"] = n_pred
+    return out
+
+
+def match_by_centroid_in_mask(gt_inst: np.ndarray, pred_inst: np.ndarray) -> list[tuple[int, int, float]]:
+    """One-to-one matching where a predicted object matches the GT object that
+    contains its centroid (ties broken by IoU). Mirrors how a person counts."""
+    cp, _ = centroids(pred_inst)
+    if len(cp) == 0 or gt_inst.max() == 0:
+        return []
+    iou = iou_matrix(gt_inst, pred_inst)
+    H, W = gt_inst.shape
+    cost = np.full(iou.shape, 1e6)
+    for j, (cy, cx) in enumerate(cp):
+        g = int(gt_inst[min(H - 1, max(0, int(round(cy)))), min(W - 1, max(0, int(round(cx))))])
+        if g > 0:
+            cost[g - 1, j] = 1.0 - iou[g - 1, j]
+    r, c = linear_sum_assignment(cost)
+    return [(int(i) + 1, int(j) + 1, float(iou[i, j])) for i, j in zip(r, c) if cost[i, j] < 1e6]
+
+
+def evaluate_cells(gt_inst: np.ndarray, gt_labels: list[str], pred_inst: np.ndarray, pred_labels: list[str],
+                   iou_thr: float = 0.5) -> dict:
+    matches = match_by_iou(gt_inst, pred_inst, iou_thr)
+    n_gt, n_pred = int(gt_inst.max()), int(pred_inst.max())
+    det = prf(len(matches), n_pred - len(matches), n_gt - len(matches))
+    det["mean_iou_matched"] = float(np.mean([m[2] for m in matches])) if matches else 0.0
+    # looser, count-oriented matchings
+    m30 = match_by_iou(gt_inst, pred_inst, 0.3)
+    det["iou30"] = prf(len(m30), n_pred - len(m30), n_gt - len(m30))
+    mc = match_by_centroid_in_mask(gt_inst, pred_inst)
+    det["centroid"] = prf(len(mc), n_pred - len(mc), n_gt - len(mc))
+    # attribute accuracy on matched pairs
+    ab_ok = nos_ok = both_ok = 0
+    conf: dict[str, dict[str, int]] = {c: {d: 0 for d in CELL_LABELS} for c in CELL_LABELS}
+    for g, p, _ in matches:
+        ga, gn = cell_attributes(gt_labels[g])
+        pa, pn = cell_attributes(pred_labels[p])
+        ab_ok += ga == pa
+        nos_ok += gn == pn
+        both_ok += (ga == pa) and (gn == pn)
+        conf[gt_labels[g]][pred_labels[p]] += 1
+    nm = max(len(matches), 1)
+    return {
+        "detection": det,
+        "attribute_accuracy": {"antibody": ab_ok / nm, "nostril": nos_ok / nm, "both": both_ok / nm, "n_matched": len(matches)},
+        "per_class": _class_scores(gt_labels, pred_labels, matches, CELL_LABELS),
+        "confusion": conf,
+        "n_gt": n_gt,
+        "n_pred": n_pred,
+    }
+
+
+def evaluate_nostrils(gt_inst: np.ndarray, gt_labels: list[str], pred_inst: np.ndarray, pred_labels: list[str],
+                      dist_thr: float = 6.0) -> dict:
+    matches = match_by_centroid(gt_inst, pred_inst, dist_thr)
+    n_gt, n_pred = int(gt_inst.max()), int(pred_inst.max())
+    det = prf(len(matches), n_pred - len(matches), n_gt - len(matches))
+    det["mean_dist_matched"] = float(np.mean([m[2] for m in matches])) if matches else 0.0
+    type_ok = sum(1 for g, p, _ in matches if nostril_in_nucleus(gt_labels[g]) == nostril_in_nucleus(pred_labels[p]))
+    return {
+        "detection": det,
+        "type_accuracy": type_ok / max(len(matches), 1),
+        "per_class": _class_scores(gt_labels, pred_labels, matches, NOSTRIL_LABELS),
+        "n_gt": n_gt,
+        "n_pred": n_pred,
+    }
+
+
+def count_errors(gt_counts: dict[str, int], pred_counts: dict[str, int]) -> dict[str, dict]:
+    out = {}
+    for lab in ALL_LABELS:
+        g, p = int(gt_counts.get(lab, 0)), int(pred_counts.get(lab, 0))
+        out[lab] = {"gt": g, "pred": p, "abs_err": abs(p - g), "rel_err": (abs(p - g) / g) if g else (0.0 if p == 0 else float("inf"))}
+    return out
+
+
+def micro_average(per_image: list[dict], classes) -> dict:
+    """Sum TP/FP/FN over images and recompute P/R/F1 per class."""
+    out = {}
+    for c in classes:
+        tp = sum(r[c]["tp"] for r in per_image)
+        fp = sum(r[c]["fp"] for r in per_image)
+        fn = sum(r[c]["fn"] for r in per_image)
+        out[c] = prf(tp, fp, fn)
+        out[c]["gt_count"] = sum(r[c]["gt_count"] for r in per_image)
+        out[c]["pred_count"] = sum(r[c]["pred_count"] for r in per_image)
+    return out

cellquant/model.py

@@ -0,0 +1,99 @@
+"""Multi-head UNet for nucleus / antibody / puncta segmentation.
+
+Output channels (all at full input resolution):
+    0..2  cell classes      : background / nucleus interior / nucleus border (softmax)
+    3     antibody logit    : P(antibody positive)      (meaningful on nucleus pixels)
+    4     nostril-attr logit: P(nucleus contains punctum) (meaningful on nucleus pixels)
+    5..7  punctum classes   : background / in nucleus / external (softmax)
+"""
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+N_OUT = 8
+CELL_SLICE = slice(0, 3)
+ANTIBODY_CH = 3
+CELLNOS_CH = 4
+NOS_SLICE = slice(5, 8)
+
+# ImageNet statistics; inputs are RGB in [0, 1].
+MEAN = (0.485, 0.456, 0.406)
+STD = (0.229, 0.224, 0.225)
+
+
+def _block(cin: int, cout: int) -> nn.Sequential:
+    return nn.Sequential(
+        nn.Conv2d(cin, cout, 3, padding=1, bias=False), nn.BatchNorm2d(cout), nn.ReLU(inplace=True),
+        nn.Conv2d(cout, cout, 3, padding=1, bias=False), nn.BatchNorm2d(cout), nn.ReLU(inplace=True),
+    )
+
+
+class CellUNet(nn.Module):
+    """UNet with a timm ResNet encoder (features at strides 2..32) and a
+    full-resolution refinement stage so that 5-pixel puncta are resolved."""
+
+    def __init__(self, encoder: str = "resnet34", pretrained: bool = False, n_out: int = N_OUT):
+        super().__init__()
+        import timm
+        self.encoder_name = encoder
+        self.encoder = timm.create_model(encoder, pretrained=pretrained, features_only=True)
+        chs = list(self.encoder.feature_info.channels())          # e.g. [64, 64, 128, 256, 512]
+        self.reductions = list(self.encoder.feature_info.reduction())
+        dec = []
+        prev = chs[-1]
+        for c in reversed(chs[:-1]):
+            dec.append(_block(prev + c, c))
+            prev = c
+        self.decoder = nn.ModuleList(dec)
+        self.stem = nn.Sequential(nn.Conv2d(3, 16, 3, padding=1, bias=False), nn.BatchNorm2d(16), nn.ReLU(inplace=True))
+        self.full = _block(prev + 16, 32)
+        self.head = nn.Conv2d(32, n_out, 1)
+        self.register_buffer("mean", torch.tensor(MEAN).view(1, 3, 1, 1))
+        self.register_buffer("std", torch.tensor(STD).view(1, 3, 1, 1))
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """x: (B, 3, H, W) float in [0, 1]; H and W must be multiples of 32."""
+        H, W = x.shape[-2:]
+        xn = (x - self.mean) / self.std
+        feats = self.encoder(xn)
+        y = feats[-1]
+        for blk, f in zip(self.decoder, reversed(feats[:-1])):
+            y = F.interpolate(y, size=f.shape[-2:], mode="bilinear", align_corners=False)
+            y = blk(torch.cat([y, f], dim=1))
+        y = F.interpolate(y, size=(H, W), mode="bilinear", align_corners=False)
+        y = self.full(torch.cat([y, self.stem(x)], dim=1))
+        return self.head(y)
+
+
+def pad_to_multiple(x: torch.Tensor, m: int = 32) -> tuple[torch.Tensor, tuple[int, int]]:
+    """Reflect-pad the bottom/right of (B, C, H, W) to multiples of ``m``."""
+    H, W = x.shape[-2:]
+    ph = (m - H % m) % m
+    pw = (m - W % m) % m
+    if ph or pw:
+        # reflect padding requires pad < dim; fall back to replicate for tiny inputs
+        mode = "reflect" if (ph < H and pw < W) else "replicate"
+        x = F.pad(x, (0, pw, 0, ph), mode=mode)
+    return x, (ph, pw)
+
+
+def save_checkpoint(model: CellUNet, path: str, extra: dict | None = None) -> None:
+    payload = {
+        "state_dict": model.state_dict(),
+        "encoder": model.encoder_name,
+        "n_out": model.head.out_channels,
+    }
+    if extra:
+        payload.update(extra)
+    torch.save(payload, path)
+
+
+def load_checkpoint(path: str, map_location: str = "cpu") -> tuple[CellUNet, dict]:
+    ck = torch.load(path, map_location=map_location, weights_only=False)
+    model = CellUNet(ck["encoder"], pretrained=False, n_out=ck.get("n_out", N_OUT))
+    model.load_state_dict(ck["state_dict"])
+    model.eval()
+    meta = {k: v for k, v in ck.items() if k != "state_dict"}
+    return model, meta

cellquant/postprocess.py

@@ -0,0 +1,230 @@
+"""Turn network probabilities into nucleus / punctum instances, labels and counts."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+import numpy as np
+from scipy import ndimage as ndi
+from skimage.segmentation import find_boundaries, watershed
+
+from .labels import ALL_LABELS, LABEL_COLORS, cell_label, nostril_label
+from .model import ANTIBODY_CH, CELLNOS_CH, CELL_SLICE, NOS_SLICE
+
+
+@dataclass
+class PostConfig:
+    cell_fg_thr: float = 0.5       # P(interior) + P(border) > thr  -> nucleus foreground
+    marker_thr: float = 0.5        # P(interior) > thr               -> watershed markers
+    min_marker_area: int = 12      # px
+    min_cell_area: int = 50        # px (smallest traced nucleus in the training set is 35 px)
+    nos_fg_thr: float = 0.5        # 1 - P(background) > thr         -> punctum foreground
+    min_nos_area: int = 3          # px
+    antibody_thr: float = 0.5
+    cellnos_thr: float = 0.5
+    nostril_rule: str = "head"     # "head": punctum type from the network; "geometric": inside a nucleus => in nucleus
+    cellnos_rule: str = "contains"  # "head" | "contains" | "either": how a nucleus gets the "Nostril" attribute
+                                    # ("contains" mirrors the annotation protocol and scored best in cross-validation)
+
+
+def logits_to_probs(logits: np.ndarray) -> dict[str, np.ndarray]:
+    """logits: (8, H, W) float -> dict of probabilities."""
+    def softmax(z):
+        z = z - z.max(axis=0, keepdims=True)
+        e = np.exp(z)
+        return e / e.sum(axis=0, keepdims=True)
+    def sigmoid(z):
+        return 1.0 / (1.0 + np.exp(-z))
+    return {
+        "cell": softmax(logits[CELL_SLICE].astype(np.float32)),
+        "antibody": sigmoid(logits[ANTIBODY_CH].astype(np.float32)),
+        "cellnos": sigmoid(logits[CELLNOS_CH].astype(np.float32)),
+        "nos": softmax(logits[NOS_SLICE].astype(np.float32)),
+    }
+
+
+def segment_cells(p_cell: np.ndarray, cfg: PostConfig) -> np.ndarray:
+    """p_cell: (3, H, W) softmax (bg, interior, border) -> int32 instance map."""
+    p_int, p_bor = p_cell[1], p_cell[2]
+    fg = (p_int + p_bor) > cfg.cell_fg_thr
+    markers, n = ndi.label(p_int > cfg.marker_thr)
+    if n:
+        sizes = np.bincount(markers.ravel())
+        small = sizes < cfg.min_marker_area
+        small[0] = False
+        markers[small[markers]] = 0
+        markers, n = ndi.label(markers > 0)
+    inst = watershed(-p_int, markers, mask=fg) if n else np.zeros(fg.shape, np.int32)
+    inst = inst.astype(np.int32)
+    # foreground components that received no marker become instances of their own
+    orphan, m = ndi.label(fg & (inst == 0))
+    if m:
+        sizes = np.bincount(orphan.ravel())
+        keep = sizes >= cfg.min_cell_area
+        keep[0] = False
+        orphan[~keep[orphan]] = 0
+        orphan_ids = np.unique(orphan)
+        orphan_ids = orphan_ids[orphan_ids > 0]
+        base = inst.max()
+        for j, oid in enumerate(orphan_ids, start=1):
+            inst[orphan == oid] = base + j
+    inst = _fill_and_filter(inst, cfg.min_cell_area)
+    return inst
+
+
+def _fill_and_filter(inst: np.ndarray, min_area: int) -> np.ndarray:
+    """Fill holes inside every instance, drop instances below ``min_area`` and
+    keep only the largest connected piece of each instance; relabel 1..n."""
+    out = np.zeros_like(inst)
+    nxt = 1
+    for i, sl in enumerate(ndi.find_objects(inst), start=1):
+        if sl is None:
+            continue
+        m = inst[sl] == i
+        lab, k = ndi.label(m)
+        if k > 1:  # keep the largest piece
+            sizes = np.bincount(lab.ravel())
+            sizes[0] = 0
+            m = lab == sizes.argmax()
+        # fill holes, but never absorb pixels that belong to another instance
+        m = m | (ndi.binary_fill_holes(m) & (inst[sl] == 0))
+        region = out[sl]
+        w = m & (region == 0)
+        if w.sum() < min_area:
+            continue
+        region[w] = nxt
+        nxt += 1
+    return out
+
+
+def segment_nostrils(p_nos: np.ndarray, cfg: PostConfig) -> np.ndarray:
+    fg = (1.0 - p_nos[0]) > cfg.nos_fg_thr
+    inst, n = ndi.label(fg)  # 4-connectivity keeps neighbouring puncta apart
+    if n == 0:
+        return inst.astype(np.int32)
+    sizes = np.bincount(inst.ravel())
+    keep = sizes >= cfg.min_nos_area
+    keep[0] = False
+    inst[~keep[inst]] = 0
+    inst, _ = ndi.label(inst > 0)
+    return inst.astype(np.int32)
+
+
+@dataclass
+class Result:
+    cell_inst: np.ndarray
+    nostril_inst: np.ndarray
+    cells: list[dict] = field(default_factory=list)
+    nostrils: list[dict] = field(default_factory=list)
+    counts: dict[str, int] = field(default_factory=dict)
+    config: dict = field(default_factory=dict)
+
+    @property
+    def cell_labels(self) -> list[str]:
+        return [""] + [c["label"] for c in self.cells]
+
+    @property
+    def nostril_labels(self) -> list[str]:
+        return [""] + [n["label"] for n in self.nostrils]
+
+
+def analyze(probs: dict[str, np.ndarray], cfg: PostConfig | None = None) -> Result:
+    cfg = cfg or PostConfig()
+    cell_inst = segment_cells(probs["cell"], cfg)
+    nos_inst = segment_nostrils(probs["nos"], cfg)
+    n_cells = int(cell_inst.max())
+    n_nos = int(nos_inst.max())
+    H, W = cell_inst.shape
+    idx = np.arange(1, n_cells + 1)
+    # per-nucleus statistics
+    if n_cells:
+        areas = ndi.sum_labels(np.ones_like(cell_inst, dtype=np.float32), cell_inst, idx)
+        ab = ndi.mean(probs["antibody"], cell_inst, idx)
+        cn = ndi.mean(probs["cellnos"], cell_inst, idx)
+        cents = ndi.center_of_mass(np.ones_like(cell_inst, dtype=np.float32), cell_inst, idx)
+        slices = ndi.find_objects(cell_inst)
+    # puncta
+    nostrils: list[dict] = []
+    contains_in: np.ndarray = np.zeros(n_cells + 1, dtype=np.int32)
+    contains_any: np.ndarray = np.zeros(n_cells + 1, dtype=np.int32)
+    if n_nos:
+        nidx = np.arange(1, n_nos + 1)
+        nareas = ndi.sum_labels(np.ones_like(nos_inst, dtype=np.float32), nos_inst, nidx)
+        p_in = ndi.sum_labels(probs["nos"][1], nos_inst, nidx)
+        p_ext = ndi.sum_labels(probs["nos"][2], nos_inst, nidx)
+        ncents = ndi.center_of_mass(np.ones_like(nos_inst, dtype=np.float32), nos_inst, nidx)
+        for j in range(n_nos):
+            cy, cx = ncents[j]
+            r, c = min(H - 1, max(0, int(round(cy)))), min(W - 1, max(0, int(round(cx))))
+            cell_id = int(cell_inst[r, c])
+            if cell_id == 0:  # a punctum touching a nucleus counts as inside it (majority of its pixels)
+                ids = cell_inst[nos_inst == j + 1]
+                ids = ids[ids > 0]
+                if ids.size and ids.size * 2 >= nareas[j]:
+                    cell_id = int(np.bincount(ids).argmax())
+            head_in = bool(p_in[j] >= p_ext[j])
+            in_nuc = head_in if cfg.nostril_rule == "head" else cell_id > 0
+            nostrils.append({
+                "id": j + 1,
+                "label": nostril_label(in_nuc),
+                "area_px": float(nareas[j]),
+                "centroid_xy": [float(cx), float(cy)],
+                "p_in_nucleus": float(p_in[j] / (p_in[j] + p_ext[j] + 1e-9)),
+                "cell_id": cell_id,
+            })
+            if cell_id:
+                contains_any[cell_id] += 1
+                if in_nuc:
+                    contains_in[cell_id] += 1
+    cells: list[dict] = []
+    for i in range(n_cells):
+        cid = i + 1
+        head_flag = bool(cn[i] > cfg.cellnos_thr)
+        cont_flag = bool(contains_in[cid] > 0)
+        if cfg.cellnos_rule == "head":
+            has_nos = head_flag
+        elif cfg.cellnos_rule == "contains":
+            has_nos = cont_flag
+        else:
+            has_nos = head_flag or cont_flag
+        sl = slices[i]
+        cells.append({
+            "id": cid,
+            "label": cell_label(bool(ab[i] > cfg.antibody_thr), has_nos),
+            "area_px": float(areas[i]),
+            "centroid_xy": [float(cents[i][1]), float(cents[i][0])],
+            "bbox_xyxy": [int(sl[1].start), int(sl[0].start), int(sl[1].stop), int(sl[0].stop)],
+            "p_antibody": float(ab[i]),
+            "p_nostril": float(cn[i]),
+            "n_puncta_inside": int(contains_in[cid]),
+        })
+    counts = {lab: 0 for lab in ALL_LABELS}
+    for c in cells:
+        counts[c["label"]] += 1
+    for n_ in nostrils:
+        counts[n_["label"]] += 1
+    return Result(cell_inst, nos_inst, cells, nostrils, counts, asdict(cfg))
+
+
+def render_overlay(img: np.ndarray, res: Result, thickness: int = 1) -> np.ndarray:
+    """Draw coloured outlines (nuclei: inner boundary, puncta: outer ring) on a copy of ``img``."""
+    out = img.copy()
+    if res.cells:
+        lut = np.zeros((len(res.cells) + 1, 3), dtype=np.uint8)
+        for c in res.cells:
+            lut[c["id"]] = LABEL_COLORS[c["label"]]
+        b = find_boundaries(res.cell_inst, mode="inner")
+        if thickness > 1:
+            b = ndi.binary_dilation(b, iterations=thickness - 1) & (res.cell_inst > 0)
+        out[b] = lut[res.cell_inst[b]]
+    if res.nostrils:
+        lut = np.zeros((len(res.nostrils) + 1, 3), dtype=np.uint8)
+        for n_ in res.nostrils:
+            lut[n_["id"]] = LABEL_COLORS[n_["label"]]
+        dil = ndi.grey_dilation(res.nostril_inst, size=(3, 3))
+        ring = (dil > 0) & (res.nostril_inst == 0)
+        out[ring] = lut[dil[ring]]
+    return out
+
+
+def result_to_json(res: Result) -> dict:
+    return {"counts": res.counts, "cells": res.cells, "nostrils": res.nostrils, "config": res.config}

evaluate.py

@@ -0,0 +1,414 @@
+#!/usr/bin/env python3
+"""Leave-one-image-out cross-validation with repeated, perturbed tests per image.
+
+    python evaluate.py cv    --data-dir DATA --runs-dir runs/cv --iters 3000
+    python evaluate.py final --data-dir DATA --weights weights/cellquant.pt
+
+``cv`` trains one model per annotated image with that image held out (unless the
+fold checkpoint already exists), then tests the held-out image many times:
+
+  * base run (no TTA), TTA x4 and TTA x8
+  * 8 dihedral variants (rotate/flip the image, predict, undo the transform)
+  * 6 photometric perturbations (per-channel gain, gamma, noise; fixed seeds)
+  * 3 identical repeats to prove determinism
+  * post-processing rule variants (how puncta get their type and how nuclei
+    get the "Nostril" attribute)
+
+``final`` reports the fit of one model on its own training images (NOT a
+generalisation estimate) and writes overlays for un-annotated images.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import time
+
+import numpy as np
+from PIL import Image
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from cellquant.annotations import discover, load_image, rasterize  # noqa: E402
+from cellquant.infer import Predictor  # noqa: E402
+from cellquant.labels import ALL_LABELS, CELL_LABELS, NOSTRIL_LABELS  # noqa: E402
+from cellquant.metrics import count_errors, evaluate_cells, evaluate_nostrils, micro_average  # noqa: E402
+from cellquant.postprocess import PostConfig, Result, analyze, render_overlay  # noqa: E402
+
+DIHEDRAL = [(k, f) for f in (False, True) for k in range(4)]
+
+
+def fwd_np(a: np.ndarray, k: int, flip: bool) -> np.ndarray:
+    if flip:
+        a = a[..., ::-1]
+    return np.rot90(a, k, axes=(-2, -1))
+
+
+def inv_np(a: np.ndarray, k: int, flip: bool) -> np.ndarray:
+    a = np.rot90(a, -k, axes=(-2, -1))
+    if flip:
+        a = a[..., ::-1]
+    return np.ascontiguousarray(a)
+
+
+def photometric(img: np.ndarray, seed: int) -> np.ndarray:
+    rng = np.random.default_rng(seed)
+    x = img.astype(np.float32) / 255.0
+    gain = rng.uniform(0.7, 1.4, size=3).astype(np.float32)
+    gamma = float(rng.uniform(0.8, 1.25))
+    x = np.clip(x * gain, 0, 1) ** gamma
+    x = x + rng.normal(0, float(rng.uniform(0, 0.02)), size=x.shape).astype(np.float32)
+    return (np.clip(x, 0, 1) * 255).round().astype(np.uint8)
+
+
+def fp_analysis(img: np.ndarray, R, res: Result) -> dict:
+    """Characterise unmatched predicted nuclei: how many overlap an annotated nucleus
+    at all (outline/split disagreement) versus none (extra detection), and how
+    bright/large they are compared with matched ones."""
+    from scipy import ndimage as ndi
+    from cellquant.metrics import match_by_iou
+    m = match_by_iou(R.cell_inst, res.cell_inst, 0.5)
+    mp = {p for _, p, _ in m}
+    mg = {g for g, _, _ in m}
+    n_pred = int(res.cell_inst.max())
+    if n_pred == 0:
+        return {"n_fp": 0}
+    ids = np.arange(1, n_pred + 1)
+    blue = ndi.mean(img[..., 2].astype(np.float32), res.cell_inst, ids)
+    areas = np.bincount(res.cell_inst.ravel())[1:]
+    gt_cover = ndi.mean((R.cell_inst > 0).astype(np.float32), res.cell_inst, ids)
+    fp = np.array([i not in mp for i in ids])
+    matched = ~fp
+    fn_ids = [g for g in range(1, R.n_cells + 1) if g not in mg]
+    fn_cover = [float((res.cell_inst[R.cell_inst == g] > 0).mean()) for g in fn_ids]
+    return {
+        "n_fp": int(fp.sum()),
+        "n_fp_overlapping_gt": int((fp & (gt_cover > 0.3)).sum()),
+        "n_fp_no_gt_overlap": int((fp & (gt_cover <= 0.3)).sum()),
+        "fp_median_blue": float(np.median(blue[fp])) if fp.any() else None,
+        "matched_median_blue": float(np.median(blue[matched])) if matched.any() else None,
+        "fp_median_area": float(np.median(areas[fp])) if fp.any() else None,
+        "matched_median_area": float(np.median(areas[matched])) if matched.any() else None,
+        "n_fn": len(fn_ids),
+        "n_fn_covered_by_prediction": int(sum(c > 0.3 for c in fn_cover)),
+    }
+
+
+def matched_pairs(R, res: Result) -> list[dict]:
+    """Per matched nucleus (IoU >= 0.5): GT label and the network's attribute probabilities,
+    so that attribute thresholds can be studied across all held-out images."""
+    from cellquant.metrics import match_by_iou
+    by_id = {c["id"]: c for c in res.cells}
+    out = []
+    for g, p, iou in match_by_iou(R.cell_inst, res.cell_inst, 0.5):
+        c = by_id[p]
+        out.append({"gt": R.cell_labels[g], "pred": c["label"], "p_antibody": c["p_antibody"],
+                    "p_nostril": c["p_nostril"], "n_puncta_inside": c["n_puncta_inside"], "iou": iou})
+    return out
+
+
+def score(R, res: Result, gt_counts: dict, img: np.ndarray | None = None) -> dict:
+    ce = evaluate_cells(R.cell_inst, R.cell_labels, res.cell_inst, res.cell_labels)
+    ne = evaluate_nostrils(R.nostril_inst, R.nostril_labels, res.nostril_inst, res.nostril_labels)
+    return {
+        "cells": ce,
+        "nostrils": ne,
+        "counts": count_errors(gt_counts, res.counts),
+        "fp_analysis": fp_analysis(img, R, res) if img is not None else None,
+        "pairs": matched_pairs(R, res) if img is not None else None,
+        "summary": {
+            "cell_det_f1": ce["detection"]["f1"],
+            "cell_det_precision": ce["detection"]["precision"],
+            "cell_det_recall": ce["detection"]["recall"],
+            "cell_mean_iou": ce["detection"]["mean_iou_matched"],
+            "cell_det_f1_iou30": ce["detection"]["iou30"]["f1"],
+            "cell_det_f1_centroid": ce["detection"]["centroid"]["f1"],
+            "cell_attr_antibody": ce["attribute_accuracy"]["antibody"],
+            "cell_attr_nostril": ce["attribute_accuracy"]["nostril"],
+            "cell_attr_both": ce["attribute_accuracy"]["both"],
+            "nos_det_f1": ne["detection"]["f1"],
+            "nos_det_precision": ne["detection"]["precision"],
+            "nos_det_recall": ne["detection"]["recall"],
+            "nos_type_acc": ne["type_accuracy"],
+            **{f"f1[{c}]": ce["per_class"][c]["f1"] for c in CELL_LABELS},
+            **{f"f1[{c}]": ne["per_class"][c]["f1"] for c in NOSTRIL_LABELS},
+        },
+    }
+
+
+def inst_hash(res: Result) -> str:
+    h = hashlib.sha256()
+    h.update(res.cell_inst.tobytes())
+    h.update(res.nostril_inst.tobytes())
+    h.update(json.dumps(res.counts, sort_keys=True).encode())
+    return h.hexdigest()[:16]
+
+
+def test_image(weights: str, img: np.ndarray, R, gt_counts: dict, device: str, out_prefix: str | None = None) -> dict:
+    cfg = PostConfig()
+    out: dict = {"runs": {}}
+    p1 = Predictor(weights, device=device, tta=1)
+    # base + determinism
+    hashes = []
+    for i in range(3):
+        res, probs = p1.predict(img, cfg)
+        hashes.append(inst_hash(res))
+    base_res, base_probs = res, probs
+    out["deterministic"] = len(set(hashes)) == 1
+    out["hashes"] = hashes
+    out["runs"]["base"] = score(R, base_res, gt_counts, img)
+    out["base_counts"] = base_res.counts
+    if out_prefix:
+        Image.fromarray(render_overlay(img, base_res)).save(out_prefix + "_pred.png")
+    # TTA
+    for tta in (4, 8):
+        res, _ = Predictor(weights, device=device, tta=tta).predict(img, cfg)
+        out["runs"][f"tta{tta}"] = score(R, res, gt_counts)
+    # dihedral robustness
+    for k, f in DIHEDRAL:
+        timg = np.ascontiguousarray(fwd_np(np.moveaxis(img, -1, 0), k, f))
+        timg = np.moveaxis(timg, 0, -1)
+        probs = p1.probs(timg)
+        probs = {kk: inv_np(v, k, f) for kk, v in probs.items()}
+        res = analyze(probs, cfg)
+        out["runs"][f"dihedral_k{k}_f{int(f)}"] = score(R, res, gt_counts)
+    # photometric perturbations
+    for seed in range(6):
+        res, _ = p1.predict(photometric(img, 1000 + seed), cfg)
+        out["runs"][f"photometric_{seed}"] = score(R, res, gt_counts)
+    # post-processing rule variants (same probabilities as the base run)
+    for nr in ("head", "geometric"):
+        for cr in ("head", "contains", "either"):
+            res = analyze(base_probs, PostConfig(nostril_rule=nr, cellnos_rule=cr))
+            out["runs"][f"rule_nos={nr}_cell={cr}"] = score(R, res, gt_counts)
+    return out
+
+
+def aggregate(per_key: dict[str, dict]) -> dict:
+    keys = sorted(per_key)
+    agg: dict = {"images": keys}
+    # micro-averaged per-class scores on the base run
+    cells = [per_key[k]["runs"]["base"]["cells"]["per_class"] for k in keys]
+    nos = [per_key[k]["runs"]["base"]["nostrils"]["per_class"] for k in keys]
+    agg["micro_base"] = {**micro_average(cells, CELL_LABELS), **micro_average(nos, NOSTRIL_LABELS)}
+    for variant in ("tta4", "tta8"):
+        cells = [per_key[k]["runs"][variant]["cells"]["per_class"] for k in keys]
+        nos = [per_key[k]["runs"][variant]["nostrils"]["per_class"] for k in keys]
+        agg[f"micro_{variant}"] = {**micro_average(cells, CELL_LABELS), **micro_average(nos, NOSTRIL_LABELS)}
+    # detection totals
+    for variant in ("base", "tta4", "tta8"):
+        tp = sum(per_key[k]["runs"][variant]["cells"]["detection"]["tp"] for k in keys)
+        fp = sum(per_key[k]["runs"][variant]["cells"]["detection"]["fp"] for k in keys)
+        fn = sum(per_key[k]["runs"][variant]["cells"]["detection"]["fn"] for k in keys)
+        ntp = sum(per_key[k]["runs"][variant]["nostrils"]["detection"]["tp"] for k in keys)
+        nfp = sum(per_key[k]["runs"][variant]["nostrils"]["detection"]["fp"] for k in keys)
+        nfn = sum(per_key[k]["runs"][variant]["nostrils"]["detection"]["fn"] for k in keys)
+        from cellquant.metrics import prf
+        agg[f"detection_{variant}"] = {"cells": prf(tp, fp, fn), "nostrils": prf(ntp, nfp, nfn)}
+        for loose in ("iou30", "centroid"):
+            ltp = sum(per_key[k]["runs"][variant]["cells"]["detection"][loose]["tp"] for k in keys)
+            lfp = sum(per_key[k]["runs"][variant]["cells"]["detection"][loose]["fp"] for k in keys)
+            lfn = sum(per_key[k]["runs"][variant]["cells"]["detection"][loose]["fn"] for k in keys)
+            agg[f"detection_{variant}"][f"cells_{loose}"] = prf(ltp, lfp, lfn)
+    # per-image summary table + robustness (mean/std over dihedral & photometric runs)
+    summ = {}
+    for k in keys:
+        runs = per_key[k]["runs"]
+        rob = [v["summary"] for n, v in runs.items() if n.startswith(("dihedral", "photometric"))]
+        rob_stats = {}
+        for m in ("cell_det_f1", "cell_attr_both", "nos_det_f1", "nos_type_acc"):
+            vals = np.array([r[m] for r in rob])
+            rob_stats[m] = {"mean": float(vals.mean()), "std": float(vals.std()), "min": float(vals.min()), "max": float(vals.max()), "n": int(len(vals))}
+        summ[k] = {"base": runs["base"]["summary"], "tta4": runs["tta4"]["summary"], "tta8": runs["tta8"]["summary"],
+                   "robustness": rob_stats, "deterministic": per_key[k]["deterministic"],
+                   "counts": runs["base"]["counts"], "fp_analysis": runs["base"].get("fp_analysis")}
+    agg["per_image"] = summ
+    # rule variants: mean cell_attr_both and nostril type acc across images
+    rules = {}
+    for n in per_key[keys[0]]["runs"]:
+        if n.startswith("rule_"):
+            nm = [per_key[k]["runs"][n]["cells"]["attribute_accuracy"]["n_matched"] for k in keys]
+            ok = [per_key[k]["runs"][n]["cells"]["attribute_accuracy"]["both"] * m for k, m in zip(keys, nm)]
+            ntp = [per_key[k]["runs"][n]["nostrils"]["detection"]["tp"] for k in keys]
+            tok = [per_key[k]["runs"][n]["nostrils"]["type_accuracy"] * t for k, t in zip(keys, ntp)]
+            rules[n] = {
+                "pooled_cell_attr_both": float(sum(ok) / max(1, sum(nm))),
+                "pooled_nos_type_acc": float(sum(tok) / max(1, sum(ntp))),
+                "micro_f1": {**micro_average([per_key[k]["runs"][n]["cells"]["per_class"] for k in keys], CELL_LABELS),
+                             **micro_average([per_key[k]["runs"][n]["nostrils"]["per_class"] for k in keys], NOSTRIL_LABELS)},
+            }
+    agg["rule_variants"] = rules
+    agg["all_deterministic"] = all(per_key[k]["deterministic"] for k in keys)
+    # antibody threshold sweep on all held-out matched nuclei (base run)
+    pairs = [p for k in keys for p in (per_key[k]["runs"]["base"].get("pairs") or [])]
+    if pairs:
+        from cellquant.labels import cell_attributes
+        y = np.array([cell_attributes(p["gt"])[0] for p in pairs])      # True = antibody +
+        s_ = np.array([p["p_antibody"] for p in pairs])
+        sweep = []
+        for thr in np.round(np.arange(0.3, 0.91, 0.05), 2):
+            pred = s_ > thr
+            tp_neg = int((~pred & ~y).sum()); fp_neg = int((~pred & y).sum()); fn_neg = int((pred & ~y).sum())
+            from cellquant.metrics import prf
+            r = prf(tp_neg, fp_neg, fn_neg)
+            sweep.append({"thr": float(thr), "neg_precision": r["precision"], "neg_recall": r["recall"], "neg_f1": r["f1"],
+                          "accuracy": float((pred == y).mean())})
+        agg["antibody_threshold_sweep"] = {"n_matched": int(len(y)), "n_negative": int((~y).sum()), "sweep": sweep}
+    return agg
+
+
+def fmt_pct(x: float) -> str:
+    return f"{100*x:5.1f}%"
+
+
+def write_report(agg: dict, path: str, title: str, note: str = "") -> None:
+    L = [f"# {title}", ""]
+    if note:
+        L += [note, ""]
+    L += ["## Micro-averaged per-class scores (base run, no TTA)", "",
+          "| Label | GT | Pred | TP | FP | FN | Precision | Recall | F1 |", "|---|---:|---:|---:|---:|---:|---:|---:|---:|"]
+    for lab in ALL_LABELS:
+        r = agg["micro_base"][lab]
+        L.append(f"| {lab} | {r['gt_count']} | {r['pred_count']} | {r['tp']} | {r['fp']} | {r['fn']} | {fmt_pct(r['precision'])} | {fmt_pct(r['recall'])} | {fmt_pct(r['f1'])} |")
+    L += ["", "Class-agnostic detection (IoU >= 0.5 for nuclei; centroid distance for puncta):", ""]
+    for v in ("base", "tta4", "tta8"):
+        c, n = agg[f"detection_{v}"]["cells"], agg[f"detection_{v}"]["nostrils"]
+        c3, cc = agg[f"detection_{v}"]["cells_iou30"], agg[f"detection_{v}"]["cells_centroid"]
+        L.append(f"- {v}: nuclei P {fmt_pct(c['precision'])} R {fmt_pct(c['recall'])} F1 {fmt_pct(c['f1'])} (IoU≥0.5); F1 {fmt_pct(c3['f1'])} (IoU≥0.3); F1 {fmt_pct(cc['f1'])} (centroid-in-nucleus) | puncta P {fmt_pct(n['precision'])} R {fmt_pct(n['recall'])} F1 {fmt_pct(n['f1'])}")
+    L += ["", "## Per-image results (each image held out of training)", "",
+          "| Image | Nuclei F1 (IoU≥0.5) | F1 (IoU≥0.3) | F1 (centroid) | mean IoU | Antibody acc | Nostril-attr acc | Puncta F1 | Puncta type acc | Deterministic |", "|---|---:|---:|---:|---:|---:|---:|---:|---:|---|"]
+    for k, s in agg["per_image"].items():
+        b = s["base"]
+        L.append(f"| {k} | {fmt_pct(b['cell_det_f1'])} | {fmt_pct(b['cell_det_f1_iou30'])} | {fmt_pct(b['cell_det_f1_centroid'])} | {b['cell_mean_iou']:.3f} | {fmt_pct(b['cell_attr_antibody'])} | {fmt_pct(b['cell_attr_nostril'])} | {fmt_pct(b['nos_det_f1'])} | {fmt_pct(b['nos_type_acc'])} | {'yes' if s['deterministic'] else 'NO'} |")
+    L += ["", "## Repeated tests per image (8 rotations/flips + 6 photometric perturbations = 14 runs)", "",
+          "| Image | Nuclei F1 mean ± sd [min, max] | Attr acc mean ± sd | Puncta F1 mean ± sd [min, max] |", "|---|---|---|---|"]
+    for k, s in agg["per_image"].items():
+        r = s["robustness"]
+        a, b, c = r["cell_det_f1"], r["cell_attr_both"], r["nos_det_f1"]
+        L.append(f"| {k} | {100*a['mean']:.1f} ± {100*a['std']:.1f} [{100*a['min']:.1f}, {100*a['max']:.1f}] | {100*b['mean']:.1f} ± {100*b['std']:.1f} | {100*c['mean']:.1f} ± {100*c['std']:.1f} [{100*c['min']:.1f}, {100*c['max']:.1f}] |")
+    L += ["", "## Why nuclei F1 is below 100 %: unmatched predictions and misses (base run)", "",
+          "| Image | FP total | FP overlapping a GT nucleus | FP with no GT overlap | FP / matched median blue | FP / matched median area | FN total | FN covered by a prediction |", "|---|---:|---:|---:|---|---|---:|---:|"]
+    for k, s in agg["per_image"].items():
+        f = s.get("fp_analysis") or {}
+        if not f or f.get("n_fp") is None:
+            continue
+        L.append(f"| {k} | {f['n_fp']} | {f.get('n_fp_overlapping_gt', 0)} | {f.get('n_fp_no_gt_overlap', 0)} | {f.get('fp_median_blue') or 0:.0f} / {f.get('matched_median_blue') or 0:.0f} | {f.get('fp_median_area') or 0:.0f} / {f.get('matched_median_area') or 0:.0f} | {f.get('n_fn', 0)} | {f.get('n_fn_covered_by_prediction', 0)} |")
+    L += ["", "## Counts per image (ground truth / predicted, base run)", "",
+          "| Image | " + " | ".join(ALL_LABELS) + " |", "|---|" + "---|" * len(ALL_LABELS)]
+    for k, s in agg["per_image"].items():
+        L.append(f"| {k} | " + " | ".join(f"{s['counts'][lab]['gt']} / {s['counts'][lab]['pred']}" for lab in ALL_LABELS) + " |")
+    L += ["", "## Post-processing rule variants (micro F1 across held-out images; accuracies pooled over matched objects)", "",
+          "| Variant | " + " | ".join(ALL_LABELS) + " | attr acc (matched nuclei) | puncta type acc (matched puncta) |", "|---|" + "---|" * (len(ALL_LABELS) + 2)]
+    for n, r in agg["rule_variants"].items():
+        L.append(f"| {n} | " + " | ".join(fmt_pct(r['micro_f1'][lab]['f1']) for lab in ALL_LABELS) + f" | {fmt_pct(r['pooled_cell_attr_both'])} | {fmt_pct(r['pooled_nos_type_acc'])} |")
+    if agg.get("antibody_threshold_sweep"):
+        sw = agg["antibody_threshold_sweep"]
+        L += ["", f"## Antibody threshold sweep on the {sw['n_matched']} matched held-out nuclei ({sw['n_negative']} antibody-negative)", "",
+              "| threshold | Antibody − precision | Antibody − recall | Antibody − F1 | overall accuracy |", "|---:|---:|---:|---:|---:|"]
+        for r in sw["sweep"]:
+            L.append(f"| {r['thr']:.2f} | {fmt_pct(r['neg_precision'])} | {fmt_pct(r['neg_recall'])} | {fmt_pct(r['neg_f1'])} | {fmt_pct(r['accuracy'])} |")
+    L.append("")
+    with open(path, "w") as f:
+        f.write("\n".join(L))
+
+
+def cmd_cv(a):
+    samples, _ = discover(a.data_dir)
+    keys = a.keys.split(",") if a.keys else [s.key for s in samples]
+    os.makedirs(a.runs_dir, exist_ok=True)
+    per_key = {}
+    for s in samples:
+        if s.key not in keys:
+            continue
+        ck = os.path.join(a.runs_dir, f"fold_{s.key}.pt")
+        if not os.path.exists(ck) or a.retrain:
+            cmd = [sys.executable, "-I", os.path.join(os.path.dirname(__file__), "train.py"), "--data-dir", a.data_dir,
+                   "--holdout", s.key, "--iters", str(a.iters), "--out", ck, "--seed", str(a.seed), "--device", a.device]
+            print("TRAIN:", " ".join(cmd), flush=True)
+            with open(os.path.join(a.runs_dir, f"train_{s.key}.log"), "w") as log:
+                subprocess.run(cmd, check=True, stdout=log, stderr=subprocess.STDOUT)
+        from cellquant.model import load_checkpoint
+        _, meta = load_checkpoint(ck)
+        if meta.get("holdout") != s.key or s.key in meta.get("train_keys", []):
+            raise SystemExit(f"{ck}: trained with holdout={meta.get('holdout')!r}, train_keys={meta.get('train_keys')}; "
+                             f"refusing to score {s.key} with it (delete the file or use --retrain)")
+        eval_json = os.path.join(a.runs_dir, f"{s.key}_eval.json")
+        if a.reuse_eval and os.path.exists(eval_json) and os.path.getmtime(eval_json) > os.path.getmtime(ck):
+            with open(eval_json) as f:
+                per_key[s.key] = json.load(f)
+            b = per_key[s.key]["runs"]["base"]["summary"]
+            print(f"[{s.key}] reused {os.path.basename(eval_json)}: nuclei F1 {b['cell_det_f1']:.3f} attr {b['cell_attr_both']:.3f} puncta F1 {b['nos_det_f1']:.3f}", flush=True)
+            continue
+        img = load_image(s.image_path)
+        R = rasterize(s.annotation, img.shape[0], img.shape[1])
+        t = time.time()
+        res = test_image(ck, img, R, s.annotation.counts(), a.device, out_prefix=os.path.join(a.runs_dir, s.key))
+        res["train_keys"] = list(meta.get("train_keys", []))
+        res["checkpoint"] = os.path.basename(ck)
+        per_key[s.key] = res
+        b = res["runs"]["base"]["summary"]
+        print(f"[{s.key}] held-out: nuclei F1 {b['cell_det_f1']:.3f} attr {b['cell_attr_both']:.3f} puncta F1 {b['nos_det_f1']:.3f} type {b['nos_type_acc']:.3f} deterministic={res['deterministic']} ({time.time()-t:.0f}s)", flush=True)
+        with open(os.path.join(a.runs_dir, f"{s.key}_eval.json"), "w") as f:
+            json.dump(res, f, indent=1)
+    agg = aggregate(per_key)
+    totals = {lab: sum(s.annotation.count(lab) for s in samples) for lab in ALL_LABELS}
+    agg["dataset_totals"] = totals
+    with open(os.path.join(a.runs_dir, "cv_results.json"), "w") as f:
+        json.dump({"aggregate": agg, "per_image": per_key}, f, indent=1)
+    n_nuc = sum(totals[c] for c in CELL_LABELS)
+    n_pun = sum(totals[c] for c in NOSTRIL_LABELS)
+    write_report(agg, os.path.join(a.runs_dir, "cv_report.md"), "Leave-one-image-out cross-validation",
+                 f"{len(per_key)} folds over {len(samples)} annotated images ({n_nuc} nucleus and {n_pun} punctum outlines); "
+                 f"each image scored by a model whose checkpoint records that image as held out. Iterations per fold: {a.iters}.")
+    print("wrote", os.path.join(a.runs_dir, "cv_report.md"))
+
+
+def cmd_final(a):
+    samples, unann = discover(a.data_dir)
+    os.makedirs(a.out_dir, exist_ok=True)
+    pred = Predictor(a.weights, device=a.device, tta=1)
+    rows = {}
+    for s in samples:
+        img = load_image(s.image_path)
+        R = rasterize(s.annotation, img.shape[0], img.shape[1])
+        res, _ = pred.predict(img, PostConfig())
+        rows[s.key] = score(R, res, s.annotation.counts())
+        Image.fromarray(render_overlay(img, res)).save(os.path.join(a.out_dir, f"{s.key}_pred.png"))
+        b = rows[s.key]["summary"]
+        print(f"[{s.key}] TRAINING-SET fit: nuclei F1 {b['cell_det_f1']:.3f} attr {b['cell_attr_both']:.3f} puncta F1 {b['nos_det_f1']:.3f}")
+    for p in unann:
+        img = load_image(p)
+        res, _ = pred.predict(img, PostConfig())
+        key = os.path.basename(p).split(" ")[0]
+        Image.fromarray(render_overlay(img, res)).save(os.path.join(a.out_dir, f"{key}_unlabeled_pred.png"))
+        rows[f"{key} (no annotation)"] = {"counts": res.counts}
+        print(f"[{key}] un-annotated image counts: {res.counts}")
+    with open(os.path.join(a.out_dir, "final_fit.json"), "w") as f:
+        json.dump(rows, f, indent=1)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    c = sub.add_parser("cv")
+    c.add_argument("--data-dir", required=True)
+    c.add_argument("--runs-dir", default="runs/cv")
+    c.add_argument("--iters", type=int, default=3000)
+    c.add_argument("--keys", default="")
+    c.add_argument("--seed", type=int, default=0)
+    c.add_argument("--device", default="auto")
+    c.add_argument("--retrain", action="store_true")
+    c.add_argument("--reuse-eval", action="store_true", help="reuse <key>_eval.json files newer than their checkpoint")
+    f = sub.add_parser("final")
+    f.add_argument("--data-dir", required=True)
+    f.add_argument("--weights", required=True)
+    f.add_argument("--out-dir", default="reports/final")
+    f.add_argument("--device", default="auto")
+    a = ap.parse_args(argv)
+    {"cv": cmd_cv, "final": cmd_final}[a.cmd](a)
+
+
+if __name__ == "__main__":
+    main()

reports/SUMMARY.md

@@ -0,0 +1,72 @@
+# CellQuant: validation summary
+
+Data: 9 annotated 1024×1024 images, 1569 nucleus outlines and 1057 punctum outlines.
+Protocol: leave-one-image-out cross-validation (one model per image, 3000 iterations each, held-out image never seen in training), then a final model trained on all images with the same recipe. Each held-out image was tested 23 times: 3 identical runs (determinism), no-TTA / 4× / 8× test-time augmentation, 8 rotations and flips, 6 photometric perturbations, and 6 post-processing rule variants. The only choice made on held-out data is the rule that gives a nucleus the Nostril attribute: of three candidate rules, 'contains an in-nucleus punctum' (the annotation protocol) scored best and is the default; see the rule-variant table in cv_report.md.
+
+## Headline numbers (micro-averaged over all held-out images, no TTA)
+
+| Measure | Precision | Recall | F1 |
+|---|---:|---:|---:|
+| Nucleus detection, IoU ≥ 0.5 | 77.5% | 78.4% | 77.9% |
+| Nucleus detection, IoU ≥ 0.3 | 85.6% | 86.7% | 86.2% |
+| Nucleus detection, centroid inside GT nucleus | 87.0% | 88.0% | 87.5% |
+| Punctum detection (centroid ≤ 6 px) | 77.3% | 82.8% | 79.9% |
+| Nucleus detection, IoU ≥ 0.5, 8× TTA | 78.1% | 78.9% | 78.5% |
+
+Per-class F1 (a true positive needs a matched object **and** the right label):
+
+| Label | GT | Pred | F1 |
+|---|---:|---:|---:|
+| Cell, Antibody + | 1061 | 1179 | 72.5% |
+| Cell, Antibody - | 105 | 39 | 31.9% |
+| Cell, Nostril, Antibody + | 398 | 370 | 71.6% |
+| Cell, Nostril, Antibody - | 5 | 0 | 0.0% |
+| Nostril in Nucleus | 525 | 529 | 78.9% |
+| Nostril External of Nucleus | 532 | 603 | 70.3% |
+
+## Per held-out image
+
+| Image | Nuclei F1 | Antibody acc | Nostril-attr acc | Puncta F1 | Nuclei F1 over 14 perturbed runs (mean ± sd) | Deterministic |
+|---|---:|---:|---:|---:|---|---|
+| C100 | 81.2% | 99.3% | 98.6% | 74.4% | 82.5 ± 1.0 | yes |
+| C102 | 90.6% | 100.0% | 90.8% | 76.3% | 89.9 ± 1.8 | yes |
+| C110 | 78.5% | 100.0% | 91.9% | 84.3% | 77.5 ± 1.1 | yes |
+| C112 | 75.0% | 96.6% | 97.4% | 75.8% | 73.6 ± 1.5 | yes |
+| F100 | 75.1% | 97.8% | 97.1% | 85.2% | 72.2 ± 1.3 | yes |
+| F110 | 72.0% | 96.0% | 94.9% | 78.7% | 71.7 ± 1.9 | yes |
+| F113 | 65.4% | 100.0% | 97.1% | 85.2% | 65.6 ± 2.1 | yes |
+| F114 | 78.8% | 93.3% | 94.4% | 67.5% | 77.8 ± 1.7 | yes |
+| F99 | 84.4% | 77.5% | 99.5% | 71.4% | 85.3 ± 1.2 | yes |
+
+## Final model (trained on all images) – fit on its own training images, NOT a generalisation estimate
+
+| Image | Nuclei F1 | Attribute acc | Puncta F1 |
+|---|---:|---:|---:|
+| C100 | 86.7% | 98.7% | 82.1% |
+| C102 | 93.3% | 94.4% | 84.6% |
+| C110 | 88.6% | 95.7% | 85.0% |
+| C112 | 83.8% | 99.2% | 86.2% |
+| F100 | 87.2% | 96.2% | 90.7% |
+| F110 | 91.7% | 94.8% | 87.2% |
+| F113 | 83.7% | 97.7% | 87.1% |
+| F114 | 88.3% | 93.4% | 83.1% |
+| F99 | 89.7% | 91.2% | 75.7% |
+
+## Antibody − threshold (held-out matched nuclei: 1230, of which 87 negative)
+
+Default threshold 0.5. Best Antibody − F1 in the sweep: 52.3% at threshold 0.85 (precision 62.9%, recall 44.8%); the full curve is in cv_report.md. The default was kept because the class is dominated by a single image (F99 holds 62 of the 102 negatives).
+
+## What limits the scores
+
+* **Touching nuclei are sometimes merged** into one outline (worst on F113); this is the main source of IoU-0.5 misses. The marker/threshold sweep (`runs/cv/postprocess_sweep.json`) is flat, so it is a network-border issue, not a post-processing one.
+* **Annotation completeness**: most unmatched predictions overlap an annotated nucleus (outline disagreement) and the rest are dimmer, smaller objects the annotator skipped; many faint red dots were likewise not annotated, which caps external-punctum precision.
+* **Antibody − is rare** (102 of 1569 nuclei, 62 in one image), and **Cell, Nostril, Antibody −** has five examples; their scores are not reliable.
+* Scores are from nine images of one experiment (35-day spinal cord, Iba1/TMEM119). New staining batches or magnifications need a check against a few annotated images.
+
+## Reproduce
+
+```bash
+python evaluate.py cv --data-dir <folder with TIFs and CVAT zips> --runs-dir runs/cv --iters 3000
+python evaluate.py final --data-dir <folder> --weights weights/cellquant.pt
+python scripts/build_summary.py
+```

reports/cv/cv_report.md

@@ -0,0 +1,105 @@
+# Leave-one-image-out cross-validation
+
+9 folds over 9 annotated images (1569 nucleus and 1057 punctum outlines); each image scored by a model whose checkpoint records that image as held out. Iterations per fold: 3000.
+
+## Micro-averaged per-class scores (base run, no TTA)
+
+| Label | GT | Pred | TP | FP | FN | Precision | Recall | F1 |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|
+| Cell, Antibody + | 1061 | 1179 | 812 | 367 | 249 |  68.9% |  76.5% |  72.5% |
+| Cell, Antibody - | 105 | 39 | 23 | 16 | 82 |  59.0% |  21.9% |  31.9% |
+| Cell, Nostril, Antibody + | 398 | 370 | 275 | 95 | 123 |  74.3% |  69.1% |  71.6% |
+| Cell, Nostril, Antibody - | 5 | 0 | 0 | 0 | 5 |   0.0% |   0.0% |   0.0% |
+| Nostril in Nucleus | 525 | 529 | 416 | 113 | 109 |  78.6% |  79.2% |  78.9% |
+| Nostril External of Nucleus | 532 | 603 | 399 | 204 | 133 |  66.2% |  75.0% |  70.3% |
+
+Class-agnostic detection (IoU >= 0.5 for nuclei; centroid distance for puncta):
+
+- base: nuclei P  77.5% R  78.4% F1  77.9% (IoU≥0.5); F1  86.2% (IoU≥0.3); F1  87.5% (centroid-in-nucleus) | puncta P  77.3% R  82.8% F1  79.9%
+- tta4: nuclei P  78.0% R  78.3% F1  78.2% (IoU≥0.5); F1  86.7% (IoU≥0.3); F1  88.3% (centroid-in-nucleus) | puncta P  77.8% R  84.2% F1  80.9%
+- tta8: nuclei P  78.1% R  78.9% F1  78.5% (IoU≥0.5); F1  86.8% (IoU≥0.3); F1  88.3% (centroid-in-nucleus) | puncta P  78.5% R  84.5% F1  81.4%
+
+## Per-image results (each image held out of training)
+
+| Image | Nuclei F1 (IoU≥0.5) | F1 (IoU≥0.3) | F1 (centroid) | mean IoU | Antibody acc | Nostril-attr acc | Puncta F1 | Puncta type acc | Deterministic |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---|
+| C100 |  81.2% |  88.4% |  89.5% | 0.783 |  99.3% |  98.6% |  74.4% | 100.0% | yes |
+| C102 |  90.6% |  91.7% |  92.7% | 0.810 | 100.0% |  90.8% |  76.3% |  95.0% | yes |
+| C110 |  78.5% |  85.4% |  88.1% | 0.752 | 100.0% |  91.9% |  84.3% |  92.4% | yes |
+| C112 |  75.0% |  85.9% |  87.2% | 0.727 |  96.6% |  97.4% |  75.8% |  88.0% | yes |
+| F100 |  75.1% |  84.9% |  84.9% | 0.761 |  97.8% |  97.1% |  85.2% |  97.0% | yes |
+| F110 |  72.0% |  80.0% |  85.1% | 0.788 |  96.0% |  94.9% |  78.7% |  90.8% | yes |
+| F113 |  65.4% |  80.1% |  83.3% | 0.732 | 100.0% |  97.1% |  85.2% |  80.8% | yes |
+| F114 |  78.8% |  85.3% |  84.5% | 0.794 |  93.3% |  94.4% |  67.5% |  95.0% | yes |
+| F99 |  84.4% |  91.9% |  92.3% | 0.802 |  77.5% |  99.5% |  71.4% |  93.3% | yes |
+
+## Repeated tests per image (8 rotations/flips + 6 photometric perturbations = 14 runs)
+
+| Image | Nuclei F1 mean ± sd [min, max] | Attr acc mean ± sd | Puncta F1 mean ± sd [min, max] |
+|---|---|---|---|
+| C100 | 82.5 ± 1.0 [81.2, 84.9] | 98.2 ± 0.8 | 74.7 ± 4.3 [68.1, 81.1] |
+| C102 | 89.9 ± 1.8 [87.0, 93.7] | 91.9 ± 2.3 | 77.4 ± 1.9 [74.4, 80.9] |
+| C110 | 77.5 ± 1.1 [75.3, 79.3] | 91.1 ± 1.7 | 84.1 ± 0.6 [83.0, 85.5] |
+| C112 | 73.6 ± 1.5 [70.5, 75.2] | 94.3 ± 0.8 | 77.2 ± 1.5 [75.8, 80.6] |
+| F100 | 72.2 ± 1.3 [69.1, 75.1] | 94.3 ± 2.0 | 85.7 ± 1.6 [82.1, 88.2] |
+| F110 | 71.7 ± 1.9 [69.1, 75.7] | 87.9 ± 1.6 | 78.8 ± 3.1 [73.2, 82.8] |
+| F113 | 65.6 ± 2.1 [62.1, 69.9] | 96.2 ± 0.8 | 81.9 ± 3.1 [77.2, 87.1] |
+| F114 | 77.8 ± 1.7 [74.7, 80.9] | 88.4 ± 1.0 | 68.9 ± 2.5 [64.8, 73.5] |
+| F99 | 85.3 ± 1.2 [82.9, 87.5] | 76.9 ± 1.5 | 75.3 ± 7.2 [57.1, 85.7] |
+
+## Why nuclei F1 is below 100 %: unmatched predictions and misses (base run)
+
+| Image | FP total | FP overlapping a GT nucleus | FP with no GT overlap | FP / matched median blue | FP / matched median area | FN total | FN covered by a prediction |
+|---|---:|---:|---:|---|---|---:|---:|
+| C100 | 37 | 27 | 10 | 48 / 76 | 264 / 642 | 31 | 28 |
+| C102 | 14 | 3 | 11 | 21 / 52 | 332 / 807 | 4 | 1 |
+| C110 | 45 | 30 | 15 | 21 / 43 | 282 / 634 | 36 | 25 |
+| C112 | 49 | 40 | 9 | 24 / 28 | 354 / 664 | 29 | 24 |
+| F100 | 42 | 24 | 18 | 17 / 33 | 601 / 744 | 49 | 46 |
+| F110 | 48 | 41 | 7 | 46 / 61 | 166 / 676 | 29 | 17 |
+| F113 | 47 | 31 | 16 | 10 / 24 | 713 / 702 | 61 | 55 |
+| F114 | 35 | 24 | 11 | 73 / 89 | 702 / 652 | 62 | 53 |
+| F99 | 41 | 34 | 7 | 36 / 56 | 435 / 595 | 38 | 35 |
+
+## Counts per image (ground truth / predicted, base run)
+
+| Image | Cell, Antibody + | Cell, Antibody - | Cell, Nostril, Antibody + | Cell, Nostril, Antibody - | Nostril in Nucleus | Nostril External of Nucleus |
+|---|---|---|---|---|---|---|
+| C100 | 165 / 167 | 0 / 4 | 13 / 13 | 0 / 0 | 14 / 15 | 6 / 8 |
+| C102 | 41 / 52 | 0 / 0 | 50 / 49 | 0 / 0 | 60 / 73 | 74 / 105 |
+| C110 | 61 / 84 | 1 / 1 | 122 / 108 | 0 / 0 | 169 / 165 | 207 / 244 |
+| C112 | 124 / 141 | 5 / 1 | 17 / 24 | 0 / 0 | 23 / 27 | 2 / 14 |
+| F100 | 87 / 97 | 6 / 6 | 93 / 76 | 0 / 0 | 118 / 122 | 44 / 26 |
+| F110 | 87 / 119 | 7 / 2 | 33 / 26 | 1 / 0 | 57 / 38 | 137 / 101 |
+| F113 | 138 / 127 | 3 / 1 | 22 / 21 | 0 / 0 | 26 / 23 | 8 / 4 |
+| F114 | 175 / 155 | 21 / 11 | 42 / 49 | 4 / 0 | 52 / 62 | 38 / 85 |
+| F99 | 183 / 237 | 62 / 13 | 6 / 4 | 0 / 0 | 6 / 4 | 16 / 16 |
+
+## Post-processing rule variants (micro F1 across held-out images; accuracies pooled over matched objects)
+
+| Variant | Cell, Antibody + | Cell, Antibody - | Cell, Nostril, Antibody + | Cell, Nostril, Antibody - | Nostril in Nucleus | Nostril External of Nucleus | attr acc (matched nuclei) | puncta type acc (matched puncta) |
+|---|---|---|---|---|---|---|---|---|
+| rule_nos=head_cell=head |  72.0% |  31.9% |  68.5% |   0.0% |  78.9% |  70.3% |  88.8% |  93.1% |
+| rule_nos=head_cell=contains |  72.5% |  31.9% |  71.6% |   0.0% |  78.9% |  70.3% |  90.2% |  93.1% |
+| rule_nos=head_cell=either |  72.4% |  31.9% |  69.3% |   0.0% |  78.9% |  70.3% |  89.4% |  93.1% |
+| rule_nos=geometric_cell=head |  72.0% |  31.9% |  68.5% |   0.0% |  78.8% |  70.3% |  88.8% |  93.0% |
+| rule_nos=geometric_cell=contains |  72.5% |  31.9% |  71.6% |   0.0% |  78.8% |  70.3% |  90.2% |  93.0% |
+| rule_nos=geometric_cell=either |  72.4% |  31.9% |  69.3% |   0.0% |  78.8% |  70.3% |  89.4% |  93.0% |
+
+## Antibody threshold sweep on the 1230 matched held-out nuclei (87 antibody-negative)
+
+| threshold | Antibody − precision | Antibody − recall | Antibody − F1 | overall accuracy |
+|---:|---:|---:|---:|---:|
+| 0.30 |  85.0% |  19.5% |  31.8% |  94.1% |
+| 0.35 |  78.3% |  20.7% |  32.7% |  94.0% |
+| 0.40 |  76.9% |  23.0% |  35.4% |  94.1% |
+| 0.45 |  74.2% |  26.4% |  39.0% |  94.1% |
+| 0.50 |  74.2% |  26.4% |  39.0% |  94.1% |
+| 0.55 |  75.0% |  31.0% |  43.9% |  94.4% |
+| 0.60 |  73.7% |  32.2% |  44.8% |  94.4% |
+| 0.65 |  72.1% |  35.6% |  47.7% |  94.5% |
+| 0.70 |  68.1% |  36.8% |  47.8% |  94.3% |
+| 0.75 |  65.4% |  39.1% |  48.9% |  94.2% |
+| 0.80 |  63.6% |  40.2% |  49.3% |  94.1% |
+| 0.85 |  62.9% |  44.8% |  52.3% |  94.2% |
+| 0.90 |  59.7% |  46.0% |  51.9% |  94.0% |

reports/cv/postprocess_sweep.json

@@ -0,0 +1,322 @@
+[
+ {
+  "marker_thr": 0.7,
+  "cell_fg_thr": 0.4,
+  "min_marker_area": 30,
+  "nuc_f1_iou50": 0.7971642378889325,
+  "nuc_f1_centroid": 0.8853879480110279,
+  "f1_ab_pos": 0.7316276537833424,
+  "f1_ab_neg": 0.2903225806451613,
+  "f1_nos_pos": 0.7247386759581882,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.83,
+   "C102": 0.912,
+   "C110": 0.796,
+   "C112": 0.768,
+   "F113": 0.654,
+   "F114": 0.797,
+   "F99": 0.838
+  }
+ },
+ {
+  "marker_thr": 0.8,
+  "cell_fg_thr": 0.4,
+  "min_marker_area": 30,
+  "nuc_f1_iou50": 0.7962456003128667,
+  "nuc_f1_centroid": 0.8838482596793116,
+  "f1_ab_pos": 0.7347379794705564,
+  "f1_ab_neg": 0.2903225806451613,
+  "f1_nos_pos": 0.7058823529411765,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.845,
+   "C102": 0.892,
+   "C110": 0.777,
+   "C112": 0.748,
+   "F113": 0.665,
+   "F114": 0.797,
+   "F99": 0.849
+  }
+ },
+ {
+  "marker_thr": 0.8,
+  "cell_fg_thr": 0.5,
+  "min_marker_area": 30,
+  "nuc_f1_iou50": 0.7952941176470589,
+  "nuc_f1_centroid": 0.8847058823529411,
+  "f1_ab_pos": 0.7316017316017317,
+  "f1_ab_neg": 0.29268292682926833,
+  "f1_nos_pos": 0.7060869565217391,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.833,
+   "C102": 0.887,
+   "C110": 0.779,
+   "C112": 0.726,
+   "F113": 0.673,
+   "F114": 0.799,
+   "F99": 0.86
+  }
+ },
+ {
+  "marker_thr": 0.7,
+  "cell_fg_thr": 0.5,
+  "min_marker_area": 30,
+  "nuc_f1_iou50": 0.7946287519747236,
+  "nuc_f1_centroid": 0.8862559241706163,
+  "f1_ab_pos": 0.7262813522355507,
+  "f1_ab_neg": 0.29268292682926833,
+  "f1_nos_pos": 0.7250437828371278,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.818,
+   "C102": 0.906,
+   "C110": 0.798,
+   "C112": 0.739,
+   "F113": 0.662,
+   "F114": 0.799,
+   "F99": 0.845
+  }
+ },
+ {
+  "marker_thr": 0.8,
+  "cell_fg_thr": 0.4,
+  "min_marker_area": 12,
+  "nuc_f1_iou50": 0.7940717628705148,
+  "nuc_f1_centroid": 0.8814352574102964,
+  "f1_ab_pos": 0.7323640280021542,
+  "f1_ab_neg": 0.2903225806451613,
+  "f1_nos_pos": 0.7046632124352332,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.845,
+   "C102": 0.892,
+   "C110": 0.773,
+   "C112": 0.744,
+   "F113": 0.658,
+   "F114": 0.797,
+   "F99": 0.849
+  }
+ },
+ {
+  "marker_thr": 0.7,
+  "cell_fg_thr": 0.4,
+  "min_marker_area": 12,
+  "nuc_f1_iou50": 0.7934143473147784,
+  "nuc_f1_centroid": 0.8812230497843984,
+  "f1_ab_pos": 0.7284552845528455,
+  "f1_ab_neg": 0.2903225806451613,
+  "f1_nos_pos": 0.7197231833910035,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.821,
+   "C102": 0.912,
+   "C110": 0.792,
+   "C112": 0.761,
+   "F113": 0.654,
+   "F114": 0.796,
+   "F99": 0.834
+  }
+ },
+ {
+  "marker_thr": 0.8,
+  "cell_fg_thr": 0.5,
+  "min_marker_area": 12,
+  "nuc_f1_iou50": 0.7931169339069223,
+  "nuc_f1_centroid": 0.8822839264763395,
+  "f1_ab_pos": 0.7292340884573895,
+  "f1_ab_neg": 0.29268292682926833,
+  "f1_nos_pos": 0.704861111111111,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.833,
+   "C102": 0.887,
+   "C110": 0.775,
+   "C112": 0.721,
+   "F113": 0.667,
+   "F114": 0.799,
+   "F99": 0.86
+  }
+ },
+ {
+  "marker_thr": 0.6,
+  "cell_fg_thr": 0.4,
+  "min_marker_area": 30,
+  "nuc_f1_iou50": 0.7930352196280174,
+  "nuc_f1_centroid": 0.8816778789077958,
+  "f1_ab_pos": 0.7275711159737418,
+  "f1_ab_neg": 0.2903225806451613,
+  "f1_nos_pos": 0.7180385288966724,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.825,
+   "C102": 0.912,
+   "C110": 0.785,
+   "C112": 0.768,
+   "F113": 0.65,
+   "F114": 0.787,
+   "F99": 0.839
+  }
+ },
+ {
+  "marker_thr": 0.5,
+  "cell_fg_thr": 0.4,
+  "min_marker_area": 30,
+  "nuc_f1_iou50": 0.792063492063492,
+  "nuc_f1_centroid": 0.880952380952381,
+  "f1_ab_pos": 0.728171334431631,
+  "f1_ab_neg": 0.2903225806451613,
+  "f1_nos_pos": 0.7145359019264448,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.823,
+   "C102": 0.912,
+   "C110": 0.785,
+   "C112": 0.782,
+   "F113": 0.647,
+   "F114": 0.78,
+   "F99": 0.836
+  }
+ },
+ {
+  "marker_thr": 0.6,
+  "cell_fg_thr": 0.5,
+  "min_marker_area": 30,
+  "nuc_f1_iou50": 0.792063492063492,
+  "nuc_f1_centroid": 0.8825396825396825,
+  "f1_ab_pos": 0.7243835616438358,
+  "f1_ab_neg": 0.29268292682926833,
+  "f1_nos_pos": 0.7183098591549296,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.819,
+   "C102": 0.906,
+   "C110": 0.787,
+   "C112": 0.739,
+   "F113": 0.658,
+   "F114": 0.793,
+   "F99": 0.847
+  }
+ },
+ {
+  "marker_thr": 0.5,
+  "cell_fg_thr": 0.5,
+  "min_marker_area": 30,
+  "nuc_f1_iou50": 0.7914012738853503,
+  "nuc_f1_centroid": 0.8821656050955414,
+  "f1_ab_pos": 0.7253714914694551,
+  "f1_ab_neg": 0.29268292682926833,
+  "f1_nos_pos": 0.7147887323943662,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.817,
+   "C102": 0.906,
+   "C110": 0.787,
+   "C112": 0.752,
+   "F113": 0.656,
+   "F114": 0.788,
+   "F99": 0.844
+  }
+ },
+ {
+  "marker_thr": 0.7,
+  "cell_fg_thr": 0.5,
+  "min_marker_area": 12,
+  "nuc_f1_iou50": 0.7908805031446541,
+  "nuc_f1_centroid": 0.8820754716981133,
+  "f1_ab_pos": 0.7231270358306189,
+  "f1_ab_neg": 0.29268292682926833,
+  "f1_nos_pos": 0.7200000000000002,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.809,
+   "C102": 0.906,
+   "C110": 0.794,
+   "C112": 0.732,
+   "F113": 0.662,
+   "F114": 0.797,
+   "F99": 0.842
+  }
+ },
+ {
+  "marker_thr": 0.6,
+  "cell_fg_thr": 0.4,
+  "min_marker_area": 12,
+  "nuc_f1_iou50": 0.7899093417422152,
+  "nuc_f1_centroid": 0.8789909341742216,
+  "f1_ab_pos": 0.724006532389766,
+  "f1_ab_neg": 0.2903225806451613,
+  "f1_nos_pos": 0.7132867132867132,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.816,
+   "C102": 0.912,
+   "C110": 0.783,
+   "C112": 0.761,
+   "F113": 0.645,
+   "F114": 0.787,
+   "F99": 0.839
+  }
+ },
+ {
+  "marker_thr": 0.5,
+  "cell_fg_thr": 0.4,
+  "min_marker_area": 12,
+  "nuc_f1_iou50": 0.7898694103680254,
+  "nuc_f1_centroid": 0.8793035219628017,
+  "f1_ab_pos": 0.726079825041006,
+  "f1_ab_neg": 0.2903225806451613,
+  "f1_nos_pos": 0.712280701754386,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.819,
+   "C102": 0.912,
+   "C110": 0.783,
+   "C112": 0.78,
+   "F113": 0.643,
+   "F114": 0.78,
+   "F99": 0.834
+  }
+ },
+ {
+  "marker_thr": 0.5,
+  "cell_fg_thr": 0.5,
+  "min_marker_area": 12,
+  "nuc_f1_iou50": 0.7898291617004372,
+  "nuc_f1_centroid": 0.881207787048073,
+  "f1_ab_pos": 0.7240811848601207,
+  "f1_ab_neg": 0.29268292682926833,
+  "f1_nos_pos": 0.7125220458553791,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.812,
+   "C102": 0.906,
+   "C110": 0.785,
+   "C112": 0.75,
+   "F113": 0.654,
+   "F114": 0.788,
+   "F99": 0.844
+  }
+ },
+ {
+  "marker_thr": 0.6,
+  "cell_fg_thr": 0.5,
+  "min_marker_area": 12,
+  "nuc_f1_iou50": 0.7892447607750098,
+  "nuc_f1_centroid": 0.8809806247528668,
+  "f1_ab_pos": 0.7212220403709765,
+  "f1_ab_neg": 0.29268292682926833,
+  "f1_nos_pos": 0.7135325131810192,
+  "f1_pin": 0.7816411682892906,
+  "per_image": {
+   "C100": 0.81,
+   "C102": 0.906,
+   "C110": 0.785,
+   "C112": 0.732,
+   "F113": 0.656,
+   "F114": 0.793,
+   "F99": 0.847
+  }
+ }
+]

reports/final/final_fit.json

@@ -0,0 +1,1820 @@
+{
+ "C100": {
+  "cells": {
+   "detection": {
+    "tp": 153,
+    "fp": 22,
+    "fn": 25,
+    "precision": 0.8742857142857143,
+    "recall": 0.8595505617977528,
+    "f1": 0.8668555240793201,
+    "mean_iou_matched": 0.7974392864551416,
+    "iou30": {
+     "tp": 165,
+     "fp": 10,
+     "fn": 13,
+     "precision": 0.9428571428571428,
+     "recall": 0.9269662921348315,
+     "f1": 0.934844192634561
+    },
+    "centroid": {
+     "tp": 165,
+     "fp": 10,
+     "fn": 13,
+     "precision": 0.9428571428571428,
+     "recall": 0.9269662921348315,
+     "f1": 0.934844192634561
+    }
+   },
+   "attribute_accuracy": {
+    "antibody": 0.9934640522875817,
+    "nostril": 0.9934640522875817,
+    "both": 0.9869281045751634,
+    "n_matched": 153
+   },
+   "per_class": {
+    "Cell, Antibody +": {
+     "tp": 139,
+     "fp": 22,
+     "fn": 26,
+     "precision": 0.8633540372670807,
+     "recall": 0.8424242424242424,
+     "f1": 0.852760736196319,
+     "gt_count": 165,
+     "pred_count": 161
+    },
+    "Cell, Antibody -": {
+     "tp": 0,
+     "fp": 2,
+     "fn": 0,
+     "precision": 0.0,
+     "recall": 0.0,
+     "f1": 0.0,
+     "gt_count": 0,
+     "pred_count": 2
+    },
+    "Cell, Nostril, Antibody +": {
+     "tp": 12,
+     "fp": 0,
+     "fn": 1,
+     "precision": 1.0,
+     "recall": 0.9230769230769231,
+     "f1": 0.9600000000000001,
+     "gt_count": 13,
+     "pred_count": 12
+    },
+    "Cell, Nostril, Antibody -": {
+     "tp": 0,
+     "fp": 0,
+     "fn": 0,
+     "precision": 0.0,
+     "recall": 0.0,
+     "f1": 0.0,
+     "gt_count": 0,
+     "pred_count": 0
+    }
+   },
+   "confusion": {
+    "Cell, Antibody +": {
+     "Cell, Antibody +": 139,
+     "Cell, Antibody -": 1,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Antibody -": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody +": {
+     "Cell, Antibody +": 1,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 12,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody -": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    }
+   },
+   "n_gt": 178,
+   "n_pred": 175
+  },
+  "nostrils": {
+   "detection": {
+    "tp": 16,
+    "fp": 3,
+    "fn": 4,
+    "precision": 0.8421052631578947,
+    "recall": 0.8,
+    "f1": 0.8205128205128205,
+    "mean_dist_matched": 1.157546253191996
+   },
+   "type_accuracy": 1.0,
+   "per_class": {
+    "Nostril in Nucleus": {
+     "tp": 12,
+     "fp": 0,
+     "fn": 2,
+     "precision": 1.0,
+     "recall": 0.8571428571428571,
+     "f1": 0.923076923076923,
+     "gt_count": 14,
+     "pred_count": 12
+    },
+    "Nostril External of Nucleus": {
+     "tp": 4,
+     "fp": 3,
+     "fn": 2,
+     "precision": 0.5714285714285714,
+     "recall": 0.6666666666666666,
+     "f1": 0.6153846153846153,
+     "gt_count": 6,
+     "pred_count": 7
+    }
+   },
+   "n_gt": 20,
+   "n_pred": 19
+  },
+  "counts": {
+   "Cell, Antibody +": {
+    "gt": 165,
+    "pred": 161,
+    "abs_err": 4,
+    "rel_err": 0.024242424242424242
+   },
+   "Cell, Antibody -": {
+    "gt": 0,
+    "pred": 2,
+    "abs_err": 2,
+    "rel_err": Infinity
+   },
+   "Cell, Nostril, Antibody +": {
+    "gt": 13,
+    "pred": 12,
+    "abs_err": 1,
+    "rel_err": 0.07692307692307693
+   },
+   "Cell, Nostril, Antibody -": {
+    "gt": 0,
+    "pred": 0,
+    "abs_err": 0,
+    "rel_err": 0.0
+   },
+   "Nostril in Nucleus": {
+    "gt": 14,
+    "pred": 12,
+    "abs_err": 2,
+    "rel_err": 0.14285714285714285
+   },
+   "Nostril External of Nucleus": {
+    "gt": 6,
+    "pred": 7,
+    "abs_err": 1,
+    "rel_err": 0.16666666666666666
+   }
+  },
+  "fp_analysis": null,
+  "pairs": null,
+  "summary": {
+   "cell_det_f1": 0.8668555240793201,
+   "cell_det_precision": 0.8742857142857143,
+   "cell_det_recall": 0.8595505617977528,
+   "cell_mean_iou": 0.7974392864551416,
+   "cell_det_f1_iou30": 0.934844192634561,
+   "cell_det_f1_centroid": 0.934844192634561,
+   "cell_attr_antibody": 0.9934640522875817,
+   "cell_attr_nostril": 0.9934640522875817,
+   "cell_attr_both": 0.9869281045751634,
+   "nos_det_f1": 0.8205128205128205,
+   "nos_det_precision": 0.8421052631578947,
+   "nos_det_recall": 0.8,
+   "nos_type_acc": 1.0,
+   "f1[Cell, Antibody +]": 0.852760736196319,
+   "f1[Cell, Antibody -]": 0.0,
+   "f1[Cell, Nostril, Antibody +]": 0.9600000000000001,
+   "f1[Cell, Nostril, Antibody -]": 0.0,
+   "f1[Nostril in Nucleus]": 0.923076923076923,
+   "f1[Nostril External of Nucleus]": 0.6153846153846153
+  }
+ },
+ "C102": {
+  "cells": {
+   "detection": {
+    "tp": 90,
+    "fp": 12,
+    "fn": 1,
+    "precision": 0.8823529411764706,
+    "recall": 0.989010989010989,
+    "f1": 0.9326424870466321,
+    "mean_iou_matched": 0.8122454665114849,
+    "iou30": {
+     "tp": 90,
+     "fp": 12,
+     "fn": 1,
+     "precision": 0.8823529411764706,
+     "recall": 0.989010989010989,
+     "f1": 0.9326424870466321
+    },
+    "centroid": {
+     "tp": 90,
+     "fp": 12,
+     "fn": 1,
+     "precision": 0.8823529411764706,
+     "recall": 0.989010989010989,
+     "f1": 0.9326424870466321
+    }
+   },
+   "attribute_accuracy": {
+    "antibody": 1.0,
+    "nostril": 0.9444444444444444,
+    "both": 0.9444444444444444,
+    "n_matched": 90
+   },
+   "per_class": {
+    "Cell, Antibody +": {
+     "tp": 41,
+     "fp": 15,
+     "fn": 0,
+     "precision": 0.7321428571428571,
+     "recall": 1.0,
+     "f1": 0.8453608247422679,
+     "gt_count": 41,
+     "pred_count": 56
+    },
+    "Cell, Antibody -": {
+     "tp": 0,
+     "fp": 0,
+     "fn": 0,
+     "precision": 0.0,
+     "recall": 0.0,
+     "f1": 0.0,
+     "gt_count": 0,
+     "pred_count": 0
+    },
+    "Cell, Nostril, Antibody +": {
+     "tp": 44,
+     "fp": 2,
+     "fn": 6,
+     "precision": 0.9565217391304348,
+     "recall": 0.88,
+     "f1": 0.9166666666666666,
+     "gt_count": 50,
+     "pred_count": 46
+    },
+    "Cell, Nostril, Antibody -": {
+     "tp": 0,
+     "fp": 0,
+     "fn": 0,
+     "precision": 0.0,
+     "recall": 0.0,
+     "f1": 0.0,
+     "gt_count": 0,
+     "pred_count": 0
+    }
+   },
+   "confusion": {
+    "Cell, Antibody +": {
+     "Cell, Antibody +": 41,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Antibody -": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody +": {
+     "Cell, Antibody +": 5,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 44,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody -": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    }
+   },
+   "n_gt": 91,
+   "n_pred": 102
+  },
+  "nostrils": {
+   "detection": {
+    "tp": 121,
+    "fp": 31,
+    "fn": 13,
+    "precision": 0.7960526315789473,
+    "recall": 0.9029850746268657,
+    "f1": 0.8461538461538461,
+    "mean_dist_matched": 1.0261222516695998
+   },
+   "type_accuracy": 1.0,
+   "per_class": {
+    "Nostril in Nucleus": {
+     "tp": 54,
+     "fp": 8,
+     "fn": 6,
+     "precision": 0.8709677419354839,
+     "recall": 0.9,
+     "f1": 0.8852459016393444,
+     "gt_count": 60,
+     "pred_count": 62
+    },
+    "Nostril External of Nucleus": {
+     "tp": 67,
+     "fp": 23,
+     "fn": 7,
+     "precision": 0.7444444444444445,
+     "recall": 0.9054054054054054,
+     "f1": 0.8170731707317074,
+     "gt_count": 74,
+     "pred_count": 90
+    }
+   },
+   "n_gt": 134,
+   "n_pred": 152
+  },
+  "counts": {
+   "Cell, Antibody +": {
+    "gt": 41,
+    "pred": 56,
+    "abs_err": 15,
+    "rel_err": 0.36585365853658536
+   },
+   "Cell, Antibody -": {
+    "gt": 0,
+    "pred": 0,
+    "abs_err": 0,
+    "rel_err": 0.0
+   },
+   "Cell, Nostril, Antibody +": {
+    "gt": 50,
+    "pred": 46,
+    "abs_err": 4,
+    "rel_err": 0.08
+   },
+   "Cell, Nostril, Antibody -": {
+    "gt": 0,
+    "pred": 0,
+    "abs_err": 0,
+    "rel_err": 0.0
+   },
+   "Nostril in Nucleus": {
+    "gt": 60,
+    "pred": 62,
+    "abs_err": 2,
+    "rel_err": 0.03333333333333333
+   },
+   "Nostril External of Nucleus": {
+    "gt": 74,
+    "pred": 90,
+    "abs_err": 16,
+    "rel_err": 0.21621621621621623
+   }
+  },
+  "fp_analysis": null,
+  "pairs": null,
+  "summary": {
+   "cell_det_f1": 0.9326424870466321,
+   "cell_det_precision": 0.8823529411764706,
+   "cell_det_recall": 0.989010989010989,
+   "cell_mean_iou": 0.8122454665114849,
+   "cell_det_f1_iou30": 0.9326424870466321,
+   "cell_det_f1_centroid": 0.9326424870466321,
+   "cell_attr_antibody": 1.0,
+   "cell_attr_nostril": 0.9444444444444444,
+   "cell_attr_both": 0.9444444444444444,
+   "nos_det_f1": 0.8461538461538461,
+   "nos_det_precision": 0.7960526315789473,
+   "nos_det_recall": 0.9029850746268657,
+   "nos_type_acc": 1.0,
+   "f1[Cell, Antibody +]": 0.8453608247422679,
+   "f1[Cell, Antibody -]": 0.0,
+   "f1[Cell, Nostril, Antibody +]": 0.9166666666666666,
+   "f1[Cell, Nostril, Antibody -]": 0.0,
+   "f1[Nostril in Nucleus]": 0.8852459016393444,
+   "f1[Nostril External of Nucleus]": 0.8170731707317074
+  }
+ },
+ "C110": {
+  "cells": {
+   "detection": {
+    "tp": 164,
+    "fp": 22,
+    "fn": 20,
+    "precision": 0.8817204301075269,
+    "recall": 0.8913043478260869,
+    "f1": 0.8864864864864864,
+    "mean_iou_matched": 0.800839882168248,
+    "iou30": {
+     "tp": 173,
+     "fp": 13,
+     "fn": 11,
+     "precision": 0.9301075268817204,
+     "recall": 0.9402173913043478,
+     "f1": 0.9351351351351351
+    },
+    "centroid": {
+     "tp": 172,
+     "fp": 14,
+     "fn": 12,
+     "precision": 0.9247311827956989,
+     "recall": 0.9347826086956522,
+     "f1": 0.9297297297297297
+    }
+   },
+   "attribute_accuracy": {
+    "antibody": 1.0,
+    "nostril": 0.9573170731707317,
+    "both": 0.9573170731707317,
+    "n_matched": 164
+   },
+   "per_class": {
+    "Cell, Antibody +": {
+     "tp": 54,
+     "fp": 19,
+     "fn": 7,
+     "precision": 0.7397260273972602,
+     "recall": 0.8852459016393442,
+     "f1": 0.8059701492537313,
+     "gt_count": 61,
+     "pred_count": 73
+    },
+    "Cell, Antibody -": {
+     "tp": 1,
+     "fp": 0,
+     "fn": 0,
+     "precision": 1.0,
+     "recall": 1.0,
+     "f1": 1.0,
+     "gt_count": 1,
+     "pred_count": 1
+    },
+    "Cell, Nostril, Antibody +": {
+     "tp": 102,
+     "fp": 10,
+     "fn": 20,
+     "precision": 0.9107142857142857,
+     "recall": 0.8360655737704918,
+     "f1": 0.8717948717948717,
+     "gt_count": 122,
+     "pred_count": 112
+    },
+    "Cell, Nostril, Antibody -": {
+     "tp": 0,
+     "fp": 0,
+     "fn": 0,
+     "precision": 0.0,
+     "recall": 0.0,
+     "f1": 0.0,
+     "gt_count": 0,
+     "pred_count": 0
+    }
+   },
+   "confusion": {
+    "Cell, Antibody +": {
+     "Cell, Antibody +": 54,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 3,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Antibody -": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 1,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody +": {
+     "Cell, Antibody +": 4,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 102,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody -": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    }
+   },
+   "n_gt": 184,
+   "n_pred": 186
+  },
+  "nostrils": {
+   "detection": {
+    "tp": 347,
+    "fp": 93,
+    "fn": 29,
+    "precision": 0.7886363636363637,
+    "recall": 0.9228723404255319,
+    "f1": 0.8504901960784313,
+    "mean_dist_matched": 0.8862671910950328
+   },
+   "type_accuracy": 0.9798270893371758,
+   "per_class": {
+    "Nostril in Nucleus": {
+     "tp": 148,
+     "fp": 34,
+     "fn": 21,
+     "precision": 0.8131868131868132,
+     "recall": 0.8757396449704142,
+     "f1": 0.8433048433048432,
+     "gt_count": 169,
+     "pred_count": 182
+    },
+    "Nostril External of Nucleus": {
+     "tp": 192,
+     "fp": 66,
+     "fn": 15,
+     "precision": 0.7441860465116279,
+     "recall": 0.927536231884058,
+     "f1": 0.8258064516129032,
+     "gt_count": 207,
+     "pred_count": 258
+    }
+   },
+   "n_gt": 376,
+   "n_pred": 440
+  },
+  "counts": {
+   "Cell, Antibody +": {
+    "gt": 61,
+    "pred": 73,
+    "abs_err": 12,
+    "rel_err": 0.19672131147540983
+   },
+   "Cell, Antibody -": {
+    "gt": 1,
+    "pred": 1,
+    "abs_err": 0,
+    "rel_err": 0.0
+   },
+   "Cell, Nostril, Antibody +": {
+    "gt": 122,
+    "pred": 112,
+    "abs_err": 10,
+    "rel_err": 0.08196721311475409
+   },
+   "Cell, Nostril, Antibody -": {
+    "gt": 0,
+    "pred": 0,
+    "abs_err": 0,
+    "rel_err": 0.0
+   },
+   "Nostril in Nucleus": {
+    "gt": 169,
+    "pred": 182,
+    "abs_err": 13,
+    "rel_err": 0.07692307692307693
+   },
+   "Nostril External of Nucleus": {
+    "gt": 207,
+    "pred": 258,
+    "abs_err": 51,
+    "rel_err": 0.2463768115942029
+   }
+  },
+  "fp_analysis": null,
+  "pairs": null,
+  "summary": {
+   "cell_det_f1": 0.8864864864864864,
+   "cell_det_precision": 0.8817204301075269,
+   "cell_det_recall": 0.8913043478260869,
+   "cell_mean_iou": 0.800839882168248,
+   "cell_det_f1_iou30": 0.9351351351351351,
+   "cell_det_f1_centroid": 0.9297297297297297,
+   "cell_attr_antibody": 1.0,
+   "cell_attr_nostril": 0.9573170731707317,
+   "cell_attr_both": 0.9573170731707317,
+   "nos_det_f1": 0.8504901960784313,
+   "nos_det_precision": 0.7886363636363637,
+   "nos_det_recall": 0.9228723404255319,
+   "nos_type_acc": 0.9798270893371758,
+   "f1[Cell, Antibody +]": 0.8059701492537313,
+   "f1[Cell, Antibody -]": 1.0,
+   "f1[Cell, Nostril, Antibody +]": 0.8717948717948717,
+   "f1[Cell, Nostril, Antibody -]": 0.0,
+   "f1[Nostril in Nucleus]": 0.8433048433048432,
+   "f1[Nostril External of Nucleus]": 0.8258064516129032
+  }
+ },
+ "C112": {
+  "cells": {
+   "detection": {
+    "tp": 124,
+    "fp": 26,
+    "fn": 22,
+    "precision": 0.8266666666666667,
+    "recall": 0.8493150684931506,
+    "f1": 0.8378378378378378,
+    "mean_iou_matched": 0.7526341825198912,
+    "iou30": {
+     "tp": 134,
+     "fp": 16,
+     "fn": 12,
+     "precision": 0.8933333333333333,
+     "recall": 0.9178082191780822,
+     "f1": 0.9054054054054055
+    },
+    "centroid": {
+     "tp": 133,
+     "fp": 17,
+     "fn": 13,
+     "precision": 0.8866666666666667,
+     "recall": 0.910958904109589,
+     "f1": 0.8986486486486487
+    }
+   },
+   "attribute_accuracy": {
+    "antibody": 0.9919354838709677,
+    "nostril": 1.0,
+    "both": 0.9919354838709677,
+    "n_matched": 124
+   },
+   "per_class": {
+    "Cell, Antibody +": {
+     "tp": 104,
+     "fp": 22,
+     "fn": 20,
+     "precision": 0.8253968253968254,
+     "recall": 0.8387096774193549,
+     "f1": 0.832,
+     "gt_count": 124,
+     "pred_count": 126
+    },
+    "Cell, Antibody -": {
+     "tp": 4,
+     "fp": 1,
+     "fn": 1,
+     "precision": 0.8,
+     "recall": 0.8,
+     "f1": 0.8000000000000002,
+     "gt_count": 5,
+     "pred_count": 5
+    },
+    "Cell, Nostril, Antibody +": {
+     "tp": 15,
+     "fp": 4,
+     "fn": 2,
+     "precision": 0.7894736842105263,
+     "recall": 0.8823529411764706,
+     "f1": 0.8333333333333333,
+     "gt_count": 17,
+     "pred_count": 19
+    },
+    "Cell, Nostril, Antibody -": {
+     "tp": 0,
+     "fp": 0,
+     "fn": 0,
+     "precision": 0.0,
+     "recall": 0.0,
+     "f1": 0.0,
+     "gt_count": 0,
+     "pred_count": 0
+    }
+   },
+   "confusion": {
+    "Cell, Antibody +": {
+     "Cell, Antibody +": 104,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Antibody -": {
+     "Cell, Antibody +": 1,
+     "Cell, Antibody -": 4,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody +": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 15,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody -": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    }
+   },
+   "n_gt": 146,
+   "n_pred": 150
+  },
+  "nostrils": {
+   "detection": {
+    "tp": 25,
+    "fp": 8,
+    "fn": 0,
+    "precision": 0.7575757575757576,
+    "recall": 1.0,
+    "f1": 0.8620689655172413,
+    "mean_dist_matched": 0.934525036066851
+   },
+   "type_accuracy": 1.0,
+   "per_class": {
+    "Nostril in Nucleus": {
+     "tp": 23,
+     "fp": 2,
+     "fn": 0,
+     "precision": 0.92,
+     "recall": 1.0,
+     "f1": 0.9583333333333334,
+     "gt_count": 23,
+     "pred_count": 25
+    },
+    "Nostril External of Nucleus": {
+     "tp": 2,
+     "fp": 6,
+     "fn": 0,
+     "precision": 0.25,
+     "recall": 1.0,
+     "f1": 0.4,
+     "gt_count": 2,
+     "pred_count": 8
+    }
+   },
+   "n_gt": 25,
+   "n_pred": 33
+  },
+  "counts": {
+   "Cell, Antibody +": {
+    "gt": 124,
+    "pred": 126,
+    "abs_err": 2,
+    "rel_err": 0.016129032258064516
+   },
+   "Cell, Antibody -": {
+    "gt": 5,
+    "pred": 5,
+    "abs_err": 0,
+    "rel_err": 0.0
+   },
+   "Cell, Nostril, Antibody +": {
+    "gt": 17,
+    "pred": 19,
+    "abs_err": 2,
+    "rel_err": 0.11764705882352941
+   },
+   "Cell, Nostril, Antibody -": {
+    "gt": 0,
+    "pred": 0,
+    "abs_err": 0,
+    "rel_err": 0.0
+   },
+   "Nostril in Nucleus": {
+    "gt": 23,
+    "pred": 25,
+    "abs_err": 2,
+    "rel_err": 0.08695652173913043
+   },
+   "Nostril External of Nucleus": {
+    "gt": 2,
+    "pred": 8,
+    "abs_err": 6,
+    "rel_err": 3.0
+   }
+  },
+  "fp_analysis": null,
+  "pairs": null,
+  "summary": {
+   "cell_det_f1": 0.8378378378378378,
+   "cell_det_precision": 0.8266666666666667,
+   "cell_det_recall": 0.8493150684931506,
+   "cell_mean_iou": 0.7526341825198912,
+   "cell_det_f1_iou30": 0.9054054054054055,
+   "cell_det_f1_centroid": 0.8986486486486487,
+   "cell_attr_antibody": 0.9919354838709677,
+   "cell_attr_nostril": 1.0,
+   "cell_attr_both": 0.9919354838709677,
+   "nos_det_f1": 0.8620689655172413,
+   "nos_det_precision": 0.7575757575757576,
+   "nos_det_recall": 1.0,
+   "nos_type_acc": 1.0,
+   "f1[Cell, Antibody +]": 0.832,
+   "f1[Cell, Antibody -]": 0.8000000000000002,
+   "f1[Cell, Nostril, Antibody +]": 0.8333333333333333,
+   "f1[Cell, Nostril, Antibody -]": 0.0,
+   "f1[Nostril in Nucleus]": 0.9583333333333334,
+   "f1[Nostril External of Nucleus]": 0.4
+  }
+ },
+ "F100": {
+  "cells": {
+   "detection": {
+    "tp": 160,
+    "fp": 21,
+    "fn": 26,
+    "precision": 0.8839779005524862,
+    "recall": 0.8602150537634409,
+    "f1": 0.871934604904632,
+    "mean_iou_matched": 0.8049454720324757,
+    "iou30": {
+     "tp": 169,
+     "fp": 12,
+     "fn": 17,
+     "precision": 0.9337016574585635,
+     "recall": 0.9086021505376344,
+     "f1": 0.9209809264305177
+    },
+    "centroid": {
+     "tp": 168,
+     "fp": 13,
+     "fn": 18,
+     "precision": 0.9281767955801105,
+     "recall": 0.9032258064516129,
+     "f1": 0.9155313351498637
+    }
+   },
+   "attribute_accuracy": {
+    "antibody": 0.98125,
+    "nostril": 0.98125,
+    "both": 0.9625,
+    "n_matched": 160
+   },
+   "per_class": {
+    "Cell, Antibody +": {
+     "tp": 79,
+     "fp": 17,
+     "fn": 8,
+     "precision": 0.8229166666666666,
+     "recall": 0.9080459770114943,
+     "f1": 0.8633879781420765,
+     "gt_count": 87,
+     "pred_count": 96
+    },
+    "Cell, Antibody -": {
+     "tp": 4,
+     "fp": 2,
+     "fn": 2,
+     "precision": 0.6666666666666666,
+     "recall": 0.6666666666666666,
+     "f1": 0.6666666666666666,
+     "gt_count": 6,
+     "pred_count": 6
+    },
+    "Cell, Nostril, Antibody +": {
+     "tp": 71,
+     "fp": 8,
+     "fn": 22,
+     "precision": 0.8987341772151899,
+     "recall": 0.7634408602150538,
+     "f1": 0.8255813953488371,
+     "gt_count": 93,
+     "pred_count": 79
+    },
+    "Cell, Nostril, Antibody -": {
+     "tp": 0,
+     "fp": 0,
+     "fn": 0,
+     "precision": 0.0,
+     "recall": 0.0,
+     "f1": 0.0,
+     "gt_count": 0,
+     "pred_count": 0
+    }
+   },
+   "confusion": {
+    "Cell, Antibody +": {
+     "Cell, Antibody +": 79,
+     "Cell, Antibody -": 1,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Antibody -": {
+     "Cell, Antibody +": 2,
+     "Cell, Antibody -": 4,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody +": {
+     "Cell, Antibody +": 3,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 71,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody -": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    }
+   },
+   "n_gt": 186,
+   "n_pred": 181
+  },
+  "nostrils": {
+   "detection": {
+    "tp": 142,
+    "fp": 9,
+    "fn": 20,
+    "precision": 0.9403973509933775,
+    "recall": 0.8765432098765432,
+    "f1": 0.9073482428115016,
+    "mean_dist_matched": 1.2296582069626907
+   },
+   "type_accuracy": 0.9929577464788732,
+   "per_class": {
+    "Nostril in Nucleus": {
+     "tp": 102,
+     "fp": 8,
+     "fn": 16,
+     "precision": 0.9272727272727272,
+     "recall": 0.864406779661017,
+     "f1": 0.8947368421052632,
+     "gt_count": 118,
+     "pred_count": 110
+    },
+    "Nostril External of Nucleus": {
+     "tp": 39,
+     "fp": 2,
+     "fn": 5,
+     "precision": 0.9512195121951219,
+     "recall": 0.8863636363636364,
+     "f1": 0.9176470588235294,
+     "gt_count": 44,
+     "pred_count": 41
+    }
+   },
+   "n_gt": 162,
+   "n_pred": 151
+  },
+  "counts": {
+   "Cell, Antibody +": {
+    "gt": 87,
+    "pred": 96,
+    "abs_err": 9,
+    "rel_err": 0.10344827586206896
+   },
+   "Cell, Antibody -": {
+    "gt": 6,
+    "pred": 6,
+    "abs_err": 0,
+    "rel_err": 0.0
+   },
+   "Cell, Nostril, Antibody +": {
+    "gt": 93,
+    "pred": 79,
+    "abs_err": 14,
+    "rel_err": 0.15053763440860216
+   },
+   "Cell, Nostril, Antibody -": {
+    "gt": 0,
+    "pred": 0,
+    "abs_err": 0,
+    "rel_err": 0.0
+   },
+   "Nostril in Nucleus": {
+    "gt": 118,
+    "pred": 110,
+    "abs_err": 8,
+    "rel_err": 0.06779661016949153
+   },
+   "Nostril External of Nucleus": {
+    "gt": 44,
+    "pred": 41,
+    "abs_err": 3,
+    "rel_err": 0.06818181818181818
+   }
+  },
+  "fp_analysis": null,
+  "pairs": null,
+  "summary": {
+   "cell_det_f1": 0.871934604904632,
+   "cell_det_precision": 0.8839779005524862,
+   "cell_det_recall": 0.8602150537634409,
+   "cell_mean_iou": 0.8049454720324757,
+   "cell_det_f1_iou30": 0.9209809264305177,
+   "cell_det_f1_centroid": 0.9155313351498637,
+   "cell_attr_antibody": 0.98125,
+   "cell_attr_nostril": 0.98125,
+   "cell_attr_both": 0.9625,
+   "nos_det_f1": 0.9073482428115016,
+   "nos_det_precision": 0.9403973509933775,
+   "nos_det_recall": 0.8765432098765432,
+   "nos_type_acc": 0.9929577464788732,
+   "f1[Cell, Antibody +]": 0.8633879781420765,
+   "f1[Cell, Antibody -]": 0.6666666666666666,
+   "f1[Cell, Nostril, Antibody +]": 0.8255813953488371,
+   "f1[Cell, Nostril, Antibody -]": 0.0,
+   "f1[Nostril in Nucleus]": 0.8947368421052632,
+   "f1[Nostril External of Nucleus]": 0.9176470588235294
+  }
+ },
+ "F110": {
+  "cells": {
+   "detection": {
+    "tp": 116,
+    "fp": 9,
+    "fn": 12,
+    "precision": 0.928,
+    "recall": 0.90625,
+    "f1": 0.9169960474308302,
+    "mean_iou_matched": 0.8161455695675424,
+    "iou30": {
+     "tp": 120,
+     "fp": 5,
+     "fn": 8,
+     "precision": 0.96,
+     "recall": 0.9375,
+     "f1": 0.9486166007905138
+    },
+    "centroid": {
+     "tp": 121,
+     "fp": 4,
+     "fn": 7,
+     "precision": 0.968,
+     "recall": 0.9453125,
+     "f1": 0.9565217391304348
+    }
+   },
+   "attribute_accuracy": {
+    "antibody": 0.9827586206896551,
+    "nostril": 0.9655172413793104,
+    "both": 0.9482758620689655,
+    "n_matched": 116
+   },
+   "per_class": {
+    "Cell, Antibody +": {
+     "tp": 82,
+     "fp": 10,
+     "fn": 5,
+     "precision": 0.8913043478260869,
+     "recall": 0.9425287356321839,
+     "f1": 0.9162011173184358,
+     "gt_count": 87,
+     "pred_count": 92
+    },
+    "Cell, Antibody -": {
+     "tp": 5,
+     "fp": 0,
+     "fn": 2,
+     "precision": 1.0,
+     "recall": 0.7142857142857143,
+     "f1": 0.8333333333333333,
+     "gt_count": 7,
+     "pred_count": 5
+    },
+    "Cell, Nostril, Antibody +": {
+     "tp": 23,
+     "fp": 5,
+     "fn": 10,
+     "precision": 0.8214285714285714,
+     "recall": 0.696969696969697,
+     "f1": 0.7540983606557378,
+     "gt_count": 33,
+     "pred_count": 28
+    },
+    "Cell, Nostril, Antibody -": {
+     "tp": 0,
+     "fp": 0,
+     "fn": 1,
+     "precision": 0.0,
+     "recall": 0.0,
+     "f1": 0.0,
+     "gt_count": 1,
+     "pred_count": 0
+    }
+   },
+   "confusion": {
+    "Cell, Antibody +": {
+     "Cell, Antibody +": 82,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Antibody -": {
+     "Cell, Antibody +": 2,
+     "Cell, Antibody -": 5,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody +": {
+     "Cell, Antibody +": 4,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 23,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody -": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    }
+   },
+   "n_gt": 128,
+   "n_pred": 125
+  },
+  "nostrils": {
+   "detection": {
+    "tp": 157,
+    "fp": 9,
+    "fn": 37,
+    "precision": 0.9457831325301205,
+    "recall": 0.8092783505154639,
+    "f1": 0.8722222222222222,
+    "mean_dist_matched": 0.7899268230101212
+   },
+   "type_accuracy": 0.9936305732484076,
+   "per_class": {
+    "Nostril in Nucleus": {
+     "tp": 48,
+     "fp": 4,
+     "fn": 9,
+     "precision": 0.9230769230769231,
+     "recall": 0.8421052631578947,
+     "f1": 0.8807339449541285,
+     "gt_count": 57,
+     "pred_count": 52
+    },
+    "Nostril External of Nucleus": {
+     "tp": 108,
+     "fp": 6,
+     "fn": 29,
+     "precision": 0.9473684210526315,
+     "recall": 0.7883211678832117,
+     "f1": 0.8605577689243028,
+     "gt_count": 137,
+     "pred_count": 114
+    }
+   },
+   "n_gt": 194,
+   "n_pred": 166
+  },
+  "counts": {
+   "Cell, Antibody +": {
+    "gt": 87,
+    "pred": 92,
+    "abs_err": 5,
+    "rel_err": 0.05747126436781609
+   },
+   "Cell, Antibody -": {
+    "gt": 7,
+    "pred": 5,
+    "abs_err": 2,
+    "rel_err": 0.2857142857142857
+   },
+   "Cell, Nostril, Antibody +": {
+    "gt": 33,
+    "pred": 28,
+    "abs_err": 5,
+    "rel_err": 0.15151515151515152
+   },
+   "Cell, Nostril, Antibody -": {
+    "gt": 1,
+    "pred": 0,
+    "abs_err": 1,
+    "rel_err": 1.0
+   },
+   "Nostril in Nucleus": {
+    "gt": 57,
+    "pred": 52,
+    "abs_err": 5,
+    "rel_err": 0.08771929824561403
+   },
+   "Nostril External of Nucleus": {
+    "gt": 137,
+    "pred": 114,
+    "abs_err": 23,
+    "rel_err": 0.1678832116788321
+   }
+  },
+  "fp_analysis": null,
+  "pairs": null,
+  "summary": {
+   "cell_det_f1": 0.9169960474308302,
+   "cell_det_precision": 0.928,
+   "cell_det_recall": 0.90625,
+   "cell_mean_iou": 0.8161455695675424,
+   "cell_det_f1_iou30": 0.9486166007905138,
+   "cell_det_f1_centroid": 0.9565217391304348,
+   "cell_attr_antibody": 0.9827586206896551,
+   "cell_attr_nostril": 0.9655172413793104,
+   "cell_attr_both": 0.9482758620689655,
+   "nos_det_f1": 0.8722222222222222,
+   "nos_det_precision": 0.9457831325301205,
+   "nos_det_recall": 0.8092783505154639,
+   "nos_type_acc": 0.9936305732484076,
+   "f1[Cell, Antibody +]": 0.9162011173184358,
+   "f1[Cell, Antibody -]": 0.8333333333333333,
+   "f1[Cell, Nostril, Antibody +]": 0.7540983606557378,
+   "f1[Cell, Nostril, Antibody -]": 0.0,
+   "f1[Nostril in Nucleus]": 0.8807339449541285,
+   "f1[Nostril External of Nucleus]": 0.8605577689243028
+  }
+ },
+ "F113": {
+  "cells": {
+   "detection": {
+    "tp": 131,
+    "fp": 19,
+    "fn": 32,
+    "precision": 0.8733333333333333,
+    "recall": 0.803680981595092,
+    "f1": 0.8370607028753994,
+    "mean_iou_matched": 0.7799368783421308,
+    "iou30": {
+     "tp": 146,
+     "fp": 4,
+     "fn": 17,
+     "precision": 0.9733333333333334,
+     "recall": 0.8957055214723927,
+     "f1": 0.9329073482428116
+    },
+    "centroid": {
+     "tp": 144,
+     "fp": 6,
+     "fn": 19,
+     "precision": 0.96,
+     "recall": 0.8834355828220859,
+     "f1": 0.9201277955271565
+    }
+   },
+   "attribute_accuracy": {
+    "antibody": 1.0,
+    "nostril": 0.9770992366412213,
+    "both": 0.9770992366412213,
+    "n_matched": 131
+   },
+   "per_class": {
+    "Cell, Antibody +": {
+     "tp": 108,
+     "fp": 21,
+     "fn": 30,
+     "precision": 0.8372093023255814,
+     "recall": 0.782608695652174,
+     "f1": 0.8089887640449438,
+     "gt_count": 138,
+     "pred_count": 129
+    },
+    "Cell, Antibody -": {
+     "tp": 2,
+     "fp": 0,
+     "fn": 1,
+     "precision": 1.0,
+     "recall": 0.6666666666666666,
+     "f1": 0.8,
+     "gt_count": 3,
+     "pred_count": 2
+    },
+    "Cell, Nostril, Antibody +": {
+     "tp": 18,
+     "fp": 1,
+     "fn": 4,
+     "precision": 0.9473684210526315,
+     "recall": 0.8181818181818182,
+     "f1": 0.8780487804878049,
+     "gt_count": 22,
+     "pred_count": 19
+    },
+    "Cell, Nostril, Antibody -": {
+     "tp": 0,
+     "fp": 0,
+     "fn": 0,
+     "precision": 0.0,
+     "recall": 0.0,
+     "f1": 0.0,
+     "gt_count": 0,
+     "pred_count": 0
+    }
+   },
+   "confusion": {
+    "Cell, Antibody +": {
+     "Cell, Antibody +": 108,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Antibody -": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 2,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody +": {
+     "Cell, Antibody +": 3,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 18,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody -": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    }
+   },
+   "n_gt": 163,
+   "n_pred": 150
+  },
+  "nostrils": {
+   "detection": {
+    "tp": 27,
+    "fp": 1,
+    "fn": 7,
+    "precision": 0.9642857142857143,
+    "recall": 0.7941176470588235,
+    "f1": 0.8709677419354839,
+    "mean_dist_matched": 0.8145690279889126
+   },
+   "type_accuracy": 0.9259259259259259,
+   "per_class": {
+    "Nostril in Nucleus": {
+     "tp": 21,
+     "fp": 2,
+     "fn": 5,
+     "precision": 0.9130434782608695,
+     "recall": 0.8076923076923077,
+     "f1": 0.8571428571428572,
+     "gt_count": 26,
+     "pred_count": 23
+    },
+    "Nostril External of Nucleus": {
+     "tp": 4,
+     "fp": 1,
+     "fn": 4,
+     "precision": 0.8,
+     "recall": 0.5,
+     "f1": 0.6153846153846154,
+     "gt_count": 8,
+     "pred_count": 5
+    }
+   },
+   "n_gt": 34,
+   "n_pred": 28
+  },
+  "counts": {
+   "Cell, Antibody +": {
+    "gt": 138,
+    "pred": 129,
+    "abs_err": 9,
+    "rel_err": 0.06521739130434782
+   },
+   "Cell, Antibody -": {
+    "gt": 3,
+    "pred": 2,
+    "abs_err": 1,
+    "rel_err": 0.3333333333333333
+   },
+   "Cell, Nostril, Antibody +": {
+    "gt": 22,
+    "pred": 19,
+    "abs_err": 3,
+    "rel_err": 0.13636363636363635
+   },
+   "Cell, Nostril, Antibody -": {
+    "gt": 0,
+    "pred": 0,
+    "abs_err": 0,
+    "rel_err": 0.0
+   },
+   "Nostril in Nucleus": {
+    "gt": 26,
+    "pred": 23,
+    "abs_err": 3,
+    "rel_err": 0.11538461538461539
+   },
+   "Nostril External of Nucleus": {
+    "gt": 8,
+    "pred": 5,
+    "abs_err": 3,
+    "rel_err": 0.375
+   }
+  },
+  "fp_analysis": null,
+  "pairs": null,
+  "summary": {
+   "cell_det_f1": 0.8370607028753994,
+   "cell_det_precision": 0.8733333333333333,
+   "cell_det_recall": 0.803680981595092,
+   "cell_mean_iou": 0.7799368783421308,
+   "cell_det_f1_iou30": 0.9329073482428116,
+   "cell_det_f1_centroid": 0.9201277955271565,
+   "cell_attr_antibody": 1.0,
+   "cell_attr_nostril": 0.9770992366412213,
+   "cell_attr_both": 0.9770992366412213,
+   "nos_det_f1": 0.8709677419354839,
+   "nos_det_precision": 0.9642857142857143,
+   "nos_det_recall": 0.7941176470588235,
+   "nos_type_acc": 0.9259259259259259,
+   "f1[Cell, Antibody +]": 0.8089887640449438,
+   "f1[Cell, Antibody -]": 0.8,
+   "f1[Cell, Nostril, Antibody +]": 0.8780487804878049,
+   "f1[Cell, Nostril, Antibody -]": 0.0,
+   "f1[Nostril in Nucleus]": 0.8571428571428572,
+   "f1[Nostril External of Nucleus]": 0.6153846153846154
+  }
+ },
+ "F114": {
+  "cells": {
+   "detection": {
+    "tp": 211,
+    "fp": 25,
+    "fn": 31,
+    "precision": 0.8940677966101694,
+    "recall": 0.871900826446281,
+    "f1": 0.8828451882845189,
+    "mean_iou_matched": 0.8168843572713155,
+    "iou30": {
+     "tp": 222,
+     "fp": 14,
+     "fn": 20,
+     "precision": 0.940677966101695,
+     "recall": 0.9173553719008265,
+     "f1": 0.9288702928870294
+    },
+    "centroid": {
+     "tp": 221,
+     "fp": 15,
+     "fn": 21,
+     "precision": 0.9364406779661016,
+     "recall": 0.9132231404958677,
+     "f1": 0.9246861924686192
+    }
+   },
+   "attribute_accuracy": {
+    "antibody": 0.95260663507109,
+    "nostril": 0.981042654028436,
+    "both": 0.933649289099526,
+    "n_matched": 211
+   },
+   "per_class": {
+    "Cell, Antibody +": {
+     "tp": 148,
+     "fp": 28,
+     "fn": 27,
+     "precision": 0.8409090909090909,
+     "recall": 0.8457142857142858,
+     "f1": 0.8433048433048433,
+     "gt_count": 175,
+     "pred_count": 176
+    },
+    "Cell, Antibody -": {
+     "tp": 12,
+     "fp": 2,
+     "fn": 9,
+     "precision": 0.8571428571428571,
+     "recall": 0.5714285714285714,
+     "f1": 0.6857142857142857,
+     "gt_count": 21,
+     "pred_count": 14
+    },
+    "Cell, Nostril, Antibody +": {
+     "tp": 37,
+     "fp": 9,
+     "fn": 5,
+     "precision": 0.8043478260869565,
+     "recall": 0.8809523809523809,
+     "f1": 0.8409090909090908,
+     "gt_count": 42,
+     "pred_count": 46
+    },
+    "Cell, Nostril, Antibody -": {
+     "tp": 0,
+     "fp": 0,
+     "fn": 4,
+     "precision": 0.0,
+     "recall": 0.0,
+     "f1": 0.0,
+     "gt_count": 4,
+     "pred_count": 0
+    }
+   },
+   "confusion": {
+    "Cell, Antibody +": {
+     "Cell, Antibody +": 148,
+     "Cell, Antibody -": 1,
+     "Cell, Nostril, Antibody +": 4,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Antibody -": {
+     "Cell, Antibody +": 9,
+     "Cell, Antibody -": 12,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody +": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 37,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody -": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    }
+   },
+   "n_gt": 242,
+   "n_pred": 236
+  },
+  "nostrils": {
+   "detection": {
+    "tp": 81,
+    "fp": 24,
+    "fn": 9,
+    "precision": 0.7714285714285715,
+    "recall": 0.9,
+    "f1": 0.8307692307692307,
+    "mean_dist_matched": 0.9417483459046142
+   },
+   "type_accuracy": 1.0,
+   "per_class": {
+    "Nostril in Nucleus": {
+     "tp": 46,
+     "fp": 8,
+     "fn": 6,
+     "precision": 0.8518518518518519,
+     "recall": 0.8846153846153846,
+     "f1": 0.8679245283018868,
+     "gt_count": 52,
+     "pred_count": 54
+    },
+    "Nostril External of Nucleus": {
+     "tp": 35,
+     "fp": 16,
+     "fn": 3,
+     "precision": 0.6862745098039216,
+     "recall": 0.9210526315789473,
+     "f1": 0.7865168539325842,
+     "gt_count": 38,
+     "pred_count": 51
+    }
+   },
+   "n_gt": 90,
+   "n_pred": 105
+  },
+  "counts": {
+   "Cell, Antibody +": {
+    "gt": 175,
+    "pred": 176,
+    "abs_err": 1,
+    "rel_err": 0.005714285714285714
+   },
+   "Cell, Antibody -": {
+    "gt": 21,
+    "pred": 14,
+    "abs_err": 7,
+    "rel_err": 0.3333333333333333
+   },
+   "Cell, Nostril, Antibody +": {
+    "gt": 42,
+    "pred": 46,
+    "abs_err": 4,
+    "rel_err": 0.09523809523809523
+   },
+   "Cell, Nostril, Antibody -": {
+    "gt": 4,
+    "pred": 0,
+    "abs_err": 4,
+    "rel_err": 1.0
+   },
+   "Nostril in Nucleus": {
+    "gt": 52,
+    "pred": 54,
+    "abs_err": 2,
+    "rel_err": 0.038461538461538464
+   },
+   "Nostril External of Nucleus": {
+    "gt": 38,
+    "pred": 51,
+    "abs_err": 13,
+    "rel_err": 0.34210526315789475
+   }
+  },
+  "fp_analysis": null,
+  "pairs": null,
+  "summary": {
+   "cell_det_f1": 0.8828451882845189,
+   "cell_det_precision": 0.8940677966101694,
+   "cell_det_recall": 0.871900826446281,
+   "cell_mean_iou": 0.8168843572713155,
+   "cell_det_f1_iou30": 0.9288702928870294,
+   "cell_det_f1_centroid": 0.9246861924686192,
+   "cell_attr_antibody": 0.95260663507109,
+   "cell_attr_nostril": 0.981042654028436,
+   "cell_attr_both": 0.933649289099526,
+   "nos_det_f1": 0.8307692307692307,
+   "nos_det_precision": 0.7714285714285715,
+   "nos_det_recall": 0.9,
+   "nos_type_acc": 1.0,
+   "f1[Cell, Antibody +]": 0.8433048433048433,
+   "f1[Cell, Antibody -]": 0.6857142857142857,
+   "f1[Cell, Nostril, Antibody +]": 0.8409090909090908,
+   "f1[Cell, Nostril, Antibody -]": 0.0,
+   "f1[Nostril in Nucleus]": 0.8679245283018868,
+   "f1[Nostril External of Nucleus]": 0.7865168539325842
+  }
+ },
+ "F99": {
+  "cells": {
+   "detection": {
+    "tp": 227,
+    "fp": 28,
+    "fn": 24,
+    "precision": 0.8901960784313725,
+    "recall": 0.9043824701195219,
+    "f1": 0.8972332015810275,
+    "mean_iou_matched": 0.8280746396024866,
+    "iou30": {
+     "tp": 238,
+     "fp": 17,
+     "fn": 13,
+     "precision": 0.9333333333333333,
+     "recall": 0.9482071713147411,
+     "f1": 0.9407114624505929
+    },
+    "centroid": {
+     "tp": 238,
+     "fp": 17,
+     "fn": 13,
+     "precision": 0.9333333333333333,
+     "recall": 0.9482071713147411,
+     "f1": 0.9407114624505929
+    }
+   },
+   "attribute_accuracy": {
+    "antibody": 0.920704845814978,
+    "nostril": 0.9911894273127754,
+    "both": 0.9118942731277533,
+    "n_matched": 227
+   },
+   "per_class": {
+    "Cell, Antibody +": {
+     "tp": 162,
+     "fp": 41,
+     "fn": 21,
+     "precision": 0.7980295566502463,
+     "recall": 0.8852459016393442,
+     "f1": 0.839378238341969,
+     "gt_count": 183,
+     "pred_count": 203
+    },
+    "Cell, Antibody -": {
+     "tp": 42,
+     "fp": 6,
+     "fn": 20,
+     "precision": 0.875,
+     "recall": 0.6774193548387096,
+     "f1": 0.7636363636363636,
+     "gt_count": 62,
+     "pred_count": 48
+    },
+    "Cell, Nostril, Antibody +": {
+     "tp": 3,
+     "fp": 1,
+     "fn": 3,
+     "precision": 0.75,
+     "recall": 0.5,
+     "f1": 0.6,
+     "gt_count": 6,
+     "pred_count": 4
+    },
+    "Cell, Nostril, Antibody -": {
+     "tp": 0,
+     "fp": 0,
+     "fn": 0,
+     "precision": 0.0,
+     "recall": 0.0,
+     "f1": 0.0,
+     "gt_count": 0,
+     "pred_count": 0
+    }
+   },
+   "confusion": {
+    "Cell, Antibody +": {
+     "Cell, Antibody +": 162,
+     "Cell, Antibody -": 4,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Antibody -": {
+     "Cell, Antibody +": 14,
+     "Cell, Antibody -": 42,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody +": {
+     "Cell, Antibody +": 2,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 3,
+     "Cell, Nostril, Antibody -": 0
+    },
+    "Cell, Nostril, Antibody -": {
+     "Cell, Antibody +": 0,
+     "Cell, Antibody -": 0,
+     "Cell, Nostril, Antibody +": 0,
+     "Cell, Nostril, Antibody -": 0
+    }
+   },
+   "n_gt": 251,
+   "n_pred": 255
+  },
+  "nostrils": {
+   "detection": {
+    "tp": 14,
+    "fp": 1,
+    "fn": 8,
+    "precision": 0.9333333333333333,
+    "recall": 0.6363636363636364,
+    "f1": 0.7567567567567568,
+    "mean_dist_matched": 0.6631874114708707
+   },
+   "type_accuracy": 1.0,
+   "per_class": {
+    "Nostril in Nucleus": {
+     "tp": 4,
+     "fp": 0,
+     "fn": 2,
+     "precision": 1.0,
+     "recall": 0.6666666666666666,
+     "f1": 0.8,
+     "gt_count": 6,
+     "pred_count": 4
+    },
+    "Nostril External of Nucleus": {
+     "tp": 10,
+     "fp": 1,
+     "fn": 6,
+     "precision": 0.9090909090909091,
+     "recall": 0.625,
+     "f1": 0.7407407407407406,
+     "gt_count": 16,
+     "pred_count": 11
+    }
+   },
+   "n_gt": 22,
+   "n_pred": 15
+  },
+  "counts": {
+   "Cell, Antibody +": {
+    "gt": 183,
+    "pred": 203,
+    "abs_err": 20,
+    "rel_err": 0.1092896174863388
+   },
+   "Cell, Antibody -": {
+    "gt": 62,
+    "pred": 48,
+    "abs_err": 14,
+    "rel_err": 0.22580645161290322
+   },
+   "Cell, Nostril, Antibody +": {
+    "gt": 6,
+    "pred": 4,
+    "abs_err": 2,
+    "rel_err": 0.3333333333333333
+   },
+   "Cell, Nostril, Antibody -": {
+    "gt": 0,
+    "pred": 0,
+    "abs_err": 0,
+    "rel_err": 0.0
+   },
+   "Nostril in Nucleus": {
+    "gt": 6,
+    "pred": 4,
+    "abs_err": 2,
+    "rel_err": 0.3333333333333333
+   },
+   "Nostril External of Nucleus": {
+    "gt": 16,
+    "pred": 11,
+    "abs_err": 5,
+    "rel_err": 0.3125
+   }
+  },
+  "fp_analysis": null,
+  "pairs": null,
+  "summary": {
+   "cell_det_f1": 0.8972332015810275,
+   "cell_det_precision": 0.8901960784313725,
+   "cell_det_recall": 0.9043824701195219,
+   "cell_mean_iou": 0.8280746396024866,
+   "cell_det_f1_iou30": 0.9407114624505929,
+   "cell_det_f1_centroid": 0.9407114624505929,
+   "cell_attr_antibody": 0.920704845814978,
+   "cell_attr_nostril": 0.9911894273127754,
+   "cell_attr_both": 0.9118942731277533,
+   "nos_det_f1": 0.7567567567567568,
+   "nos_det_precision": 0.9333333333333333,
+   "nos_det_recall": 0.6363636363636364,
+   "nos_type_acc": 1.0,
+   "f1[Cell, Antibody +]": 0.839378238341969,
+   "f1[Cell, Antibody -]": 0.7636363636363636,
+   "f1[Cell, Nostril, Antibody +]": 0.6,
+   "f1[Cell, Nostril, Antibody -]": 0.0,
+   "f1[Nostril in Nucleus]": 0.8,
+   "f1[Nostril External of Nucleus]": 0.7407407407407406
+  }
+ }
+}

requirements.txt

@@ -0,0 +1,12 @@
+--extra-index-url https://download.pytorch.org/whl/cpu
+torch>=2.2
+torchvision>=0.17
+timm>=0.9.7
+numpy>=1.26
+scipy>=1.11
+scikit-image>=0.22
+tifffile>=2023.7
+imagecodecs>=2023.7
+Pillow>=10
+gradio>=5.0
+google-genai>=1.0

scripts/build_summary.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Write reports/SUMMARY.md from runs/cv/cv_results.json and reports/final/final_fit.json."""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, ROOT)
+from cellquant.labels import ALL_LABELS, CELL_LABELS, NOSTRIL_LABELS  # noqa: E402
+
+
+def pct(x: float) -> str:
+    return f"{100 * x:.1f}%"
+
+
+def main():
+    cv = json.load(open(os.path.join(ROOT, "runs", "cv", "cv_results.json")))
+    agg = cv["aggregate"]
+    per = agg["per_image"]
+    fit = json.load(open(os.path.join(ROOT, "reports", "final", "final_fit.json")))
+    tot = agg["dataset_totals"]
+    n_nuc = sum(tot[c] for c in CELL_LABELS)
+    n_pun = sum(tot[c] for c in NOSTRIL_LABELS)
+    det = agg["detection_base"]
+    det8 = agg["detection_tta8"]
+    L = ["# CellQuant: validation summary", "",
+         f"Data: {len(per)} annotated 1024×1024 images, {n_nuc} nucleus outlines and {n_pun} punctum outlines.",
+         "Protocol: leave-one-image-out cross-validation (one model per image, 3000 iterations each, held-out image never seen in training), "
+         "then a final model trained on all images with the same recipe. Each held-out image was tested 23 times: 3 identical runs "
+         "(determinism), no-TTA / 4× / 8× test-time augmentation, 8 rotations and flips, 6 photometric perturbations, and 6 post-processing rule variants. "
+         "The only choice made on held-out data is the rule that gives a nucleus the Nostril attribute: of three candidate rules, "
+         "'contains an in-nucleus punctum' (the annotation protocol) scored best and is the default; see the rule-variant table in cv_report.md.", "",
+         "## Headline numbers (micro-averaged over all held-out images, no TTA)", "",
+         "| Measure | Precision | Recall | F1 |", "|---|---:|---:|---:|",
+         f"| Nucleus detection, IoU ≥ 0.5 | {pct(det['cells']['precision'])} | {pct(det['cells']['recall'])} | {pct(det['cells']['f1'])} |",
+         f"| Nucleus detection, IoU ≥ 0.3 | {pct(det['cells_iou30']['precision'])} | {pct(det['cells_iou30']['recall'])} | {pct(det['cells_iou30']['f1'])} |",
+         f"| Nucleus detection, centroid inside GT nucleus | {pct(det['cells_centroid']['precision'])} | {pct(det['cells_centroid']['recall'])} | {pct(det['cells_centroid']['f1'])} |",
+         f"| Punctum detection (centroid ≤ 6 px) | {pct(det['nostrils']['precision'])} | {pct(det['nostrils']['recall'])} | {pct(det['nostrils']['f1'])} |",
+         f"| Nucleus detection, IoU ≥ 0.5, 8× TTA | {pct(det8['cells']['precision'])} | {pct(det8['cells']['recall'])} | {pct(det8['cells']['f1'])} |",
+         "", "Per-class F1 (a true positive needs a matched object **and** the right label):", "",
+         "| Label | GT | Pred | F1 |", "|---|---:|---:|---:|"]
+    for lab in ALL_LABELS:
+        r = agg["micro_base"][lab]
+        L.append(f"| {lab} | {r['gt_count']} | {r['pred_count']} | {pct(r['f1'])} |")
+    L += ["", "## Per held-out image", "",
+          "| Image | Nuclei F1 | Antibody acc | Nostril-attr acc | Puncta F1 | Nuclei F1 over 14 perturbed runs (mean ± sd) | Deterministic |",
+          "|---|---:|---:|---:|---:|---|---|"]
+    for k, s in per.items():
+        b = s["base"]; r = s["robustness"]["cell_det_f1"]
+        L.append(f"| {k} | {pct(b['cell_det_f1'])} | {pct(b['cell_attr_antibody'])} | {pct(b['cell_attr_nostril'])} | {pct(b['nos_det_f1'])} | "
+                 f"{100*r['mean']:.1f} ± {100*r['std']:.1f} | {'yes' if s['deterministic'] else 'no'} |")
+    L += ["", "## Final model (trained on all images) – fit on its own training images, NOT a generalisation estimate", "",
+          "| Image | Nuclei F1 | Attribute acc | Puncta F1 |", "|---|---:|---:|---:|"]
+    for k, v in fit.items():
+        if "summary" in v:
+            s = v["summary"]
+            L.append(f"| {k} | {pct(s['cell_det_f1'])} | {pct(s['cell_attr_both'])} | {pct(s['nos_det_f1'])} |")
+    sw = agg.get("antibody_threshold_sweep")
+    if sw:
+        best = max(sw["sweep"], key=lambda r: r["neg_f1"])
+        L += ["", f"## Antibody − threshold (held-out matched nuclei: {sw['n_matched']}, of which {sw['n_negative']} negative)", "",
+              f"Default threshold 0.5. Best Antibody − F1 in the sweep: {pct(best['neg_f1'])} at threshold {best['thr']:.2f} "
+              f"(precision {pct(best['neg_precision'])}, recall {pct(best['neg_recall'])}); the full curve is in cv_report.md. "
+              "The default was kept because the class is dominated by a single image (F99 holds 62 of the 102 negatives)."]
+    L += ["", "## What limits the scores", "",
+          "* **Touching nuclei are sometimes merged** into one outline (worst on F113); this is the main source of IoU-0.5 misses. The marker/threshold sweep (`runs/cv/postprocess_sweep.json`) is flat, so it is a network-border issue, not a post-processing one.",
+          "* **Annotation completeness**: most unmatched predictions overlap an annotated nucleus (outline disagreement) and the rest are dimmer, smaller objects the annotator skipped; many faint red dots were likewise not annotated, which caps external-punctum precision.",
+          "* **Antibody − is rare** (102 of 1569 nuclei, 62 in one image), and **Cell, Nostril, Antibody −** has five examples; their scores are not reliable.",
+          "* Scores are from nine images of one experiment (35-day spinal cord, Iba1/TMEM119). New staining batches or magnifications need a check against a few annotated images.",
+          "", "## Reproduce", "",
+          "```bash", "python evaluate.py cv --data-dir <folder with TIFs and CVAT zips> --runs-dir runs/cv --iters 3000",
+          "python evaluate.py final --data-dir <folder> --weights weights/cellquant.pt", "python scripts/build_summary.py", "```", ""]
+    out = os.path.join(ROOT, "reports", "SUMMARY.md")
+    with open(out, "w") as f:
+        f.write("\n".join(L))
+    print("wrote", out)
+
+
+if __name__ == "__main__":
+    main()

scripts/deploy_hf.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Create / update the CellQuant Space on Hugging Face and wait until it runs.
+
+    python scripts/deploy_hf.py --repo <user>/cellquant [--public] [--no-wait]
+
+Uses the token from `hf auth login` (or HF_TOKEN). Large files (the .pt checkpoint)
+are uploaded through LFS automatically. Then polls the Space runtime and, once it is
+RUNNING, calls its API with the bundled example image to prove it works.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+
+from huggingface_hub import HfApi, get_token, whoami
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+IGNORE = ["runs/**", "runs/*", ".pytest_cache/**", "**/__pycache__/**", "__pycache__/**", "*.pyc",
+          "reports/final/*.png", "reports/cv/*.png", "*.log", ".gitignore", ".DS_Store"]
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--repo", default=None, help="<user>/<space-name>; default <me>/cellquant")
+    ap.add_argument("--public", action="store_true")
+    ap.add_argument("--no-wait", action="store_true")
+    ap.add_argument("--timeout", type=int, default=1800)
+    a = ap.parse_args(argv)
+    api = HfApi()
+    me = whoami()["name"]
+    repo = a.repo or f"{me}/cellquant"
+    if not os.path.exists(os.path.join(ROOT, "weights", "cellquant.pt")):
+        raise SystemExit("weights/cellquant.pt missing: train first")
+    url = api.create_repo(repo, repo_type="space", space_sdk="gradio", private=not a.public, exist_ok=True)
+    print("space:", url)
+    api.upload_folder(folder_path=ROOT, repo_id=repo, repo_type="space", ignore_patterns=IGNORE,
+                      commit_message="Deploy CellQuant")
+    print("uploaded")
+    if a.no_wait:
+        return
+    t0 = time.time()
+    last = None
+    while time.time() - t0 < a.timeout:
+        rt = api.get_space_runtime(repo)
+        stage = str(rt.stage)
+        if stage != last:
+            print(f"[{time.time()-t0:5.0f}s] stage {stage} hardware {rt.hardware}", flush=True)
+            last = stage
+        if stage.endswith("RUNNING"):
+            break
+        if "ERROR" in stage or stage.endswith("STOPPED"):
+            print("build failed; last log lines:")
+            try:
+                print(api.get_space_runtime(repo))
+            except Exception as e:  # noqa: BLE001
+                print(e)
+            sys.exit(1)
+        time.sleep(15)
+    else:
+        raise SystemExit("timed out waiting for the Space")
+    # smoke test through the Gradio API
+    from gradio_client import Client, handle_file
+    client = Client(repo, hf_token=get_token())
+    ex = os.path.join(ROOT, "examples", "F100_crop_512.png")
+    t = time.time()
+    out = client.predict([handle_file(ex)], "none (fastest)", 0.5, 0.5, 50, "head", "contains", False, api_name="/analyze_files")
+    print(f"API call ok in {time.time()-t:.1f}s; counts row: {out[0]['data'][0] if isinstance(out[0], dict) else out[0]}")
+
+
+if __name__ == "__main__":
+    main()

scripts/postprocess_sweep.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Sweep post-processing thresholds on held-out fold predictions (no retraining).
+
+    python scripts/postprocess_sweep.py --data-dir DATA --runs-dir runs/cv [--keys A,B] [--device mps]
+
+For every fold checkpoint the held-out image is predicted once; every PostConfig in
+the grid is then scored on the same probabilities. Prints micro-averaged nucleus
+detection F1 (IoU >= 0.5 and centroid rule) and per-class F1 per setting.
+"""
+from __future__ import annotations
+
+import argparse
+import itertools
+import json
+import os
+import sys
+
+import numpy as np
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from cellquant.annotations import discover, load_image, rasterize  # noqa: E402
+from cellquant.infer import Predictor  # noqa: E402
+from cellquant.labels import CELL_LABELS, NOSTRIL_LABELS  # noqa: E402
+from cellquant.metrics import evaluate_cells, evaluate_nostrils, micro_average, prf  # noqa: E402
+from cellquant.postprocess import PostConfig, analyze  # noqa: E402
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--data-dir", required=True)
+    ap.add_argument("--runs-dir", default="runs/cv")
+    ap.add_argument("--keys", default="")
+    ap.add_argument("--device", default="auto")
+    ap.add_argument("--out", default="")
+    a = ap.parse_args(argv)
+    samples, _ = discover(a.data_dir, verbose=False)
+    keys = a.keys.split(",") if a.keys else [s.key for s in samples]
+    grid = [PostConfig(marker_thr=m, cell_fg_thr=f, min_marker_area=ma)
+            for m, f, ma in itertools.product((0.5, 0.6, 0.7, 0.8), (0.4, 0.5), (12, 30))]
+    per_cfg = {i: [] for i in range(len(grid))}
+    for s in samples:
+        if s.key not in keys:
+            continue
+        ck = os.path.join(a.runs_dir, f"fold_{s.key}.pt")
+        if not os.path.exists(ck):
+            print("missing", ck)
+            continue
+        img = load_image(s.image_path)
+        R = rasterize(s.annotation, img.shape[0], img.shape[1])
+        probs = Predictor(ck, device=a.device, tta=1).probs(img)
+        for i, cfg in enumerate(grid):
+            res = analyze(probs, cfg)
+            ce = evaluate_cells(R.cell_inst, R.cell_labels, res.cell_inst, res.cell_labels)
+            ne = evaluate_nostrils(R.nostril_inst, R.nostril_labels, res.nostril_inst, res.nostril_labels)
+            per_cfg[i].append({"key": s.key, "det": ce["detection"], "cells": ce["per_class"], "nos": ne["per_class"],
+                               "attr": ce["attribute_accuracy"]})
+        print("done", s.key, flush=True)
+    rows = []
+    for i, cfg in enumerate(grid):
+        rs = per_cfg[i]
+        if not rs:
+            continue
+        tp = sum(r["det"]["tp"] for r in rs); fp = sum(r["det"]["fp"] for r in rs); fn = sum(r["det"]["fn"] for r in rs)
+        ctp = sum(r["det"]["centroid"]["tp"] for r in rs); cfp = sum(r["det"]["centroid"]["fp"] for r in rs); cfn = sum(r["det"]["centroid"]["fn"] for r in rs)
+        mc = micro_average([r["cells"] for r in rs], CELL_LABELS)
+        mn = micro_average([r["nos"] for r in rs], NOSTRIL_LABELS)
+        per_img = {r["key"]: round(r["det"]["f1"], 3) for r in rs}
+        rows.append({"marker_thr": cfg.marker_thr, "cell_fg_thr": cfg.cell_fg_thr, "min_marker_area": cfg.min_marker_area,
+                     "nuc_f1_iou50": prf(tp, fp, fn)["f1"], "nuc_f1_centroid": prf(ctp, cfp, cfn)["f1"],
+                     "f1_ab_pos": mc["Cell, Antibody +"]["f1"], "f1_ab_neg": mc["Cell, Antibody -"]["f1"],
+                     "f1_nos_pos": mc["Cell, Nostril, Antibody +"]["f1"], "f1_pin": mn["Nostril in Nucleus"]["f1"],
+                     "per_image": per_img})
+    rows.sort(key=lambda r: -r["nuc_f1_iou50"])
+    print(f"{'marker':>6} {'fg':>4} {'minA':>4} | {'nucF1@.5':>8} {'nucF1cen':>8} | {'Ab+':>6} {'Ab-':>6} {'NosAb+':>6} {'PinNuc':>6} | per image")
+    for r in rows:
+        print(f"{r['marker_thr']:6.2f} {r['cell_fg_thr']:4.1f} {r['min_marker_area']:4d} | {100*r['nuc_f1_iou50']:8.1f} {100*r['nuc_f1_centroid']:8.1f} | "
+              f"{100*r['f1_ab_pos']:6.1f} {100*r['f1_ab_neg']:6.1f} {100*r['f1_nos_pos']:6.1f} {100*r['f1_pin']:6.1f} | "
+              + " ".join(f"{k}:{100*v:.0f}" for k, v in r['per_image'].items()))
+    if a.out:
+        with open(a.out, "w") as f:
+            json.dump(rows, f, indent=1)
+
+
+if __name__ == "__main__":
+    main()

tests/conftest.py

@@ -0,0 +1,4 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

tests/test_annotations.py

@@ -0,0 +1,115 @@
+import os
+import zipfile
+
+import numpy as np
+import pytest
+
+from cellquant.annotations import (
+    ImageAnnotation,
+    Shape,
+    discover,
+    image_key,
+    load_annotation_file,
+    parse_cvat_xml,
+    rasterize,
+    to_rgb_uint8,
+)
+
+XML = """<?xml version="1.0" encoding="utf-8"?>
+<annotations>
+  <version>1.1</version>
+  <meta><task><size>1</size></task></meta>
+  <image id="0" name="K1 demo - RGB copy.tif" width="100" height="80">
+    <polyline label="Cell, Antibody +" source="manual" occluded="0" points="10.0,10.0;30.0,10.0;30.0,30.0;10.0,30.0;10.0,10.0" z_order="0"></polyline>
+    <polygon label="Cell, Nostril, Antibody -" source="manual" occluded="0" points="50,50;70,50;70,70;50,70" z_order="0"></polygon>
+    <ellipse label="Nostril in Nucleus" source="manual" occluded="0" cx="60" cy="60" rx="3" ry="2" z_order="0"></ellipse>
+    <polyline label="Nostril External of Nucleus" source="manual" occluded="0" points="90.2,5.1;90.4,5.3;90.6,5.1" z_order="0"></polyline>
+    <box label="Cell, Antibody -" source="manual" occluded="0" xtl="80" ytl="60" xbr="95" ybr="75" z_order="0"></box>
+  </image>
+</annotations>
+"""
+
+
+def test_parse_xml_shapes_and_counts():
+    anns = parse_cvat_xml(XML.encode())
+    assert len(anns) == 1
+    a = anns[0]
+    assert (a.width, a.height) == (100, 80)
+    assert a.key == "K1"
+    c = a.counts()
+    assert c["Cell, Antibody +"] == 1 and c["Cell, Nostril, Antibody -"] == 1 and c["Cell, Antibody -"] == 1
+    assert c["Nostril in Nucleus"] == 1 and c["Nostril External of Nucleus"] == 1
+
+
+def test_rasterize_areas_and_attributes():
+    a = parse_cvat_xml(XML.encode())[0]
+    R = rasterize(a)
+    assert R.cell_inst.shape == (80, 100)
+    assert R.n_cells == 3 and R.n_nostrils == 2
+    areas = np.bincount(R.cell_inst.ravel())[1:]
+    # 20x20 squares rasterise to ~21x21 pixels (inclusive edges) -> 400..441
+    assert all(380 <= x <= 450 for x in areas[:2]) or all(380 <= x <= 450 for x in sorted(areas)[-2:])
+    # tiny polyline (sub-pixel) keeps its centroid pixel
+    nareas = np.bincount(R.nostril_inst.ravel())[1:]
+    assert nareas.min() >= 1
+    # ellipse rx=3, ry=2 -> pi*6 ~ 19 px
+    assert 10 <= nareas.max() <= 30
+    ab = R.cell_antibody()
+    hn = R.cell_has_nostril()
+    labels = R.cell_labels
+    for i, lab in enumerate(labels):
+        if i == 0:
+            continue
+        assert ab[i] == lab.endswith("+")
+        assert hn[i] == ("Nostril" in lab)
+    assert R.nostril_inside().sum() == 1
+
+
+def test_image_key_handles_copies_and_double_spaces():
+    assert image_key("F114  F 35D SC Iba W002 - Focused EDF Document_RGB.tif") == "F114"
+    assert image_key("C110 F 35D SC Iba W001 - Focused EDF Document_RGB copy (1).tif") == "C110"
+
+
+def test_discover_pairs_by_internal_name(tmp_path):
+    from PIL import Image
+    Image.fromarray(np.zeros((80, 100, 3), np.uint8)).save(tmp_path / "K1 demo - RGB copy (1).png")
+    Image.fromarray(np.zeros((80, 100, 3), np.uint8)).save(tmp_path / "K2 other.png")  # unannotated
+    with zipfile.ZipFile(tmp_path / "WRONGNAME_Annotated.zip", "w") as zf:
+        zf.writestr("annotations.xml", XML)
+    samples, unann = discover(str(tmp_path), verbose=False)
+    assert [s.key for s in samples] == ["K1"]
+    assert len(unann) == 1 and unann[0].endswith("K2 other.png")
+    assert samples[0].annotation.count("Cell, Antibody +") == 1
+
+
+def test_load_annotation_file_zip_and_xml(tmp_path):
+    (tmp_path / "a.xml").write_text(XML)
+    with zipfile.ZipFile(tmp_path / "a.zip", "w") as zf:
+        zf.writestr("annotations.xml", XML)
+    assert len(load_annotation_file(str(tmp_path / "a.xml"))[0].shapes) == 5
+    assert len(load_annotation_file(str(tmp_path / "a.zip"))[0].shapes) == 5
+    with pytest.raises(ValueError):
+        load_annotation_file(str(tmp_path / "nothing.txt"))
+
+
+def test_to_rgb_uint8_variants():
+    g = np.full((4, 5), 7, np.uint8)
+    assert to_rgb_uint8(g).shape == (4, 5, 3)
+    chw = np.zeros((3, 4, 5), np.uint8)
+    assert to_rgb_uint8(chw).shape == (4, 5, 3)
+    rgba = np.zeros((4, 5, 4), np.uint8)
+    assert to_rgb_uint8(rgba).shape == (4, 5, 3)
+    u16 = np.full((4, 5, 3), 4000, np.uint16)
+    out = to_rgb_uint8(u16)
+    assert out.dtype == np.uint8 and out.max() == 255
+    f01 = np.full((4, 5, 3), 0.5, np.float32)
+    assert to_rgb_uint8(f01).max() in (127, 128)
+    with pytest.raises(ValueError):
+        to_rgb_uint8(np.zeros((40, 50, 2), np.uint8))
+    with pytest.raises(ValueError):
+        to_rgb_uint8(np.zeros((4, 50, 2), np.uint8))   # 4 rows is not "RGBA channel-first"
+
+
+def test_shape_area_shoelace():
+    s = Shape("Cell, Antibody +", "polygon", np.array([[0, 0], [10, 0], [10, 10], [0, 10]], np.float32))
+    assert abs(s.area - 100) < 1e-6

tests/test_app.py

@@ -0,0 +1,34 @@
+import os
+
+import numpy as np
+import pytest
+from PIL import Image
+
+WEIGHTS = os.environ.get("CELLQUANT_WEIGHTS", os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "weights", "cellquant.pt"))
+
+
+@pytest.mark.skipif(not os.path.exists(WEIGHTS), reason="trained weights not present")
+def test_analyze_files_end_to_end(tmp_path):
+    import app
+    rng = np.random.default_rng(0)
+    img = (rng.random((200, 240, 3)) * 50).astype(np.uint8)
+    p1 = tmp_path / "a.png"
+    Image.fromarray(img).save(p1)
+    import tifffile
+    p2 = tmp_path / "b.tif"
+    tifffile.imwrite(str(p2), img)
+    rows, gallery, zip_path, summary = app.analyze_files([str(p1), str(p2)], "none (fastest)", 0.5, 0.5, 50, "head", "contains", False)
+    assert len(rows) == 2 and rows[0][0] == "a.png" and len(rows[0]) == 7
+    assert len(gallery) == 2 and os.path.exists(gallery[0][0])
+    assert os.path.exists(zip_path) and summary == ""
+    import zipfile
+    with zipfile.ZipFile(zip_path) as zf:
+        names = zf.namelist()
+    assert "counts.csv" in names and "objects.csv" in names and "results.json" in names
+
+
+def test_build_demo_constructs():
+    pytest.importorskip("gradio")
+    import app
+    demo = app.build_demo()
+    assert demo is not None

tests/test_data.py

@@ -0,0 +1,39 @@
+import numpy as np
+
+from cellquant.annotations import RasterAnnotation
+from cellquant.data import AugConfig, PatchSampler, make_targets
+
+
+def _raster():
+    inst = np.zeros((64, 64), np.int32)
+    inst[10:30, 10:30] = 1
+    inst[30:50, 30:50] = 2  # touches instance 1 at a corner
+    nos = np.zeros((64, 64), np.int32)
+    nos[20:23, 20:23] = 1
+    nos[5:7, 50:52] = 2
+    return RasterAnnotation(inst, ["", "Cell, Nostril, Antibody +", "Cell, Antibody -"], nos,
+                            ["", "Nostril in Nucleus", "Nostril External of Nucleus"])
+
+
+def test_make_targets_layout():
+    T = make_targets(_raster())
+    assert set(np.unique(T["cell3"])) == {0, 1, 2}
+    assert ((T["cell3"] > 0) == (T["cellmask"] > 0)).all()
+    # border ring is 2 px wide: a 20x20 square has 20*20 - 16*16 = 144 border px
+    assert int((T["cell3"][10:30, 10:30] == 2).sum()) == 144
+    assert T["antibody"][15, 15] == 1 and T["antibody"][40, 40] == 0
+    assert T["cellnos"][15, 15] == 1 and T["cellnos"][40, 40] == 0
+    assert T["nos3"][21, 21] == 1 and T["nos3"][5, 50] == 2 and T["nos3"][0, 0] == 0
+
+
+def test_sampler_batch_shapes_and_reproducibility():
+    img = (np.random.default_rng(0).random((64, 64, 3)) * 255).astype(np.uint8)
+    T = make_targets(_raster())
+    cfg = AugConfig(crop=32)
+    a = PatchSampler([img], [T], cfg, seed=3).batch(2)
+    b = PatchSampler([img], [T], cfg, seed=3).batch(2)
+    x, t = a
+    assert x.shape == (2, 3, 32, 32) and x.min() >= 0 and x.max() <= 1
+    assert t["cell3"].shape == (2, 32, 32) and t["cell3"].dtype.is_floating_point is False
+    assert np.allclose(x.numpy(), b[0].numpy())
+    assert all(np.array_equal(t[k].numpy(), b[1][k].numpy()) for k in t)

tests/test_evaluate.py

@@ -0,0 +1,26 @@
+import numpy as np
+
+import evaluate as ev
+
+
+def test_dihedral_transforms_invert_for_2d_and_3d():
+    rng = np.random.default_rng(0)
+    a2 = rng.random((5, 7))
+    a3 = rng.random((3, 5, 7))
+    for k, f in ev.DIHEDRAL:
+        assert np.array_equal(ev.inv_np(ev.fwd_np(a2, k, f), k, f), a2)
+        assert np.array_equal(ev.inv_np(ev.fwd_np(a3, k, f), k, f), a3)
+
+
+def test_dihedral_transforms_are_distinct():
+    a = np.arange(12).reshape(3, 4).astype(float)
+    outs = [ev.fwd_np(a, k, f).tobytes() + bytes(ev.fwd_np(a, k, f).shape) for k, f in ev.DIHEDRAL]
+    assert len(set(outs)) == 8
+
+
+def test_photometric_is_deterministic_and_valid():
+    img = (np.random.default_rng(1).random((16, 16, 3)) * 255).astype(np.uint8)
+    a = ev.photometric(img, 5)
+    b = ev.photometric(img, 5)
+    assert np.array_equal(a, b) and a.dtype == np.uint8 and a.shape == img.shape
+    assert not np.array_equal(ev.photometric(img, 6), a)

tests/test_labels.py

@@ -0,0 +1,16 @@
+from cellquant.labels import ALL_LABELS, CELL_LABELS, NOSTRIL_LABELS, cell_attributes, cell_label, nostril_in_nucleus, nostril_label
+
+
+def test_cell_label_roundtrip():
+    for lab in CELL_LABELS:
+        a, n = cell_attributes(lab)
+        assert cell_label(a, n) == lab
+
+
+def test_nostril_label_roundtrip():
+    for lab in NOSTRIL_LABELS:
+        assert nostril_label(nostril_in_nucleus(lab)) == lab
+
+
+def test_label_sets_disjoint():
+    assert len(ALL_LABELS) == 6 and set(CELL_LABELS).isdisjoint(NOSTRIL_LABELS)

tests/test_metrics.py

@@ -0,0 +1,60 @@
+import numpy as np
+
+from cellquant.metrics import count_errors, evaluate_cells, evaluate_nostrils, match_by_centroid, match_by_iou, micro_average
+
+
+def _two_squares():
+    inst = np.zeros((50, 50), np.int32)
+    inst[5:15, 5:15] = 1
+    inst[30:45, 30:45] = 2
+    return inst
+
+
+def test_perfect_prediction_scores_one():
+    inst = _two_squares()
+    labels = ["", "Cell, Antibody +", "Cell, Antibody -"]
+    r = evaluate_cells(inst, labels, inst.copy(), list(labels))
+    assert r["detection"]["f1"] == 1.0 and r["attribute_accuracy"]["both"] == 1.0
+    assert r["per_class"]["Cell, Antibody +"]["f1"] == 1.0
+
+
+def test_wrong_label_counts_as_fp_and_fn_for_classes_but_detected():
+    inst = _two_squares()
+    gt = ["", "Cell, Antibody +", "Cell, Antibody -"]
+    pred = ["", "Cell, Antibody +", "Cell, Antibody +"]
+    r = evaluate_cells(inst, gt, inst.copy(), pred)
+    assert r["detection"]["tp"] == 2
+    assert r["per_class"]["Cell, Antibody -"]["fn"] == 1 and r["per_class"]["Cell, Antibody +"]["fp"] == 1
+    assert r["attribute_accuracy"]["antibody"] == 0.5
+
+
+def test_shifted_prediction_fails_iou_but_passes_centroid():
+    gt = _two_squares()
+    pred = np.zeros_like(gt)
+    pred[9:19, 9:19] = 1          # IoU with square 1 = 36/164 < 0.5, centroid (14,14) is inside GT square 1
+    pred[30:45, 30:45] = 2
+    assert len(match_by_iou(gt, pred, 0.5)) == 1
+    r = evaluate_cells(gt, ["", "Cell, Antibody +", "Cell, Antibody +"], pred, ["", "Cell, Antibody +", "Cell, Antibody +"])
+    assert r["detection"]["tp"] == 1 and r["detection"]["centroid"]["tp"] == 2
+
+
+def test_nostril_matching_by_distance():
+    gt = np.zeros((40, 40), np.int32)
+    gt[10:13, 10:13] = 1
+    gt[30:33, 30:33] = 2
+    pred = np.zeros_like(gt)
+    pred[12:15, 12:15] = 1       # 2 px away -> match
+    pred[5:8, 30:33] = 2         # 25 px away -> no match
+    m = match_by_centroid(gt, pred, 6.0)
+    assert len(m) == 1 and m[0][:2] == (1, 1)
+    r = evaluate_nostrils(gt, ["", "Nostril in Nucleus", "Nostril External of Nucleus"], pred, ["", "Nostril in Nucleus", "Nostril in Nucleus"])
+    assert r["detection"]["tp"] == 1 and r["detection"]["fp"] == 1 and r["detection"]["fn"] == 1
+    assert r["type_accuracy"] == 1.0
+
+
+def test_count_errors_and_micro_average():
+    ce = count_errors({"Cell, Antibody +": 10}, {"Cell, Antibody +": 8})
+    assert ce["Cell, Antibody +"]["abs_err"] == 2 and abs(ce["Cell, Antibody +"]["rel_err"] - 0.2) < 1e-9
+    per = [{"A": {"tp": 1, "fp": 1, "fn": 0, "gt_count": 1, "pred_count": 2}}, {"A": {"tp": 3, "fp": 0, "fn": 1, "gt_count": 4, "pred_count": 3}}]
+    m = micro_average(per, ["A"])
+    assert m["A"]["tp"] == 4 and m["A"]["fp"] == 1 and m["A"]["fn"] == 1 and abs(m["A"]["f1"] - 0.8) < 1e-9

tests/test_model_infer.py

@@ -0,0 +1,57 @@
+import os
+
+import numpy as np
+import pytest
+import torch
+
+from cellquant.model import CellUNet, N_OUT, load_checkpoint, pad_to_multiple, save_checkpoint
+
+WEIGHTS = os.environ.get("CELLQUANT_WEIGHTS", os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "weights", "cellquant.pt"))
+
+
+def test_pad_to_multiple():
+    x = torch.zeros(1, 3, 70, 100)
+    xp, (ph, pw) = pad_to_multiple(x, 32)
+    assert xp.shape[-2:] == (96, 128) and (ph, pw) == (26, 28)
+    x2, (ph2, pw2) = pad_to_multiple(torch.zeros(1, 3, 64, 64), 32)
+    assert x2.shape[-2:] == (64, 64) and (ph2, pw2) == (0, 0)
+
+
+def test_model_forward_and_checkpoint_roundtrip(tmp_path):
+    m = CellUNet("resnet34", pretrained=False).eval()
+    x = torch.rand(1, 3, 64, 96)
+    with torch.no_grad():
+        y = m(x)
+    assert y.shape == (1, N_OUT, 64, 96)
+    p = tmp_path / "m.pt"
+    save_checkpoint(m, str(p), {"note": "test"})
+    m2, meta = load_checkpoint(str(p))
+    assert meta["note"] == "test" and meta["encoder"] == "resnet34"
+    with torch.no_grad():
+        assert torch.allclose(m2(x), y, atol=1e-5)
+
+
+@pytest.mark.skipif(not os.path.exists(WEIGHTS), reason="trained weights not present")
+def test_predictor_deterministic_and_tiling_consistent():
+    from cellquant.infer import Predictor
+    rng = np.random.default_rng(0)
+    img = (rng.random((300, 420, 3)) * 60).astype(np.uint8)
+    p = Predictor(WEIGHTS, device="cpu", tta=1)
+    a = p.probs(img)
+    b = p.probs(img)
+    assert all(np.array_equal(a[k], b[k]) for k in a)
+    assert a["cell"].shape == (3, 300, 420)
+    # force tiling and compare with the whole-image pass
+    pt = Predictor(WEIGHTS, device="cpu", tta=1, tile=256, overlap=64, max_whole=128)
+    c = pt.probs(img)
+    diff = np.abs(c["cell"] - a["cell"]).mean()
+    assert diff < 0.05, diff
+
+
+@pytest.mark.skipif(not os.path.exists(WEIGHTS), reason="trained weights not present")
+def test_tta_outputs_valid_probabilities():
+    from cellquant.infer import Predictor
+    img = (np.random.default_rng(1).random((128, 160, 3)) * 60).astype(np.uint8)
+    for tta in (4, 8):
+        pr = Predictor(WEIGHTS, device="cpu", tta=tta).probs(img)
+        assert np.allclose(pr["cell"].sum(0), 1, atol=1e-4) and np.allclose(pr["nos"].sum(0), 1, atol=1e-4)

tests/test_postprocess.py

@@ -0,0 +1,93 @@
+import numpy as np
+
+from cellquant.labels import ALL_LABELS
+from cellquant.postprocess import PostConfig, analyze, logits_to_probs, render_overlay, segment_cells
+
+
+def _disc(h, w, cy, cx, r):
+    yy, xx = np.mgrid[:h, :w]
+    return (yy - cy) ** 2 + (xx - cx) ** 2 <= r * r
+
+
+def _probs(h=96, w=96):
+    """Two touching discs; the left one antibody+ with a punctum inside; one external punctum."""
+    d1, d2 = _disc(h, w, 48, 30, 14), _disc(h, w, 48, 56, 14)
+    fg = d1 | d2
+    inner = _disc(h, w, 48, 30, 11) | _disc(h, w, 48, 56, 11)
+    cell = np.zeros((3, h, w), np.float32)
+    cell[1][inner] = 0.9
+    cell[2][fg & ~inner] = 0.9
+    cell[0] = 1 - cell[1] - cell[2]
+    antibody = np.where(d1, 0.95, 0.05).astype(np.float32)
+    cellnos = np.full((h, w), 0.1, np.float32)
+    nos = np.zeros((3, h, w), np.float32)
+    p_in = _disc(h, w, 48, 30, 2)
+    p_ext = _disc(h, w, 10, 80, 2)
+    nos[1][p_in] = 0.9
+    nos[2][p_ext] = 0.9
+    nos[0] = 1 - nos[1] - nos[2]
+    return {"cell": cell, "antibody": antibody, "cellnos": cellnos, "nos": nos}
+
+
+def test_touching_discs_split_into_two_instances():
+    inst = segment_cells(_probs()["cell"], PostConfig())
+    assert inst.max() == 2
+    areas = np.bincount(inst.ravel())[1:]
+    assert all(500 <= a <= 700 for a in areas)  # pi*14^2 ~ 616
+
+
+def test_analyze_labels_and_counts():
+    res = analyze(_probs(), PostConfig())
+    assert len(res.cells) == 2 and len(res.nostrils) == 2
+    labels = sorted(c["label"] for c in res.cells)
+    assert labels == ["Cell, Antibody -", "Cell, Nostril, Antibody +"]
+    assert sorted(n["label"] for n in res.nostrils) == ["Nostril External of Nucleus", "Nostril in Nucleus"]
+    assert sum(res.counts.values()) == 4 and set(res.counts) == set(ALL_LABELS)
+    inside = [n for n in res.nostrils if n["label"] == "Nostril in Nucleus"][0]
+    assert inside["cell_id"] == [c for c in res.cells if c["label"].startswith("Cell, Nostril")][0]["id"]
+
+
+def test_cellnos_rules():
+    p = _probs()
+    head_only = analyze(p, PostConfig(cellnos_rule="head"))
+    assert all(not c["label"].startswith("Cell, Nostril") for c in head_only.cells)
+    contains = analyze(p, PostConfig(cellnos_rule="contains"))
+    assert sum(c["label"].startswith("Cell, Nostril") for c in contains.cells) == 1
+
+
+def test_geometric_nostril_rule_overrides_head():
+    p = _probs()
+    # make the network call the inside punctum "external"; geometric rule should still say inside
+    p["nos"][1], p["nos"][2] = p["nos"][2].copy(), p["nos"][1].copy()
+    head = analyze(p, PostConfig(nostril_rule="head"))
+    geo = analyze(p, PostConfig(nostril_rule="geometric"))
+    assert head.counts["Nostril in Nucleus"] == 1 and geo.counts["Nostril in Nucleus"] == 1
+    # with head rule the punctum inside the disc is now labelled external
+    inside_disc = [n for n in head.nostrils if n["cell_id"] > 0][0]
+    assert inside_disc["label"] == "Nostril External of Nucleus"
+    assert [n for n in geo.nostrils if n["cell_id"] > 0][0]["label"] == "Nostril in Nucleus"
+
+
+def test_min_area_filters_small_instances():
+    p = _probs()
+    assert len(analyze(p, PostConfig(min_cell_area=1000)).cells) == 0
+
+
+def test_logits_to_probs_and_overlay():
+    logits = np.random.default_rng(0).normal(size=(8, 40, 40)).astype(np.float32)
+    pr = logits_to_probs(logits)
+    assert np.allclose(pr["cell"].sum(0), 1, atol=1e-5) and np.allclose(pr["nos"].sum(0), 1, atol=1e-5)
+    assert pr["antibody"].min() >= 0 and pr["antibody"].max() <= 1
+    res = analyze(_probs(), PostConfig())
+    img = np.zeros((96, 96, 3), np.uint8)
+    ov = render_overlay(img, res)
+    assert ov.shape == img.shape and ov.any()
+
+
+def test_empty_image_gives_no_objects():
+    h = w = 64
+    p = {"cell": np.stack([np.ones((h, w)), np.zeros((h, w)), np.zeros((h, w))]).astype(np.float32),
+         "antibody": np.zeros((h, w), np.float32), "cellnos": np.zeros((h, w), np.float32),
+         "nos": np.stack([np.ones((h, w)), np.zeros((h, w)), np.zeros((h, w))]).astype(np.float32)}
+    res = analyze(p, PostConfig())
+    assert res.cells == [] and res.nostrils == [] and sum(res.counts.values()) == 0

tests/test_review_fixes.py

@@ -0,0 +1,157 @@
+"""Regression tests for the defects found in the adversarial review."""
+import os
+import zipfile
+
+import numpy as np
+import pytest
+import tifffile
+from PIL import Image
+
+from cellquant.annotations import discover, load_image, normalized_name, short_keys, to_rgb_uint8
+from cellquant.data import AugConfig, Prefetcher, make_targets
+from cellquant.annotations import RasterAnnotation
+from cellquant.metrics import match_by_iou
+from cellquant.postprocess import PostConfig, _fill_and_filter, analyze
+
+XML = """<?xml version="1.0" encoding="utf-8"?>
+<annotations><version>1.1</version><meta><task><size>1</size></task></meta>
+<image id="0" name="{name}" width="{w}" height="{h}">
+<polyline label="Cell, Antibody +" source="manual" occluded="0" points="10,10;30,10;30,30;10,30;10,10" z_order="0"></polyline>
+</image></annotations>"""
+
+
+def _rgb(h=64, w=64):
+    a = np.zeros((h, w, 3), np.uint8)
+    a[..., 0], a[..., 1], a[..., 2] = 200, 100, 50
+    return a
+
+
+def test_channel_per_page_tif_loads_three_channels(tmp_path):
+    rgb = _rgb()
+    p1 = tmp_path / "ij.tif"
+    tifffile.imwrite(str(p1), np.moveaxis(rgb, -1, 0), imagej=True, metadata={"axes": "CYX"})
+    p2 = tmp_path / "ome.ome.tif"
+    tifffile.imwrite(str(p2), np.moveaxis(rgb, -1, 0), ome=True, metadata={"axes": "CYX"})
+    for p in (p1, p2):
+        a = load_image(str(p))
+        assert a.shape == (64, 64, 3)
+        assert a[1, 1].tolist() == [200, 100, 50], str(p)
+
+
+def test_plain_tif_still_loads_and_large_stack_refused(tmp_path):
+    p = tmp_path / "plain.tif"
+    tifffile.imwrite(str(p), _rgb())
+    assert load_image(str(p))[0, 0].tolist() == [200, 100, 50]
+    stack = tmp_path / "stack.tif"
+    tifffile.imwrite(str(stack), np.zeros((7, 32, 32), np.uint8), imagej=True, metadata={"axes": "ZYX"})
+    with pytest.raises(ValueError):
+        load_image(str(stack))
+
+
+def test_lzw_tif_via_pillow_fallback_or_codecs(tmp_path):
+    p = tmp_path / "lzw.tif"
+    Image.fromarray(_rgb()).save(str(p), compression="tiff_lzw")
+    assert load_image(str(p))[2, 2].tolist() == [200, 100, 50]
+
+
+def test_palette_png_converted_to_rgb(tmp_path):
+    p = tmp_path / "pal.png"
+    Image.fromarray(_rgb()).convert("P", palette=Image.ADAPTIVE, colors=4).save(str(p))
+    a = load_image(str(p))
+    assert a.shape == (64, 64, 3)
+    assert not (np.array_equal(a[..., 0], a[..., 1]) and np.array_equal(a[..., 1], a[..., 2]))
+
+
+def test_16bit_scaling_ignores_single_saturated_pixel():
+    a = np.full((64, 64, 3), 1000, np.uint16)
+    b = a.copy()
+    b[0, 0, :] = 65535
+    ua, ub = to_rgb_uint8(a), to_rgb_uint8(b)
+    assert ua[10, 10, 0] == 255 and ub[10, 10, 0] == 255   # the one hot pixel does not change the gain
+    assert to_rgb_uint8(np.full((8, 8, 3), 0.5, np.float32))[0, 0, 0] in (127, 128)
+
+
+def test_enclosed_instance_survives_and_ids_are_contiguous():
+    inst = np.zeros((40, 40), np.int32)
+    yy, xx = np.mgrid[:40, :40]
+    ring = ((yy - 20) ** 2 + (xx - 20) ** 2 <= 15 ** 2) & ((yy - 20) ** 2 + (xx - 20) ** 2 > 8 ** 2)
+    inner = (yy - 20) ** 2 + (xx - 20) ** 2 <= 6 ** 2
+    inst[ring] = 1
+    inst[inner] = 2
+    out = _fill_and_filter(inst, min_area=5)
+    ids = np.unique(out)
+    assert ids.tolist() == [0, 1, 2]
+    assert out[20, 20] == 2 and out[20, 7] == 1
+    # the 2-px moat between ring and inner disc is background in the input and gets filled into the ring
+    assert out[20, 13] == 1
+    # analyze() must not crash on such a map either
+    h = w = 40
+    p_cell = np.zeros((3, h, w), np.float32)
+    p_cell[1][inner] = 0.9
+    p_cell[1][ring] = 0.9
+    p_cell[2] = 0
+    p_cell[0] = 1 - p_cell[1]
+    probs = {"cell": p_cell, "antibody": np.zeros((h, w), np.float32), "cellnos": np.zeros((h, w), np.float32),
+             "nos": np.stack([np.ones((h, w)), np.zeros((h, w)), np.zeros((h, w))]).astype(np.float32)}
+    res = analyze(probs, PostConfig(min_cell_area=5))
+    assert len(res.cells) == int(res.cell_inst.max())
+
+
+def test_match_by_iou_prefers_number_of_valid_matches():
+    # GT A overlaps pred X with IoU 0.6 and pred Y with IoU 0.45; GT B overlaps X with 0.45.
+    # Summed-IoU assignment would pick (A,Y)+(B,X)=0.9 < (A,X)=0.6 ... make the sums favour the wrong choice:
+    gt = np.zeros((30, 60), np.int32)
+    pred = np.zeros((30, 60), np.int32)
+    gt[0:10, 0:20] = 1            # A: 200 px
+    gt[10:20, 0:20] = 2           # B: 200 px
+    pred[0:10, 0:20] = 1          # X == A exactly (IoU 1.0 with A)
+    pred[5:15, 0:20] = 2          # Y straddles A and B (IoU 100/300 = 0.33 with each)
+    pred[0:10, 0:20] = 1          # X overwrites the top of Y
+    m = match_by_iou(gt, pred, 0.5)
+    assert (1, 1) in [(g, p) for g, p, _ in m]
+
+
+def test_short_keys_disambiguate_wells():
+    names = ["C110 F 35D SC Iba W001 - Focused EDF Document_RGB copy.tif", "C110 F 35D SC Iba W003 - Focused EDF Document_RGB.tif", "F99 M 35D SC Iba W004 - Focused EDF Document_RGB.tif"]
+    assert short_keys(names) == ["C110_W001", "C110_W003", "F99"]
+    assert normalized_name("F114  F 35D SC Iba W002 - Focused EDF Document_RGB copy (1).tif") == "f114 f 35d sc iba w002 - focused edf document_rgb"
+
+
+def test_discover_two_sections_same_animal_and_size_check(tmp_path):
+    for n in ("C110 F 35D SC Iba W001 - RGB.png", "C110 F 35D SC Iba W003 - RGB.png"):
+        Image.fromarray(np.zeros((40, 50, 3), np.uint8)).save(tmp_path / n)
+    for i, n in enumerate(("C110 F 35D SC Iba W001 - RGB copy.tif", "C110 F 35D SC Iba W003 - RGB.tif")):
+        with zipfile.ZipFile(tmp_path / f"ann{i}.zip", "w") as zf:
+            zf.writestr("annotations.xml", XML.format(name=n, w=50, h=40))
+    samples, unann = discover(str(tmp_path), verbose=False)
+    assert [s.key for s in samples] == ["C110_W001", "C110_W003"] and unann == []
+    # a mismatching canvas is refused
+    with zipfile.ZipFile(tmp_path / "ann0.zip", "w") as zf:
+        zf.writestr("annotations.xml", XML.format(name="C110 F 35D SC Iba W001 - RGB.tif", w=500, h=400))
+    with pytest.raises(ValueError):
+        discover(str(tmp_path), verbose=False)
+
+
+def test_discover_refuses_two_different_images_with_same_name(tmp_path):
+    Image.fromarray(np.zeros((40, 50, 3), np.uint8)).save(tmp_path / "K1 a - RGB.png")
+    Image.fromarray(np.ones((40, 50, 3), np.uint8)).save(tmp_path / "K1 a - RGB copy.png")
+    with zipfile.ZipFile(tmp_path / "ann.zip", "w") as zf:
+        zf.writestr("annotations.xml", XML.format(name="K1 a - RGB.png", w=50, h=40))
+    with pytest.raises(ValueError):
+        discover(str(tmp_path), verbose=False)
+
+
+def test_prefetcher_is_deterministic():
+    inst = np.zeros((64, 64), np.int32)
+    inst[10:30, 10:30] = 1
+    R = RasterAnnotation(inst, ["", "Cell, Antibody +"], np.zeros((64, 64), np.int32), [""])
+    img = (np.random.default_rng(0).random((64, 64, 3)) * 255).astype(np.uint8)
+    T = make_targets(R)
+    def stream(seed):
+        pf = Prefetcher([img], [T], AugConfig(crop=32), batch=2, seed=seed, workers=3, depth=6)
+        out = [pf.next()[0].numpy().copy() for _ in range(9)]
+        pf.close()
+        return out
+    a, b = stream(4), stream(4)
+    assert all(np.array_equal(x, y) for x, y in zip(a, b))
+    assert not all(np.array_equal(x, y) for x, y in zip(a, stream(5)))

train.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""Train CellQuant on CVAT-annotated images.
+
+Examples
+--------
+Final model on every annotated image:
+    python train.py --data-dir /path/to/images_and_zips --out weights/cellquant.pt
+Leave-one-image-out fold (held-out image is only used for monitoring):
+    python train.py --data-dir ... --holdout C110 --out runs/fold_C110.pt
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import sys
+import time
+
+import numpy as np
+import torch
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from cellquant.annotations import discover, load_image, rasterize  # noqa: E402
+from cellquant.data import AugConfig, Prefetcher, make_targets  # noqa: E402
+from cellquant.infer import Predictor, pick_device  # noqa: E402
+from cellquant.losses import multitask_loss  # noqa: E402
+from cellquant.metrics import evaluate_cells, evaluate_nostrils  # noqa: E402
+from cellquant.model import CellUNet, save_checkpoint  # noqa: E402
+from cellquant.postprocess import PostConfig, analyze  # noqa: E402
+
+
+def parse_args(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--data-dir", required=True)
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--holdout", default="", help="image key to leave out (e.g. C110); empty = train on all")
+    ap.add_argument("--iters", type=int, default=3000)
+    ap.add_argument("--batch", type=int, default=4)
+    ap.add_argument("--crop", type=int, default=512)
+    ap.add_argument("--lr", type=float, default=3e-4)
+    ap.add_argument("--weight-decay", type=float, default=1e-4)
+    ap.add_argument("--warmup", type=int, default=100)
+    ap.add_argument("--encoder", default="resnet34")
+    ap.add_argument("--no-pretrained", action="store_true")
+    ap.add_argument("--seed", type=int, default=0)
+    ap.add_argument("--device", default="auto")
+    ap.add_argument("--log-every", type=int, default=50)
+    ap.add_argument("--val-every", type=int, default=500)
+    ap.add_argument("--workers", type=int, default=3, help="augmentation threads")
+    return ap.parse_args(argv)
+
+
+def lr_at(it: int, total: int, base: float, warmup: int) -> float:
+    if it < warmup:
+        return base * (it + 1) / warmup
+    t = (it - warmup) / max(1, total - warmup)
+    return base * (0.02 + 0.98 * 0.5 * (1 + math.cos(math.pi * t)))
+
+
+def quick_val(model: CellUNet, img: np.ndarray, R, device) -> dict:
+    pred = Predictor(model, device=str(device), tta=1)
+    res, _ = pred.predict(img, PostConfig())
+    ce = evaluate_cells(R.cell_inst, R.cell_labels, res.cell_inst, res.cell_labels)
+    ne = evaluate_nostrils(R.nostril_inst, R.nostril_labels, res.nostril_inst, res.nostril_labels)
+    return {
+        "cell_det_f1": ce["detection"]["f1"],
+        "cell_attr_both": ce["attribute_accuracy"]["both"],
+        "nos_det_f1": ne["detection"]["f1"],
+        "nos_type_acc": ne["type_accuracy"],
+        "n_pred_cells": ce["n_pred"], "n_gt_cells": ce["n_gt"],
+    }
+
+
+def main(argv=None):
+    a = parse_args(argv)
+    torch.manual_seed(a.seed)
+    np.random.seed(a.seed)
+    device = pick_device(a.device)
+    samples, _ = discover(a.data_dir)
+    if not samples:
+        raise SystemExit("no annotated images found")
+    train = [s for s in samples if s.key != a.holdout]
+    held = [s for s in samples if s.key == a.holdout]
+    if a.holdout and not held:
+        raise SystemExit(f"holdout {a.holdout!r} not among {[s.key for s in samples]}")
+    print(f"device={device} train={[s.key for s in train]} holdout={[s.key for s in held]}")
+    images, targets = [], []
+    for s in train:
+        img = load_image(s.image_path)
+        R = rasterize(s.annotation, img.shape[0], img.shape[1])
+        images.append(img)
+        targets.append(make_targets(R))
+    sampler = Prefetcher(images, targets, AugConfig(crop=a.crop), batch=a.batch, seed=a.seed, workers=a.workers)
+    held_img = held_R = None
+    if held:
+        held_img = load_image(held[0].image_path)
+        held_R = rasterize(held[0].annotation, held_img.shape[0], held_img.shape[1])
+
+    model = CellUNet(a.encoder, pretrained=not a.no_pretrained).to(device)
+    opt = torch.optim.AdamW(model.parameters(), lr=a.lr, weight_decay=a.weight_decay)
+    history = {"train": [], "val": []}
+    t0 = time.time()
+    run = {}
+    for it in range(a.iters):
+        lr = lr_at(it, a.iters, a.lr, a.warmup)
+        for g in opt.param_groups:
+            g["lr"] = lr
+        model.train()
+        x, t = sampler.next()
+        out = model(x.to(device))
+        loss, parts = multitask_loss(out, t)
+        opt.zero_grad(set_to_none=True)
+        loss.backward()
+        torch.nn.utils.clip_grad_norm_(model.parameters(), 5.0)
+        opt.step()
+        for k, v in parts.items():
+            run[k] = run.get(k, 0.0) + v
+        if (it + 1) % a.log_every == 0:
+            avg = {k: v / a.log_every for k, v in run.items()}
+            run = {}
+            avg["iter"] = it + 1
+            avg["lr"] = lr
+            avg["elapsed_s"] = time.time() - t0
+            history["train"].append(avg)
+            print(f"it {it+1:5d} loss {avg['total']:.3f} cell {avg['ce_cell']:.3f}/{avg['dice_cell']:.3f} "
+                  f"nos {avg['ce_nos']:.3f}/{avg['dice_nos']:.3f} ab {avg['bce_ab']:.3f} cn {avg['bce_cn']:.3f} "
+                  f"lr {lr:.2e} {avg['elapsed_s']:.0f}s", flush=True)
+        if held and ((it + 1) % a.val_every == 0 or it + 1 == a.iters):
+            model.eval()
+            v = quick_val(model, held_img, held_R, device)
+            v["iter"] = it + 1
+            history["val"].append(v)
+            print(f"   val[{a.holdout}] cell F1 {v['cell_det_f1']:.3f} attr {v['cell_attr_both']:.3f} "
+                  f"nos F1 {v['nos_det_f1']:.3f} type {v['nos_type_acc']:.3f} (pred {v['n_pred_cells']} / gt {v['n_gt_cells']} cells)", flush=True)
+    sampler.close()
+    model.eval().cpu()
+    os.makedirs(os.path.dirname(os.path.abspath(a.out)), exist_ok=True)
+    save_checkpoint(model, a.out, {
+        "config": vars(a),
+        "train_keys": [s.key for s in train],
+        "holdout": a.holdout,
+        "history": history,
+        "labels": list(__import__("cellquant.labels", fromlist=["ALL_LABELS"]).ALL_LABELS),
+    })
+    with open(os.path.splitext(a.out)[0] + "_history.json", "w") as f:
+        json.dump(history, f, indent=1)
+    print(f"saved {a.out} ({time.time()-t0:.0f}s)")
+
+
+if __name__ == "__main__":
+    main()

weights/cellquant.pt

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

weights/cellquant_history.json

@@ -0,0 +1,725 @@
+{
+ "train": [
+  {
+   "ce_cell": 0.9070329773426056,
+   "dice_cell": 0.8730328452587127,
+   "ce_nos": 1.0830040109157562,
+   "dice_nos": 0.9898272252082825,
+   "bce_ab": 0.524188295006752,
+   "bce_cn": 0.6183760815858841,
+   "total": 4.9954613590240475,
+   "iter": 50,
+   "lr": 0.00015,
+   "elapsed_s": 59.566773891448975
+  },
+  {
+   "ce_cell": 0.7300815117359162,
+   "dice_cell": 0.8212458372116089,
+   "ce_nos": 0.7789127671718598,
+   "dice_nos": 0.9821323096752167,
+   "bce_ab": 0.2914739960432053,
+   "bce_cn": 0.3936499571800232,
+   "total": 3.9974963092803955,
+   "iter": 100,
+   "lr": 0.0003,
+   "elapsed_s": 109.73091292381287
+  },
+  {
+   "ce_cell": 0.5734736859798432,
+   "dice_cell": 0.7798113775253296,
+   "ce_nos": 0.574396123290062,
+   "dice_nos": 0.9748807692527771,
+   "bce_ab": 0.23322827845811844,
+   "bce_cn": 0.33575250566005704,
+   "total": 3.4715427684783937,
+   "iter": 150,
+   "lr": 0.00029979294712266676,
+   "elapsed_s": 160.73545289039612
+  },
+  {
+   "ce_cell": 0.44446682393550874,
+   "dice_cell": 0.7253605389595031,
+   "ce_nos": 0.4329249274730682,
+   "dice_nos": 0.9701189231872559,
+   "bce_ab": 0.20956841707229615,
+   "bce_cn": 0.32494749456644056,
+   "total": 3.107387113571167,
+   "iter": 200,
+   "lr": 0.0002991554114956718,
+   "elapsed_s": 211.49982213974
+  },
+  {
+   "ce_cell": 0.35687846958637237,
+   "dice_cell": 0.6721045792102813,
+   "ce_nos": 0.32840390503406525,
+   "dice_nos": 0.9639902281761169,
+   "bce_ab": 0.17408027544617652,
+   "bce_cn": 0.3147788044810295,
+   "total": 2.810236248970032,
+   "iter": 250,
+   "lr": 0.00029808917686451123,
+   "elapsed_s": 255.0301797389984
+  },
+  {
+   "ce_cell": 0.30268543839454654,
+   "dice_cell": 0.6246984755992889,
+   "ce_nos": 0.24472756624221803,
+   "dice_nos": 0.9488238263130188,
+   "bce_ab": 0.1679477596282959,
+   "bce_cn": 0.264477858543396,
+   "total": 2.5533609533309938,
+   "iter": 300,
+   "lr": 0.00029659737067906796,
+   "elapsed_s": 305.7051999568939
+  },
+  {
+   "ce_cell": 0.2692413151264191,
+   "dice_cell": 0.5903848171234131,
+   "ce_nos": 0.18806805282831193,
+   "dice_nos": 0.9169448506832123,
+   "bce_ab": 0.1362369504570961,
+   "bce_cn": 0.2647552129626274,
+   "total": 2.365631227493286,
+   "iter": 350,
+   "lr": 0.00029468436866391876,
+   "elapsed_s": 356.85323691368103
+  },
+  {
+   "ce_cell": 0.24572547733783723,
+   "dice_cell": 0.5541446590423584,
+   "ce_nos": 0.14375351637601852,
+   "dice_nos": 0.8989665198326111,
+   "bce_ab": 0.1442735657095909,
+   "bce_cn": 0.25428884506225585,
+   "total": 2.241152620315552,
+   "iter": 400,
+   "lr": 0.0002923557819835801,
+   "elapsed_s": 408.5768549442291
+  },
+  {
+   "ce_cell": 0.23625801086425782,
+   "dice_cell": 0.5364066225290298,
+   "ce_nos": 0.11115477636456489,
+   "dice_nos": 0.87745032787323,
+   "bce_ab": 0.1183611673116684,
+   "bce_cn": 0.22456467717885972,
+   "total": 2.1041955590248107,
+   "iter": 450,
+   "lr": 0.00028961844078399557,
+   "elapsed_s": 459.0741550922394
+  },
+  {
+   "ce_cell": 0.21822448045015336,
+   "dice_cell": 0.5127934575080871,
+   "ce_nos": 0.0872543377429247,
+   "dice_nos": 0.8334435498714448,
+   "bce_ab": 0.1045101822167635,
+   "bce_cn": 0.2290149673819542,
+   "total": 1.9852409744262696,
+   "iter": 500,
+   "lr": 0.0002864803741585413,
+   "elapsed_s": 509.7258110046387
+  },
+  {
+   "ce_cell": 0.21543064922094346,
+   "dice_cell": 0.49275926291942596,
+   "ce_nos": 0.07010223433375358,
+   "dice_nos": 0.795907906293869,
+   "bce_ab": 0.10423918575048446,
+   "bce_cn": 0.21024613380432128,
+   "total": 1.8886853814125062,
+   "iter": 550,
+   "lr": 0.0002829507865973116,
+   "elapsed_s": 560.3340859413147
+  },
+  {
+   "ce_cell": 0.21174423784017563,
+   "dice_cell": 0.4891924291849136,
+   "ce_nos": 0.06100128136575222,
+   "dice_nos": 0.7548426115512847,
+   "bce_ab": 0.09695948652923107,
+   "bce_cn": 0.20541400745511054,
+   "total": 1.8191540384292602,
+   "iter": 600,
+   "lr": 0.0002790400309887635,
+   "elapsed_s": 610.7946240901947
+  },
+  {
+   "ce_cell": 0.20390785247087478,
+   "dice_cell": 0.4746441453695297,
+   "ce_nos": 0.04720834020525217,
+   "dice_nos": 0.709533805847168,
+   "bce_ab": 0.09941868580877782,
+   "bce_cn": 0.19302350237965585,
+   "total": 1.727736325263977,
+   "iter": 650,
+   "lr": 0.0002747595782529114,
+   "elapsed_s": 660.7677178382874
+  },
+  {
+   "ce_cell": 0.2039007693529129,
+   "dice_cell": 0.46679477393627167,
+   "ce_nos": 0.048075792603194716,
+   "dice_nos": 0.6227267402410507,
+   "bce_ab": 0.08658930584788323,
+   "bce_cn": 0.18947327509522438,
+   "total": 1.617560646533966,
+   "iter": 700,
+   "lr": 0.0002701219836951418,
+   "elapsed_s": 711.0392649173737
+  },
+  {
+   "ce_cell": 0.200768101811409,
+   "dice_cell": 0.45868332326412203,
+   "ce_nos": 0.03979761004447937,
+   "dice_nos": 0.5989265680313111,
+   "bce_ab": 0.07302961058914662,
+   "bce_cn": 0.1712094095349312,
+   "total": 1.5424146223068238,
+   "iter": 750,
+   "lr": 0.0002651408501793399,
+   "elapsed_s": 760.5930259227753
+  },
+  {
+   "ce_cell": 0.19177152156829835,
+   "dice_cell": 0.4472357839345932,
+   "ce_nos": 0.03094205627217889,
+   "dice_nos": 0.5603820198774337,
+   "bce_ab": 0.08034474328160286,
+   "bce_cn": 0.14997318997979164,
+   "total": 1.4606493067741395,
+   "iter": 800,
+   "lr": 0.0002598307882283455,
+   "elapsed_s": 810.9303019046783
+  },
+  {
+   "ce_cell": 0.19938127607107162,
+   "dice_cell": 0.44567417323589326,
+   "ce_nos": 0.04125866884365678,
+   "dice_nos": 0.4803364199399948,
+   "bce_ab": 0.07717311266809702,
+   "bce_cn": 0.1591106753051281,
+   "total": 1.4029343223571777,
+   "iter": 850,
+   "lr": 0.00025420737316877263,
+   "elapsed_s": 857.9806337356567
+  },
+  {
+   "ce_cell": 0.1933874309062958,
+   "dice_cell": 0.4387037259340286,
+   "ce_nos": 0.036275244057178496,
+   "dice_nos": 0.48662609457969663,
+   "bce_ab": 0.06898861289024354,
+   "bce_cn": 0.15267845779657363,
+   "total": 1.3766595673561097,
+   "iter": 900,
+   "lr": 0.00024828709944589296,
+   "elapsed_s": 908.7008759975433
+  },
+  {
+   "ce_cell": 0.19506525486707688,
+   "dice_cell": 0.4412110126018524,
+   "ce_nos": 0.035951650235801935,
+   "dice_nos": 0.43454607129096984,
+   "bce_ab": 0.06932192835956812,
+   "bce_cn": 0.14733665704727172,
+   "total": 1.32343257188797,
+   "iter": 950,
+   "lr": 0.00024208733224258537,
+   "elapsed_s": 959.4800848960876
+  },
+  {
+   "ce_cell": 0.1945480227470398,
+   "dice_cell": 0.43224972307682036,
+   "ce_nos": 0.0335944464802742,
+   "dice_nos": 0.40378140449523925,
+   "bce_ab": 0.06522910814732313,
+   "bce_cn": 0.13741043150424959,
+   "total": 1.2668131160736085,
+   "iter": 1000,
+   "lr": 0.0002356262565442632,
+   "elapsed_s": 1009.7932658195496
+  },
+  {
+   "ce_cell": 0.18734178960323333,
+   "dice_cell": 0.4267615270614624,
+   "ce_nos": 0.036363077107816937,
+   "dice_nos": 0.4053969383239746,
+   "bce_ab": 0.0643582896143198,
+   "bce_cn": 0.12727220386266708,
+   "total": 1.2474938321113587,
+   "iter": 1050,
+   "lr": 0.0002289228237991784,
+   "elapsed_s": 1059.9658198356628
+  },
+  {
+   "ce_cell": 0.18910773277282714,
+   "dice_cell": 0.42362256467342374,
+   "ce_nos": 0.0346462229359895,
+   "dice_nos": 0.3729756760597229,
+   "bce_ab": 0.06174593850970268,
+   "bce_cn": 0.13085844799876212,
+   "total": 1.2129565787315368,
+   "iter": 1100,
+   "lr": 0.0002219966963305587,
+   "elapsed_s": 1110.0916857719421
+  },
+  {
+   "ce_cell": 0.1822684535384178,
+   "dice_cell": 0.4143069595098495,
+   "ce_nos": 0.03322938298806548,
+   "dice_nos": 0.3389162081480026,
+   "bce_ab": 0.05988596722483635,
+   "bce_cn": 0.11884681917726994,
+   "total": 1.1474537920951844,
+   "iter": 1150,
+   "lr": 0.00021486818966362585,
+   "elapsed_s": 1160.7585599422455
+  },
+  {
+   "ce_cell": 0.18991790741682052,
+   "dice_cell": 0.41873910784721374,
+   "ce_nos": 0.036337544079869985,
+   "dice_nos": 0.34970403611660006,
+   "bce_ab": 0.05970212183892727,
+   "bce_cn": 0.1334019273519516,
+   "total": 1.1878026413917542,
+   "iter": 1200,
+   "lr": 0.00020755821293665946,
+   "elapsed_s": 1211.4072179794312
+  },
+  {
+   "ce_cell": 0.17697676301002502,
+   "dice_cell": 0.40928772032260896,
+   "ce_nos": 0.03304771558381617,
+   "dice_nos": 0.3399574244022369,
+   "bce_ab": 0.04348419822752476,
+   "bce_cn": 0.1121597220748663,
+   "total": 1.1149135494232179,
+   "iter": 1250,
+   "lr": 0.00020008820757089248,
+   "elapsed_s": 1262.1290378570557
+  },
+  {
+   "ce_cell": 0.17598221957683563,
+   "dice_cell": 0.40642625391483306,
+   "ce_nos": 0.033407045025378466,
+   "dice_nos": 0.310367751121521,
+   "bce_ab": 0.0478444230183959,
+   "bce_cn": 0.09985558047890664,
+   "total": 1.073883285522461,
+   "iter": 1300,
+   "lr": 0.0001924800843791277,
+   "elapsed_s": 1311.735403060913
+  },
+  {
+   "ce_cell": 0.18522560983896255,
+   "dice_cell": 0.403508597612381,
+   "ce_nos": 0.036090935450047254,
+   "dice_nos": 0.3127438998222351,
+   "bce_ab": 0.04713532615453005,
+   "bce_cn": 0.11126945935189723,
+   "total": 1.0959738206863403,
+   "iter": 1350,
+   "lr": 0.00018475615929754922,
+   "elapsed_s": 1362.2759177684784
+  },
+  {
+   "ce_cell": 0.18232185065746306,
+   "dice_cell": 0.40336430847644805,
+   "ce_nos": 0.0384017390338704,
+   "dice_nos": 0.30273705661296846,
+   "bce_ab": 0.04570051861926913,
+   "bce_cn": 0.11299202486872673,
+   "total": 1.0855175077915191,
+   "iter": 1400,
+   "lr": 0.0001769390879292361,
+   "elapsed_s": 1412.6486489772797
+  },
+  {
+   "ce_cell": 0.18443019971251487,
+   "dice_cell": 0.41006422102451323,
+   "ce_nos": 0.038777465261518956,
+   "dice_nos": 0.293556307554245,
+   "bce_ab": 0.040375117510557175,
+   "bce_cn": 0.0971392347663641,
+   "total": 1.0643425357341767,
+   "iter": 1450,
+   "lr": 0.00016905179909137546,
+   "elapsed_s": 1462.6795949935913
+  },
+  {
+   "ce_cell": 0.17869871109724045,
+   "dice_cell": 0.40553332567214967,
+   "ce_nos": 0.03795233623124659,
+   "dice_nos": 0.2916260594129562,
+   "bce_ab": 0.04099308693781495,
+   "bce_cn": 0.0865385101735592,
+   "total": 1.0413420403003693,
+   "iter": 1500,
+   "lr": 0.00016111742756109098,
+   "elapsed_s": 1512.4294548034668
+  },
+  {
+   "ce_cell": 0.1764592757821083,
+   "dice_cell": 0.3958728986978531,
+   "ce_nos": 0.035169387739151715,
+   "dice_nos": 0.27471464276313784,
+   "bce_ab": 0.035233155209571126,
+   "bce_cn": 0.08008314736187458,
+   "total": 0.9975325107574463,
+   "iter": 1550,
+   "lr": 0.00015315924621715527,
+   "elapsed_s": 1562.1074118614197
+  },
+  {
+   "ce_cell": 0.17475848585367204,
+   "dice_cell": 0.3929943698644638,
+   "ce_nos": 0.03353961421176791,
+   "dice_nos": 0.3009433788061142,
+   "bce_ab": 0.03854949928820133,
+   "bce_cn": 0.08339719414710998,
+   "total": 1.0241825413703918,
+   "iter": 1600,
+   "lr": 0.00014520059777662684,
+   "elapsed_s": 1612.9562838077545
+  },
+  {
+   "ce_cell": 0.18072757810354234,
+   "dice_cell": 0.39913213849067686,
+   "ce_nos": 0.039328129449859264,
+   "dice_nos": 0.2857843828201294,
+   "bce_ab": 0.03886710917577148,
+   "bce_cn": 0.09502572849392892,
+   "total": 1.0388650584220886,
+   "iter": 1650,
+   "lr": 0.00013726482632663912,
+   "elapsed_s": 1663.1288919448853
+  },
+  {
+   "ce_cell": 0.1759936460852623,
+   "dice_cell": 0.39650719165802,
+   "ce_nos": 0.032182310023345054,
+   "dice_nos": 0.2933516526222229,
+   "bce_ab": 0.03653882872313261,
+   "bce_cn": 0.08788134880363942,
+   "total": 1.0224549758434296,
+   "iter": 1700,
+   "lr": 0.00012937520885217038,
+   "elapsed_s": 1712.6260061264038
+  },
+  {
+   "ce_cell": 0.17498762905597687,
+   "dice_cell": 0.38849363803863524,
+   "ce_nos": 0.03151271438226104,
+   "dice_nos": 0.27745749831199645,
+   "bce_ab": 0.038630726784467696,
+   "bce_cn": 0.08467736341059208,
+   "total": 0.995759572982788,
+   "iter": 1750,
+   "lr": 0.0001215548869606366,
+   "elapsed_s": 1763.162414073944
+  },
+  {
+   "ce_cell": 0.16943098440766335,
+   "dice_cell": 0.38974578082561495,
+   "ce_nos": 0.030594841404818,
+   "dice_nos": 0.2775198197364807,
+   "bce_ab": 0.03063900684937835,
+   "bce_cn": 0.07809612043201923,
+   "total": 0.9760265576839448,
+   "iter": 1800,
+   "lr": 0.00011382679900356957,
+   "elapsed_s": 1812.9093608856201
+  },
+  {
+   "ce_cell": 0.17392412394285203,
+   "dice_cell": 0.39087122797966,
+   "ce_nos": 0.03287358325906098,
+   "dice_nos": 0.27309031009674073,
+   "bce_ab": 0.03879237989895046,
+   "bce_cn": 0.07375255063176155,
+   "total": 0.9833041846752166,
+   "iter": 1850,
+   "lr": 0.0001062136127944796,
+   "elapsed_s": 1862.8471250534058
+  },
+  {
+   "ce_cell": 0.1721265098452568,
+   "dice_cell": 0.3918482345342636,
+   "ce_nos": 0.03052111998666078,
+   "dice_nos": 0.26571854174137116,
+   "bce_ab": 0.028863372541964055,
+   "bce_cn": 0.07009109571576118,
+   "total": 0.9591688740253449,
+   "iter": 1900,
+   "lr": 9.873765912025276e-05,
+   "elapsed_s": 1913.0803048610687
+  },
+  {
+   "ce_cell": 0.17321533888578414,
+   "dice_cell": 0.3879319250583649,
+   "ce_nos": 0.03197065497748554,
+   "dice_nos": 0.2754987716674805,
+   "bce_ab": 0.03000295827165246,
+   "bce_cn": 0.0681322829797864,
+   "total": 0.966751925945282,
+   "iter": 1950,
+   "lr": 9.142086624110557e-05,
+   "elapsed_s": 1962.4520688056946
+  },
+  {
+   "ce_cell": 0.16933307886123658,
+   "dice_cell": 0.3823584771156311,
+   "ce_nos": 0.03379744639620185,
+   "dice_nos": 0.2684609520435333,
+   "bce_ab": 0.03405721362680197,
+   "bce_cn": 0.07046777069568634,
+   "total": 0.9584749519824982,
+   "iter": 2000,
+   "lr": 8.428469557121958e-05,
+   "elapsed_s": 2011.636960029602
+  },
+  {
+   "ce_cell": 0.17340840995311738,
+   "dice_cell": 0.3878352814912796,
+   "ce_nos": 0.03318483327515423,
+   "dice_nos": 0.2580646830797195,
+   "bce_ab": 0.029467624574899674,
+   "bce_cn": 0.07082617726176978,
+   "total": 0.9527869963645935,
+   "iter": 2050,
+   "lr": 7.735007872871564e-05,
+   "elapsed_s": 2061.974331855774
+  },
+  {
+   "ce_cell": 0.17320298582315444,
+   "dice_cell": 0.3853736054897308,
+   "ce_nos": 0.028748751198872925,
+   "dice_nos": 0.26544315218925474,
+   "bce_ab": 0.033497555926442144,
+   "bce_cn": 0.06046421557664871,
+   "total": 0.9467302620410919,
+   "iter": 2100,
+   "lr": 7.063735613961179e-05,
+   "elapsed_s": 2112.548271894455
+  },
+  {
+   "ce_cell": 0.1658191041648388,
+   "dice_cell": 0.3796718597412109,
+   "ce_nos": 0.03187917632050812,
+   "dice_nos": 0.26365615785121915,
+   "bce_ab": 0.030561734307557344,
+   "bce_cn": 0.05981527805328369,
+   "total": 0.9314033150672912,
+   "iter": 2150,
+   "lr": 6.416621737584896e-05,
+   "elapsed_s": 2162.667312860489
+  },
+  {
+   "ce_cell": 0.1701272311806679,
+   "dice_cell": 0.37863297820091246,
+   "ce_nos": 0.027262243572622538,
+   "dice_nos": 0.26668123960494994,
+   "bce_ab": 0.04351606283336878,
+   "bce_cn": 0.06579859033226967,
+   "total": 0.9520183408260345,
+   "iter": 2200,
+   "lr": 5.795564340238374e-05,
+   "elapsed_s": 2213.4271240234375
+  },
+  {
+   "ce_cell": 0.1703978794813156,
+   "dice_cell": 0.38433976292610167,
+   "ce_nos": 0.03619127416983247,
+   "dice_nos": 0.24586948692798616,
+   "bce_ab": 0.02381640898063779,
+   "bce_cn": 0.06208158168941736,
+   "total": 0.922696396112442,
+   "iter": 2250,
+   "lr": 5.202385090274833e-05,
+   "elapsed_s": 2263.827299118042
+  },
+  {
+   "ce_cell": 0.16755644142627715,
+   "dice_cell": 0.3778986144065857,
+   "ce_nos": 0.03260435258969665,
+   "dice_nos": 0.25375066459178924,
+   "bce_ab": 0.029958658767864108,
+   "bce_cn": 0.05888926636427641,
+   "total": 0.9206579995155334,
+   "iter": 2300,
+   "lr": 4.638823884637875e-05,
+   "elapsed_s": 2313.582683801651
+  },
+  {
+   "ce_cell": 0.1692182320356369,
+   "dice_cell": 0.3797942841053009,
+   "ce_nos": 0.031096484493464232,
+   "dice_nos": 0.25585519909858706,
+   "bce_ab": 0.025209803096950055,
+   "bce_cn": 0.06410345062613487,
+   "total": 0.925277452468872,
+   "iter": 2350,
+   "lr": 4.106533745443955e-05,
+   "elapsed_s": 2366.780472755432
+  },
+  {
+   "ce_cell": 0.1647430169582367,
+   "dice_cell": 0.37565741121768953,
+   "ce_nos": 0.029058436192572118,
+   "dice_nos": 0.2536770069599152,
+   "bce_ab": 0.026647686092182994,
+   "bce_cn": 0.05636850781738758,
+   "total": 0.9061520624160767,
+   "iter": 2400,
+   "lr": 3.607075971383718e-05,
+   "elapsed_s": 2420.7595388889313
+  },
+  {
+   "ce_cell": 0.1587481266260147,
+   "dice_cell": 0.37386213421821596,
+   "ce_nos": 0.027811604756861924,
+   "dice_nos": 0.2525290942192078,
+   "bce_ab": 0.027055934872478246,
+   "bce_cn": 0.05388368744403124,
+   "total": 0.8938905835151673,
+   "iter": 2450,
+   "lr": 3.1419155581639394e-05,
+   "elapsed_s": 2472.9100120067596
+  },
+  {
+   "ce_cell": 0.16981444805860518,
+   "dice_cell": 0.3800900149345398,
+   "ce_nos": 0.02935561618767679,
+   "dice_nos": 0.2700779044628143,
+   "bce_ab": 0.026528375521302223,
+   "bce_cn": 0.05692515041679144,
+   "total": 0.932791496515274,
+   "iter": 2500,
+   "lr": 2.7124169014226923e-05,
+   "elapsed_s": 2525.758083820343
+  },
+  {
+   "ce_cell": 0.16598297476768495,
+   "dice_cell": 0.37718391716480254,
+   "ce_nos": 0.030217354064807297,
+   "dice_nos": 0.2526162987947464,
+   "bce_ab": 0.027398303812369705,
+   "bce_cn": 0.05613136574625969,
+   "total": 0.9095302104949952,
+   "iter": 2550,
+   "lr": 2.319839794721846e-05,
+   "elapsed_s": 2578.604254961014
+  },
+  {
+   "ce_cell": 0.16501545295119285,
+   "dice_cell": 0.37883709609508515,
+   "ce_nos": 0.029584614327177405,
+   "dice_nos": 0.24774192690849303,
+   "bce_ab": 0.022402014611288906,
+   "bce_cn": 0.057471454478800296,
+   "total": 0.9010525631904602,
+   "iter": 2600,
+   "lr": 1.9653357343555055e-05,
+   "elapsed_s": 2630.874783039093
+  },
+  {
+   "ce_cell": 0.16610188841819762,
+   "dice_cell": 0.3750225841999054,
+   "ce_nos": 0.03136977587360889,
+   "dice_nos": 0.24075563967227936,
+   "bce_ab": 0.023018423346802593,
+   "bce_cn": 0.054641781151294706,
+   "total": 0.8909100878238678,
+   "iter": 2650,
+   "lr": 1.6499445418129828e-05,
+   "elapsed_s": 2683.160297870636
+  },
+  {
+   "ce_cell": 0.16699187859892844,
+   "dice_cell": 0.37973670542240145,
+   "ce_nos": 0.031007613111287354,
+   "dice_nos": 0.25119431257247926,
+   "bce_ab": 0.02384809180162847,
+   "bce_cn": 0.05100016433745622,
+   "total": 0.9037787771224975,
+   "iter": 2700,
+   "lr": 1.3745913138031944e-05,
+   "elapsed_s": 2734.7909269332886
+  },
+  {
+   "ce_cell": 0.1654239809513092,
+   "dice_cell": 0.373527038693428,
+   "ce_nos": 0.026881940369494258,
+   "dice_nos": 0.25084660708904266,
+   "bce_ab": 0.03065326821990311,
+   "bce_cn": 0.05875104777514935,
+   "total": 0.9060838842391967,
+   "iter": 2750,
+   "lr": 1.1400837087866401e-05,
+   "elapsed_s": 2785.7226259708405
+  },
+  {
+   "ce_cell": 0.164136121571064,
+   "dice_cell": 0.37796851992607117,
+   "ce_nos": 0.03165758168324828,
+   "dice_nos": 0.2464037835597992,
+   "bce_ab": 0.02406527513638139,
+   "bce_cn": 0.05659090880304575,
+   "total": 0.9008221983909607,
+   "iter": 2800,
+   "lr": 9.471095779739621e-06,
+   "elapsed_s": 2837.11731505394
+  },
+  {
+   "ce_cell": 0.16365474253892898,
+   "dice_cell": 0.3711686569452286,
+   "ce_nos": 0.03501185901463032,
+   "dice_nos": 0.26115318775177004,
+   "bce_ab": 0.020862439805641772,
+   "bce_cn": 0.06006271541118622,
+   "total": 0.9119135963916779,
+   "iter": 2850,
+   "lr": 7.96234947739845e-06,
+   "elapsed_s": 2888.5047039985657
+  },
+  {
+   "ce_cell": 0.1650400999188423,
+   "dice_cell": 0.37380745112895963,
+   "ce_nos": 0.027719355495646594,
+   "dice_nos": 0.24648674428462983,
+   "bce_ab": 0.030483954632654787,
+   "bce_cn": 0.05518790137022734,
+   "total": 0.898725507259369,
+   "iter": 2900,
+   "lr": 6.8790235937012375e-06,
+   "elapsed_s": 2939.583750963211
+  },
+  {
+   "ce_cell": 0.1652056121826172,
+   "dice_cell": 0.37707124650478363,
+   "ce_nos": 0.027215274684131145,
+   "dice_nos": 0.24094445288181304,
+   "bce_ab": 0.02379746310412884,
+   "bce_cn": 0.05311750005930662,
+   "total": 0.8873515450954437,
+   "iter": 2950,
+   "lr": 6.224295710119515e-06,
+   "elapsed_s": 2990.7978727817535
+  },
+  {
+   "ce_cell": 0.15959388136863709,
+   "dice_cell": 0.3714492267370224,
+   "ce_nos": 0.030986426128074528,
+   "dice_nos": 0.2347310698032379,
+   "bce_ab": 0.018123713415116073,
+   "bce_cn": 0.05247432488948107,
+   "total": 0.8673586428165436,
+   "iter": 3000,
+   "lr": 6.000086256343946e-06,
+   "elapsed_s": 3042.6654930114746
+  }
+ ],
+ "val": []
+}