pathseed 0.1.0__tar.gz

pathseed-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade pip build pytest
+      - run: python -m build
+      - run: python -m pip install dist/*.whl && python -m pytest -q tests
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pathseed-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+!src/pathseed/ui/dist/
+ui-src/node_modules/
+ui-src/dist/
+runs/
+*.pt
+*.ckpt
+.DS_Store

pathseed-0.1.0/CITATION.cff

@@ -0,0 +1,8 @@
+cff-version: 1.2.0
+title: "pathseed: from an unlabeled whole-slide image to a detector for a rare target"
+message: "If you use this software, please cite the accompanying paper (reference to come)."
+type: software
+version: 0.1.0
+date-released: 2026-09-08
+license: MIT
+repository-code: https://github.com/<org>/pathseed

pathseed-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the pathseed authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pathseed-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: pathseed
+Version: 0.1.0
+Summary: From an unlabeled whole-slide image to a detector for a rare target: seed with point prompts, propose, review, retrain.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=9.0
+Requires-Dist: scikit-image>=0.21
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == 'plot'
+Provides-Extra: sam3
+Requires-Dist: torch>=2.1; extra == 'sam3'
+Requires-Dist: transformers>=5.12; extra == 'sam3'
+Provides-Extra: torch
+Requires-Dist: timm>=1.0; extra == 'torch'
+Requires-Dist: torch>=2.1; extra == 'torch'
+Provides-Extra: wsi
+Requires-Dist: openslide-bin; extra == 'wsi'
+Requires-Dist: openslide-python>=1.3; extra == 'wsi'
+Description-Content-Type: text/markdown
+
+# pathseed
+
+From an unlabeled whole-slide image to a detector for a rare target, with the
+expert's time spent where it counts.
+
+```
+seed            expert points at ~30 instances; SAM 3 turns each point set into a mask
+train           a small proposal network learns from those tiles (+ ~30 empty tiles)
+sweep           the network scans the unlabeled tissue and ranks what fires
+review          expert accepts / rejects the top proposals (2 s each); rejects = hard negatives
+retrain         … repeat once or twice, then sweep every slide
+```
+
+Everything is parameterised by a `TargetSpec`: which mask channels the target
+has, its size window, an optional relation between channels ("the ring must
+enclose a nucleus"), and how a proposal is matched to ground truth (mask overlap
+or point distance). The same code runs for a tau halo (two masks, relation) and
+a mitotic figure (one mask, point ground truth).
+
+The package also contains the **oracle simulation** that produces the
+label-efficiency curves: on a benchmark that already has ground truth, the
+oracle plays the pathologist, so the loop can be run from many seeds with a
+measured annotator budget (points placed + decisions made) against held-out
+slide F1, next to a random-tile baseline and the full-data upper bound.
+
+## Layout
+
+```
+src/pathseed/
+  target.py     TargetSpec (+ presets: tau, mitosis)
+  manifest.py   dataset layout (images/ + one mask dir per channel + manifest.json), Label
+  propose.py    probability maps -> proposals (components, size window, relation rule)
+  metrics.py    object / tile detection F1, per-fold result record
+  folds.py      slide-held-out folds
+  budget.py     annotator cost accounting
+  oracle.py     simulated reviewer from ground truth
+  simulate.py   the label-efficiency experiment (+ random baseline, upper bound)
+  loop.py       the real loop: state dir, train / propose / ingest_review
+  seed.py       point prompts -> masks (SAM 3 adapter; threshold fallback)
+  sweep.py      whole-slide / large-image sweep -> pool dataset
+  review.py     browser UI server (review grid + focus panel + seeding canvas), stdlib only
+  app.py        start()/stop() for Colab or local use (server + cached SAM 3)
+  project.py    SQLite bank of slides, tiles, prompts, decisions (what the UI writes)
+  wsi.py        whole-slide access (openslide) for the seeding viewer
+  roi_eval.py   MIDOG-style region evaluation: sweep, distance NMS, 7.5 um matching, F1 / AP / FROC
+  ui/dist/      the built React UI (source in ui-src/; `npm install && npm run build` there)
+  models/       prototype (numpy floor), unet (pluggable encoder + U-Net decoder, K channels), encoders.py,
+                retinanet (torchvision reference detector under the same proposal contract)
+  plot.py       F1-vs-budget figure
+  cli.py
+tests/             synthetic benchmark; runs without torch
+experiments/midog/ the paper experiments on MIDOG++ (see below)
+```
+
+## Experiments (MIDOG++)
+
+`experiments/midog/` holds everything behind the MIDOG++ numbers in `experiments/midog/RESULTS.md`:
+`build_midog.py` (ROIs -> tiles with point ground truth), `paper_midog.py` (the label-efficiency loop with the
+ground truth as reviewer, one JSON row per round), `full_bench.py` (full-training-set ceilings),
+`roi_eval.py` (region-level scoring), `calibrate.py` (validation-selected threshold),
+`crosscheck_eval.py` (the same detections scored with the official MIDOG 2025 evaluation code),
+`midogpp_split_ammeling.json` (the patient-level split of Ammeling et al. 2026), and the Colab runners
+`colab_loop_v3.sh` / `colab_ceiling2.sh`. The seed tiles, detections and models are on Zenodo (link to come).
+
+## UI
+
+`pathseed.review.serve()` serves a React app (Vite, Tailwind, framer-motion; source in
+`ui-src/`, prebuilt into `src/pathseed/ui/dist/`). Review mode: card grid with masks,
+focus panel with zoom and per-proposal measurements, keyboard `a`/`r`/`u`, arrows,
+`m` toggles masks (per-card ◐ toggles one tile), `f` hides the panel. Seed mode: tile
+list with filter, click = positive point, shift-click = negative, `1`/`2` switch channel,
+`z` undo, `s` save, `e` save as empty. Rebuild after editing `ui-src/`:
+`cd ui-src && npm install && npm run build`.
+
+## Install
+
+```
+pip install -e .              # core: numpy, scipy, pillow, scikit-image
+pip install -e '.[torch]'     # proposal network (torch, timm)
+pip install -e '.[sam3]'      # SAM 3 seeding (transformers)
+pip install -e '.[wsi,plot,dev]'
+pytest
+```
+
+## Encoders
+
+The network is a U-Net decoder over a pluggable encoder; output channels come
+from the target (one by default). Multi-scale timm models work by name
+(`mobilenetv4_conv_small`, `fastvit_t8`, `tiny_vit_5m_224`, `convnext_tiny`,
+`resnet18`, ...); plain ViTs get a ViTDet-style feature pyramid
+(`vit:vit_small_patch16_224`, `vit:samvit_base_patch16`, `vit:hf-hub:MahmoodLab/UNI`).
+`freeze_encoder=True` trains only the decoder. `pathseed encoders <spec>...` prints
+what each one hands the decoder. Pathology foundation models have short names
+(`uni`, `uni2h`, `hoptimus0`, `hoptimus1`, `virchow2`); they are gated on the
+Hugging Face Hub: accept the terms on the model page, then log in once
+(`huggingface-cli login`, or `huggingface_hub.login(token)`; on Colab keep the
+token in Secrets and call login from a cell). Each carries its own input
+normalisation.
+
+## Simulation on the tau benchmark
+
+```
+pathseed folds    --dataset macrophage_100k_curated --out folds.json --tau-fixed
+pathseed simulate --dataset macrophage_100k_curated --target tau --folds folds.json --test-fold 0 \
+                  --model unet --seed-pos 30 --seed-neg 30 --rounds 2 --review-cap 300 \
+                  --seeds 0,1,2 --random --full --out runs/ --opt epochs=20
+pathseed summarise --runs runs/ --csv runs.csv --plot curve.png
+```
+
+## Start the app (Colab or local)
+
+```python
+from pathseed.app import start, stop
+start("/content/dataset", state="/content/state",
+      slides_dir="/content/drive/MyDrive/svs", target="tau",
+      sam3_cache="/content/drive/MyDrive/sam3/checkpoint")   # prints the URL (Colab proxy or localhost)
+```
+
+`start()` loads SAM 3 once and reuses it, replaces a previous server on the same
+port, and picks a free port if that one is taken. `stop()` shuts everything down.
+`seg="threshold"` runs without a model (dry run), `seg=None` disables seeding.
+
+## The real loop
+
+```python
+from pathseed import target
+from pathseed.loop import Loop
+from pathseed.review import serve
+from pathseed.seed import Sam3PointSegmenter
+
+tgt = target.tau()
+loop = Loop.init("state", "dataset", tgt)
+serve("dataset", None, tgt, segmenter=Sam3PointSegmenter(), port=8765)   # seed tab: place points, save
+# ... then add the saved seed labels:
+import json; from pathseed.manifest import Label
+loop.add_labels([Label.from_dict(d) for d in json.load(open("dataset/seed_labels.json"))], seed_instances=30, seed_negatives=30)
+loop.train(0, model="unet", epochs=20)                                   # encoder="fastvit_t8", freeze_encoder=True ...
+# sweep slides into the same dataset dir (pathseed sweep ...), then
+loop.propose(0, cap=300)
+serve("dataset", "state/round_0", tgt, port=8765)                        # review tab
+loop.ingest_review(0, accepted_source="files")
+loop.train(1, model="unet", epochs=20)
+```

pathseed-0.1.0/README.md

@@ -0,0 +1,143 @@
+# pathseed
+
+From an unlabeled whole-slide image to a detector for a rare target, with the
+expert's time spent where it counts.
+
+```
+seed            expert points at ~30 instances; SAM 3 turns each point set into a mask
+train           a small proposal network learns from those tiles (+ ~30 empty tiles)
+sweep           the network scans the unlabeled tissue and ranks what fires
+review          expert accepts / rejects the top proposals (2 s each); rejects = hard negatives
+retrain         … repeat once or twice, then sweep every slide
+```
+
+Everything is parameterised by a `TargetSpec`: which mask channels the target
+has, its size window, an optional relation between channels ("the ring must
+enclose a nucleus"), and how a proposal is matched to ground truth (mask overlap
+or point distance). The same code runs for a tau halo (two masks, relation) and
+a mitotic figure (one mask, point ground truth).
+
+The package also contains the **oracle simulation** that produces the
+label-efficiency curves: on a benchmark that already has ground truth, the
+oracle plays the pathologist, so the loop can be run from many seeds with a
+measured annotator budget (points placed + decisions made) against held-out
+slide F1, next to a random-tile baseline and the full-data upper bound.
+
+## Layout
+
+```
+src/pathseed/
+  target.py     TargetSpec (+ presets: tau, mitosis)
+  manifest.py   dataset layout (images/ + one mask dir per channel + manifest.json), Label
+  propose.py    probability maps -> proposals (components, size window, relation rule)
+  metrics.py    object / tile detection F1, per-fold result record
+  folds.py      slide-held-out folds
+  budget.py     annotator cost accounting
+  oracle.py     simulated reviewer from ground truth
+  simulate.py   the label-efficiency experiment (+ random baseline, upper bound)
+  loop.py       the real loop: state dir, train / propose / ingest_review
+  seed.py       point prompts -> masks (SAM 3 adapter; threshold fallback)
+  sweep.py      whole-slide / large-image sweep -> pool dataset
+  review.py     browser UI server (review grid + focus panel + seeding canvas), stdlib only
+  app.py        start()/stop() for Colab or local use (server + cached SAM 3)
+  project.py    SQLite bank of slides, tiles, prompts, decisions (what the UI writes)
+  wsi.py        whole-slide access (openslide) for the seeding viewer
+  roi_eval.py   MIDOG-style region evaluation: sweep, distance NMS, 7.5 um matching, F1 / AP / FROC
+  ui/dist/      the built React UI (source in ui-src/; `npm install && npm run build` there)
+  models/       prototype (numpy floor), unet (pluggable encoder + U-Net decoder, K channels), encoders.py,
+                retinanet (torchvision reference detector under the same proposal contract)
+  plot.py       F1-vs-budget figure
+  cli.py
+tests/             synthetic benchmark; runs without torch
+experiments/midog/ the paper experiments on MIDOG++ (see below)
+```
+
+## Experiments (MIDOG++)
+
+`experiments/midog/` holds everything behind the MIDOG++ numbers in `experiments/midog/RESULTS.md`:
+`build_midog.py` (ROIs -> tiles with point ground truth), `paper_midog.py` (the label-efficiency loop with the
+ground truth as reviewer, one JSON row per round), `full_bench.py` (full-training-set ceilings),
+`roi_eval.py` (region-level scoring), `calibrate.py` (validation-selected threshold),
+`crosscheck_eval.py` (the same detections scored with the official MIDOG 2025 evaluation code),
+`midogpp_split_ammeling.json` (the patient-level split of Ammeling et al. 2026), and the Colab runners
+`colab_loop_v3.sh` / `colab_ceiling2.sh`. The seed tiles, detections and models are on Zenodo (link to come).
+
+## UI
+
+`pathseed.review.serve()` serves a React app (Vite, Tailwind, framer-motion; source in
+`ui-src/`, prebuilt into `src/pathseed/ui/dist/`). Review mode: card grid with masks,
+focus panel with zoom and per-proposal measurements, keyboard `a`/`r`/`u`, arrows,
+`m` toggles masks (per-card ◐ toggles one tile), `f` hides the panel. Seed mode: tile
+list with filter, click = positive point, shift-click = negative, `1`/`2` switch channel,
+`z` undo, `s` save, `e` save as empty. Rebuild after editing `ui-src/`:
+`cd ui-src && npm install && npm run build`.
+
+## Install
+
+```
+pip install -e .              # core: numpy, scipy, pillow, scikit-image
+pip install -e '.[torch]'     # proposal network (torch, timm)
+pip install -e '.[sam3]'      # SAM 3 seeding (transformers)
+pip install -e '.[wsi,plot,dev]'
+pytest
+```
+
+## Encoders
+
+The network is a U-Net decoder over a pluggable encoder; output channels come
+from the target (one by default). Multi-scale timm models work by name
+(`mobilenetv4_conv_small`, `fastvit_t8`, `tiny_vit_5m_224`, `convnext_tiny`,
+`resnet18`, ...); plain ViTs get a ViTDet-style feature pyramid
+(`vit:vit_small_patch16_224`, `vit:samvit_base_patch16`, `vit:hf-hub:MahmoodLab/UNI`).
+`freeze_encoder=True` trains only the decoder. `pathseed encoders <spec>...` prints
+what each one hands the decoder. Pathology foundation models have short names
+(`uni`, `uni2h`, `hoptimus0`, `hoptimus1`, `virchow2`); they are gated on the
+Hugging Face Hub: accept the terms on the model page, then log in once
+(`huggingface-cli login`, or `huggingface_hub.login(token)`; on Colab keep the
+token in Secrets and call login from a cell). Each carries its own input
+normalisation.
+
+## Simulation on the tau benchmark
+
+```
+pathseed folds    --dataset macrophage_100k_curated --out folds.json --tau-fixed
+pathseed simulate --dataset macrophage_100k_curated --target tau --folds folds.json --test-fold 0 \
+                  --model unet --seed-pos 30 --seed-neg 30 --rounds 2 --review-cap 300 \
+                  --seeds 0,1,2 --random --full --out runs/ --opt epochs=20
+pathseed summarise --runs runs/ --csv runs.csv --plot curve.png
+```
+
+## Start the app (Colab or local)
+
+```python
+from pathseed.app import start, stop
+start("/content/dataset", state="/content/state",
+      slides_dir="/content/drive/MyDrive/svs", target="tau",
+      sam3_cache="/content/drive/MyDrive/sam3/checkpoint")   # prints the URL (Colab proxy or localhost)
+```
+
+`start()` loads SAM 3 once and reuses it, replaces a previous server on the same
+port, and picks a free port if that one is taken. `stop()` shuts everything down.
+`seg="threshold"` runs without a model (dry run), `seg=None` disables seeding.
+
+## The real loop
+
+```python
+from pathseed import target
+from pathseed.loop import Loop
+from pathseed.review import serve
+from pathseed.seed import Sam3PointSegmenter
+
+tgt = target.tau()
+loop = Loop.init("state", "dataset", tgt)
+serve("dataset", None, tgt, segmenter=Sam3PointSegmenter(), port=8765)   # seed tab: place points, save
+# ... then add the saved seed labels:
+import json; from pathseed.manifest import Label
+loop.add_labels([Label.from_dict(d) for d in json.load(open("dataset/seed_labels.json"))], seed_instances=30, seed_negatives=30)
+loop.train(0, model="unet", epochs=20)                                   # encoder="fastvit_t8", freeze_encoder=True ...
+# sweep slides into the same dataset dir (pathseed sweep ...), then
+loop.propose(0, cap=300)
+serve("dataset", "state/round_0", tgt, port=8765)                        # review tab
+loop.ingest_review(0, accepted_source="files")
+loop.train(1, model="unet", epochs=20)
+```

pathseed-0.1.0/experiments/midog/RESULTS.md

@@ -0,0 +1,148 @@
+# pathseed results (living document, updated 2026-09-07 evening)
+
+## Protocol v3 (current): MIDOG++ on the Ammeling patient split, validation-selected threshold
+
+Split of Ammeling et al. 2026 (arXiv 2607.28007, "Beyond classification: pathology foundation models as
+detection encoders for mitotic figures"): the 475 MIDOG++ ROIs with >= 1 mitotic figure, sorted, shuffled with
+seed 42; 71 test ROIs (1,714 figures), 71 validation (1,511), 333 train (8,712). Reproduced in
+`experiments/midog/midogpp_split_ammeling.json`. Every model is trained on the train ROIs only; the score threshold is chosen
+on the validation ROIs (grid 0.05–0.995) and applied once to the test ROIs. Matching: a detection counts if its
+centre lies within 7.5 um (30 px) of an unclaimed figure; we also report the 25 px radius Ammeling uses (no
+difference in the third decimal). FROC = area of sensitivity vs FP/ROI on [0, 8] as in the MIDOG 2025 evaluation
+container (max 8). Our scoring was cross-checked on the same detections with the official MIDOG 2025 `evaluate.py`
+code path (evalutils matching, torchmetrics AP): F1 agrees to the third decimal (`experiments/midog/crosscheck_eval.py`).
+
+### Full-training-set ceilings (all 34,944 train tiles, 20 epochs) — `ceilings/`
+
+| model | params | thr (val) | test F1 | P | R | AP | FROC [0,8] (official code) |
+|---|---|---|---|---|---|---|---|
+| U-Net, TinyViT-5M encoder (ours) | 5.8 M | 0.975 | **0.763** | 0.740 | 0.789 | 0.809 | 4.40 (5.02*) |
+| RetinaNet, ResNet-50 FPN (torchvision, inside our pipeline: same tiles, sweep, scoring) | 32 M | 0.25 | 0.762 | 0.784 | 0.742 | 0.816 | 5.26 (5.26*) |
+| U-Net, UNI2-h encoder (ViT-H, encoder lr 1e-5) | 690 M | | pending | | | | |
+| U-Net, UNI encoder (ViT-L, encoder lr 1e-5), original ViT neck | 308 M | 0.985 | 0.770 | 0.745 | 0.796 | 0.757 | 4.70* |
+| U-Net, UNI encoder, 4x larger ViT-matched decoder (strides 2–16, learned final up) | 324 M | 0.985 | 0.767 | 0.719 | 0.823 | 0.734 | 4.54* |
+
+\* FROC area computed from the full ranking (`calibrate.py`); the official code samples 40 thresholds and gives a lower value for saturated score scales (TinyViT 4.40 vs 5.02).
+
+Ammeling et al., same test ROIs, their code (1008 px patches, 100 epochs, frozen FM backbones except ResNet-50):
+ResNet-50 RetinaNet end-to-end 0.792 (P 0.808 R 0.776, FROC 5.69), H-optimus-0 + RetinaNet 0.772, H-optimus-1 +
+Faster R-CNN 0.772, Virchow + RetinaNet 0.762, UNI2-h + Faster R-CNN 0.756, UNI (all heads) 0.45–0.71.
+
+Reading: a standard detector run through our pipeline lands 3 points under its published number (smaller tiles,
+5x fewer epochs, lighter augmentation), so the sweep and the metric are sound; our 5.8 M-parameter U-Net matches it
+in F1 and AP. The U-Net's score scale is saturated (best threshold 0.975; a grid capped at 0.95 would cost it 13
+points), and its top-ranked candidates contain more false positives (lower FROC) — a consequence of pos_weight 10.
+
+### Label-efficiency rounds under protocol v3 — `midog_v3/`
+
+Seed = the hand-annotated set minus ROI 244 (which falls in val): 25 figures (42 points, SAM 3 masks) + 27 empty tiles,
+69 actions ≈ 4 min. Sweep pool = 60 of the 333 train ROIs (seed 0, round-robin over tumour types, seed ROIs excluded);
+500 decisions per round (half top-scored, half uncertain), oracle reviewer, accepted label = 14 px disc, +1,500 free
+unfired background tiles per round; foundation encoders fine-tuned with encoder lr 1e-5 (decoder 3e-4), ImageNet
+encoders with 3e-4 throughout; 20 epochs per round. Test = the 71 Ammeling test ROIs (1,714 figures). **F1 = test F1 at
+the threshold selected on the 71 validation ROIs** (F1@best, the test-selected value, differs by ≤ 0.01 in every row and
+is no longer reported). Minutes = 3 s per point, 4 s per empty tile, 2.5 s per decision.
+
+| encoder | ceiling F1 | round 0 (69 actions, 4 min) | round 1 (569, 25 min) | round 2 (1,069, 46 min) | round 3 (1,569, 66 min) |
+|---|---|---|---|---|---|
+| H-optimus-0 (ViT-g, 1.1 B) | 0.792 | 0.640 | 0.725 | 0.749 | **0.759** |
+| UNI2-h (ViT-H, 690 M) | 0.798 | 0.630 | 0.750 | 0.749 | 0.755 |
+| UNI (ViT-L, 308 M) | 0.770 | 0.386 | 0.594 | 0.682 | 0.695 |
+| SAM ViT-H (632 M, natural images) | 0.762 | 0.211 | 0.421 | 0.585 | 0.648 |
+| TinyViT-5M | 0.763 | 0.350 | 0.575 | 0.627 | 0.674 |
+| ResNet-50 (26 M) | – | 0.398 | 0.554 | 0.588 | 0.622 |
+| FastViT-T8 | – | 0.180 | 0.429 | 0.570 | 0.607 |
+| MobileNetV4-S | – | 0.129 | 0.330 | 0.499 | 0.516 |
+| ConvNeXt-T | – | 0.106 | 0.256 | 0.374 | 0.467 |
+
+AP at round 3 — H-optimus-0 0.723, UNI2-h 0.727, UNI 0.6x, SAM ViT-H 0.582, TinyViT 0.659, ResNet-50 0.592, FastViT 0.543, MNv4 0.451, ConvNeXt-T 0.350.
+Earlier UNI2-h run (lost when the Colab session ended; models for rounds 1–2 not synced): 0.664 / 0.746 / 0.773 F1@best.
+
+Reading: with a pathology foundation encoder the seed model alone (4 min of clicks) reaches ~80 % of its full-data
+ceiling, one round of 500 decisions (25 min) ~91 %, two rounds ~94 %; the 5.8 M ImageNet encoder needs three rounds
+(66 min) to reach 88 % of its own, lower, ceiling. Proposal acceptance rises round by round (FM: 238 → 255 → 303 of 500).
+---
+
+# Protocol v2 (superseded 2026-09-07): official MIDOG++ csv split, threshold selected on test
+
+All MIDOG numbers are the MIDOG metric: every test ROI (111 ROIs, 2,467 mitotic
+figures of the MIDOG++ test split) swept end to end, a detection counts when its
+centre is within 7.5 µm of a labelled figure; F1 at the 0.5 operating point,
+F1 at the best score threshold (grid to 0.995; optimistic, chosen on test), AP over the score
+ranking, FROC = mean sensitivity at 0.5/1/2/4/8 FP per ROI.
+Literature: full MIDOG++ training set ≈ 0.77–0.79 F1 (RetinaNet / FM encoders); MIDOG 2025 test 0.740.
+
+The full-training-set ceiling of our U-Net (TinyViT-5M) is F1 0.764 / AP 0.812, i.e. at the literature level,
+so the decoder is not the limiting factor; the label-efficiency rounds are measured against that ceiling.
+
+## MIDOG++ — the three numbers (hand-in-the-loop, real clicks)
+
+Annotator: 30 figures clicked (50 points, SAM 3 masks) + 30 empty tiles = 80 actions, 4.5 min;
+then 500 accept/reject decisions on proposals from a sweep of 60 training ROIs = 21 min total.
+
+| step | labelled tiles | actions | encoder | F1@0.5 | F1@best (thr) | AP | FROC | found / 2,467 | FP |
+|---|---|---|---|---|---|---|---|---|---|
+| seed: 30 masks + 30 empty | 60 | 80 | TinyViT-5M | 0.149 | – | 0.139 | 0.076 | 1,400 | 14,865 |
+| seed: 30 masks + 30 empty | 60 | 80 | MobileNetV4-S | 0.073 | – | 0.034 | 0.035 | 637 | 14,310 |
+| + round 1: 500 decisions (126 ✓ 374 ✗), human reviewer | 560 | 580 | TinyViT-5M | 0.299 | 0.417 (0.95) | 0.373 | 0.205 | 1,799 | 7,777 |
+
+The paper run (`midog/`) repeats this with the ground truth as reviewer, three rounds of 500,
+for TinyViT-5M, FastViT-T8, ConvNeXt-T, MobileNetV4-S, UNI, UNI2-h, H-optimus-0 (fine-tuned),
+then frozen UNI and H-optimus-0; rows are appended here as they complete.
+| full training set (ceiling) | 40,592 | – | TinyViT-5M | 0.365 | **0.764** (0.975) | **0.812** | 0.84 | 2,401 | 8,297 |
+| full training set (ceiling) | 40,592 | – | FastViT-T8 | 0.328 | 0.751 (0.975) | 0.790 | 0.81 | 2,369 | 9,590 |
+| full training set (ceiling) | 40,592 | – | MobileNetV4-S | 0.173 | 0.680 (0.975) | 0.714 | 0.71 | 2,384 | 22,680 |
+
+### Oracle-reviewed rounds from the same 30 hand masks (TinyViT-5M; accepted label = 14 px disc at the top proposal)
+
+| review rounds | actions | +1,500 free background tiles / round | | | none | | |
+|---|---|---|---|---|---|---|---|
+| | | F1@0.5 | F1@best | AP | F1@0.5 | F1@best | AP |
+| seed only | 80 | 0.170 | 0.280 | 0.170 | – | – | – |
+| 1 × 500 decisions | 580 | 0.462 | 0.560 | 0.497 | 0.560* | 0.609* | 0.539* |
+| 2 × 500 decisions | 1,080 | **0.472** | **0.597** | 0.560 | 0.378 | 0.587 | 0.573 |
+| 3 × 500 decisions | 1,580 | **0.486** | **0.626** | **0.600** | 0.319 | 0.588 | 0.581 |
+| 4 × 500 decisions | 2,080 | **0.506** | **0.668** | **0.665** | 0.262 | 0.596 | 0.591 |
+| 5 × 500 decisions | 2,580 | 0.531 | 0.684 | 0.674 | – | – | – |
+| 6 × 500 decisions | 3,080 | 0.511 | 0.692 | **0.688** | – | – | – |
+| 8 × 500 decisions | 3,987 | 0.524 | **0.700** | 0.678 | – | – | – |
+
+Plateau from round 6 on: ≈ 2 h of expert time reaches 85 % of the ceiling AP and 92 % of the ceiling F1.
+Human-started line (your 500 decisions, then oracle), rounds 2–4: F1@best 0.607 / 0.646 / 0.666, AP 0.563 / 0.638 / 0.644.
+
+### Other encoders, same recipe, round 4 (2,080 actions): F1@best / AP
+FastViT-T8 0.596 / 0.568 · MobileNetV4-S 0.488 / 0.422 · ConvNeXt-T 0.398 / 0.281 · UNI (ViT-L, fully fine-tuned at lr 3e-4) 0.278 / 0.167 · UNI2-h cut at round 1 (0.171 / 0.077).
+Full fine-tuning of the large foundation encoders at the decoder's learning rate destroys the pretrained representation on 60 tiles; rerun with encoder lr 1e-5 pending.
+
+\* the no-background control resumed from a state that already held one reviewed round, so its rows are shifted by one round (its "seed" row is really 1 × 500).
+Reading: with free background every metric rises monotonically (AP 0.17 → 0.50 → 0.56 → 0.60, FP stays ~3.7k); without it the ranking still improves slowly (AP 0.59 at round 4) but the 0.5 operating point collapses (12k FP). Human round 1 under the same recipe: F1 0.437 / AP 0.435 vs oracle 0.462 / 0.497 — within training noise. Ceiling AP 0.81, F1 0.76.
+
+Scale of the alternative: MIDOG++ itself holds 26,286 candidate annotations over 503 ROIs, each judged by two experts (a third on disagreement) after an exhaustive screen; ≈53,000 decisions plus ~300,000 tile views, i.e. on the order of 100 expert-hours. Three review rounds here cost 1,580 actions ≈ 67 minutes.
+
+Round 1 by tumour type (F1@0.5): mast cell 0.59, lymphosarcoma 0.54, melanoma 0.28, breast 0.21, lung 0.19, soft-tissue sarcoma 0.16, neuroendocrine 0.13.
+
+Review agreement with ground truth (blue hint rings): 125 correct accepts, 1 wrong accept,
+12 figures rejected (mask not on the figure), 362 correct rejects.
+
+## Tau (macrophage_100k, fold 0 = slides 3, 9, 17; published protocol, object F1 at 30 % mask overlap)
+
+Oracle simulation, 3 seeds, MobileNetV4-S, 20 epochs; loop = 30 GT masks + 30 empty, then review rounds of 300.
+Published references on fold 0: MNv4 full data 0.920 tile F1, GBM 0.942.
+
+| step | actions | tile F1 | object F1 |
+|---|---|---|---|
+| seed 30 + 30 | 480 | 0.869 ± .015 | 0.803 |
+| round 1 | 780 | 0.944 ± .003 | 0.894 |
+| round 2 | 1,080 | 0.952 ± .005 | 0.905 |
+
+Tau is easy at the tile level (13 random positives already give 0.92); the rerun with the
+final protocol (30 + 300 empties, full-data ceiling, TinyViT) is queued.
+
+## Files (gdrive `MyDrive/macrophage/seedloop_paper/`)
+
+- `RESULTS.md` this document
+- `db/` MIDOG++ annotations (COCO), the official csv split, `midogpp_split_ammeling.json` (the split used from protocol v3 on)
+- `seed/` the annotator's hand-labelled tiles (30 figures + 30 empties, SAM 3 masks, project.db); the loops use it minus ROI 244
+- `ceilings/` protocol-v3 full-training-set models: `<model>.pt`, `<model>.json`, `roi_{val,test}_<model>*.json` (detections), `calib_<model>.json` (val-selected threshold → test), `crosscheck_*.json` (official MIDOG 2025 scorer on the same detections)
+- `midog_v3/` protocol-v3 label-efficiency loops (renamed `loops/` once the queues finish): `<encoder>.json` (one row per round) + `<encoder>/` (state, per-round models, proposals, decisions, detections)
+- `MyDrive/macrophage/_archive/seedloop_paper_oldsplit_2026-09-07/` everything from the official-csv split (protocol v2), the deep-decoder trial, the partial UNI2-h loop

pathseed-0.1.0/experiments/midog/build_midog.py

@@ -0,0 +1,111 @@
+"""MIDOG++ -> a pathseed dataset (tiles + point ground truth + disc masks).
+
+  python experiments/midog/build_midog.py --images /content/midog/images --coco /content/MIDOGpp/databases/MIDOG++.json \
+      --out /content/data/midogpp --tile 256 --bg-per-roi 60 --radius 14 --jobs 8
+
+Every ROI is cut into a tile grid. A tile is positive when >= 1 mitotic figure
+centre (category 1) lies inside it (>= `--margin` px from the border); its
+`points` hold the centres in tile coordinates and its `mitosis` mask is a disc
+of `--radius` px around each (the segmentation-style stand-in for a click mask;
+`pathseed` can later replace these with SAM 3 masks). Tiles holding only
+"imposters" (category 2) are kept as background with `imposter=1` (hard
+negatives); `--bg-per-roi` further random tissue tiles per ROI are background.
+`slide` = ROI id, `domain` = tumor type (for leave-one-domain-out folds)."""
+import argparse, json, os, random
+from concurrent.futures import ProcessPoolExecutor
+
+import numpy as np
+from PIL import Image
+
+Image.MAX_IMAGE_PIXELS = None
+
+ap = argparse.ArgumentParser()
+ap.add_argument("--images", required=True); ap.add_argument("--coco", required=True); ap.add_argument("--out", required=True)
+ap.add_argument("--tile", type=int, default=256); ap.add_argument("--margin", type=int, default=8)
+ap.add_argument("--bg-per-roi", type=int, default=60); ap.add_argument("--radius", type=int, default=14)
+ap.add_argument("--tissue-max", type=float, default=225, help="mean gray above this = empty glass, skipped")
+ap.add_argument("--jobs", type=int, default=8); ap.add_argument("--limit", type=int, default=0, help="debug: first N ROIs")
+ap.add_argument("--seed", type=int, default=0)
+ap.add_argument("--split-csv", default=None, help="MIDOGpp/datasets_xvalidation.csv: Slide;Dataset;Tumor;Scanner;... -> item.split")
+a = ap.parse_args()
+split_of, scanner_of = {}, {}
+if a.split_csv:
+    import csv
+    for row in csv.DictReader(open(a.split_csv), delimiter=";"):
+        split_of[int(row["Slide"])] = row["Dataset"].strip(); scanner_of[int(row["Slide"])] = row.get("Scanner", "").strip()
+
+coco = json.load(open(a.coco))
+imgs = {im["id"]: im for im in coco["images"]}
+ann = {}
+for an in coco["annotations"]:
+    x0, y0, x1, y1 = an["bbox"]
+    ann.setdefault(an["image_id"], []).append(((x0 + x1) / 2, (y0 + y1) / 2, an["category_id"]))
+T, M, R = a.tile, a.margin, a.radius
+for d in ("images", "mitosis"):
+    os.makedirs(os.path.join(a.out, d), exist_ok=True)
+
+
+def disc(h, w, cx, cy, r):
+    yy, xx = np.mgrid[:h, :w]
+    return (xx - cx) ** 2 + (yy - cy) ** 2 <= r * r
+
+
+def one(image_id):
+    im = imgs[image_id]
+    path = os.path.join(a.images, im["file_name"])
+    if not os.path.exists(path):
+        return []
+    arr = np.asarray(Image.open(path).convert("RGB"))
+    H, W = arr.shape[:2]
+    pts = ann.get(image_id, [])
+    rng = random.Random(a.seed + image_id)
+    items = []; bg_candidates = []
+    for y in range(0, H - T + 1, T):
+        for x in range(0, W - T + 1, T):
+            crop = arr[y:y + T, x:x + T]
+            if crop.mean() > a.tissue_max:
+                continue
+            mf = [(px - x, py - y) for px, py, c in pts if c == 1 and x + M <= px < x + T - M and y + M <= py < y + T - M]
+            imp = [(px - x, py - y) for px, py, c in pts if c == 2 and x <= px < x + T and y <= py < y + T]
+            tid = f"{image_id}_{x}_{y}"
+            if mf:
+                mask = np.zeros((T, T), bool)
+                for px, py in mf:
+                    mask |= disc(T, T, px, py, R)
+                Image.fromarray(crop).save(os.path.join(a.out, "images", f"{tid}.png"))
+                Image.fromarray((mask * 255).astype(np.uint8)).save(os.path.join(a.out, "mitosis", f"{tid}.png"))
+                items.append({"id": tid, "kind": "pos", "slide": str(image_id), "domain": im["tumor_type"], "x": x, "y": y,
+                              "points": [[round(px, 1), round(py, 1)] for px, py in mf], "n_imposter": len(imp),
+                              "split": split_of.get(image_id), "scanner": scanner_of.get(image_id)})
+            elif any(c == 1 and x <= px < x + T and y <= py < y + T for px, py, c in pts):
+                continue                                   # a figure cut by the border: neither pos nor clean bg
+            else:
+                bg_candidates.append((tid, x, y, crop, len(imp)))
+    # hard negatives (imposter tiles) always kept; plus a random sample of the rest
+    hard = [b for b in bg_candidates if b[4] > 0]
+    rest = [b for b in bg_candidates if b[4] == 0]
+    rng.shuffle(rest)
+    for tid, x, y, crop, nimp in hard + rest[: a.bg_per_roi]:
+        Image.fromarray(crop).save(os.path.join(a.out, "images", f"{tid}.png"))
+        items.append({"id": tid, "kind": "bg", "slide": str(image_id), "domain": im["tumor_type"], "x": x, "y": y, "n_imposter": nimp,
+                      "split": split_of.get(image_id), "scanner": scanner_of.get(image_id)})
+    return items
+
+
+if __name__ == "__main__":
+    ids = sorted(imgs)
+    if a.limit:
+        ids = ids[: a.limit]
+    items = []
+    with ProcessPoolExecutor(a.jobs) as ex:
+        for k, res in enumerate(ex.map(one, ids), 1):
+            items.extend(res)
+            if k % 25 == 0 or k == len(ids):
+                print(f"  {k}/{len(ids)} ROIs -> {len(items)} tiles", flush=True)
+    pos = sum(1 for it in items if it["kind"] == "pos"); hard = sum(1 for it in items if it["kind"] == "bg" and it.get("n_imposter"))
+    man = {"dataset": "MIDOG++", "tile": T, "radius": R, "coco": a.coco, "items": items,
+           "domains": sorted({im["tumor_type"] for im in imgs.values()}),
+           "summary": {"rois": len(ids), "tiles": len(items), "positive": pos, "background": len(items) - pos, "imposter_tiles": hard,
+                       "figures": sum(len(it.get("points", [])) for it in items)}}
+    json.dump(man, open(os.path.join(a.out, "manifest.json"), "w"))
+    print(json.dumps(man["summary"], indent=1))