Replace v2 with v3: membrane-first label priority

Dataset503_MicroridgeMembraneFirst. Same 477 tiles, same architecture,
same 100 epochs; only which class wins a contested label pixel changed.

v2 trained on labels where microridges had erased 69.6% of the membrane,
so it predicted a broken membrane and called membrane pixels microridge.

Frozen test: cell_membrane Dice 0.471 -> 0.707, boundary F1 0.659 -> 0.874,
microridge Dice 0.877 -> 0.852.

README.md

@@ -1,163 +1,170 @@
----
-license: cc-by-nc-sa-4.0
-library_name: nnunetv2
-pipeline_tag: image-segmentation
-tags:
-  - biology
-  - microscopy
-  - cell-segmentation
-  - microridge
-  - nnunet
-  - zebrafish
----
-
-# MicroridgeVectorAI — v2
-
-A 2D nnU-Net that segments **actin microridges**, **cell regions** and **cell
-membranes** in projected single-channel microscopy of epithelial tissue.
-
-Companion application: <https://github.com/LBK888/MicroridgeVectorAI> (CellVector,
-AGPL-3.0). The model runs standalone with nnU-Net v2 alone — CellVector is not
-required.
-
-| | |
-|---|---|
-| Model id | `8f1dbd06-6ec8-4c22-8e26-412cfee26ea9` |
-| Task | 2D semantic segmentation, 4 classes |
-| Architecture | nnU-Net v2 PlainConvUNet, 8 stages, patch 512x512 |
-| Trainer / folds | `nnUNetTrainer_100epochs`, fold 0 |
-| Input | single-channel 2D image, any size |
-| Snapshot hash | `dbe134f83c52b8ecae6cb62182310205496497ec297406ed8a2c912b60ba8cc9` |
-
-Labels: `0` background, `1` cell_region, `2` cell_membrane, `3` microridge.
-
-## Scores
-
-Frozen test — 36 tiles from **3 fields the model never saw**. Splits are grouped
-by source field, so no tile of a training field appears in the test set.
-
-| Metric | Value |
-|---|---|
-| cell_region Dice | 0.944 |
-| cell_membrane Dice | 0.471 |
-| cell_membrane boundary F1 (1 px tolerance) | 0.659 |
-| microridge Dice | 0.877 |
-| microridge precision / recall | 0.911 / 0.855 |
-| microridge skeleton length error | 0.100 |
-
-nnU-Net's own fold-0 validation (89 tiles): cell_region 0.964, cell_membrane
-0.495, microridge 0.912.
-
-**Reading the membrane number.** A Dice of 0.47 on a 3-pixel line covering ~1%
-of the frame is not the same failure as 0.47 on a region class: thin-structure
-Dice collapses when a prediction is offset by a pixel even where it follows the
-right path. The boundary F1 of 0.659, which allows one pixel of tolerance, is
-the more informative figure, and the gap between them says the membrane is
-mostly in the right place but not pixel-exact.
-
-## Limitations
-
-- **Cell contours derived from the label map merge.** Reconstructing cells as
-  the connected components of `label in (1, 3)` yields a single blob, because
-  the predicted membrane is thin and not perfectly closed. Use the predicted
-  membrane (class 2) for cell geometry, or split the region with a watershed
-  seeded inside cells. Do not expect instance-separated cells out of the box.
-- **The ground truth was not human-reviewed.** Labels were imported from
-  published raster masks and corrected only for import artifacts, not by an
-  expert. Treat this model as a proposal generator to be corrected, which is how
-  the companion application uses it.
-- **Trained on 13 fields.** Train and validation loss diverge (-0.755 vs
-  -0.629), which is what a small number of independent acquisitions looks like.
-  More fields will help more than more epochs.
-- **One fold, not an ensemble.** Only fold 0 was trained.
-- Validated on zebrafish periderm-style epithelial microridge imagery. Behaviour
-  on other tissue, magnification or modality is unknown.
-
-## Training data
-
-Wide-field frames cut into 477 tiles of at most 512x512 from 19 fields, keeping
-only regions whose raster truth is trustworthy. Uneven illumination leaves part
-of such a frame too dark for the upstream segmentation to resolve anything, and
-that failure is silent — the skeleton mask is empty while the cell mask still
-looks complete. Blocks were kept only where skeleton density cleared both an
-absolute floor and a share of the frame's own 90th percentile, **and** at least
-95% of the block was attributed to a cell. 68.3% of the field pixels survived.
-
-Labels were rasterized from vector geometry with a 3 px membrane and a 5 px
-microridge stroke.
-
-## Files
-
-```text
-registry.json                                   provenance record, metrics, checksums
-nnUNet_results/Dataset502_MicroridgeField/
-└─ nnUNetTrainer_100epochs__nnUNetPlans__2d/
-   ├─ dataset.json                              channel names and label map
-   ├─ plans.json                                preprocessing and architecture
-   └─ fold_0/checkpoint_final.pth               weights
-```
-
-Those three files under the trainer folder are the complete inference set. The
-directory names encode the configuration — nnU-Net parses
-`Dataset<ID>_<name>/<trainer>__<plans>__<configuration>` — so do not rename them.
-
-The checkpoint is shipped unmodified so the `checkpoint_sha256` in
-`registry.json` verifies. About half of it is optimizer state; stripping to
-`network_weights`, `init_args`, `trainer_name` and
-`inference_allowed_mirroring_axes` halves the size but invalidates that
-checksum.
-
-## Usage
-
-```bash
-pip install nnunetv2 huggingface_hub
-hf download leobk/MicroridgeVectorAI --local-dir microridge-model
-```
-
-```python
-import torch, numpy as np, tifffile
-from nnunetv2.inference.predict_from_raw_data import nnUNetPredictor
-
-MODEL = ("microridge-model/nnUNet_results/Dataset502_MicroridgeField"
-         "/nnUNetTrainer_100epochs__nnUNetPlans__2d")
-
-predictor = nnUNetPredictor(device=torch.device("cuda"))
-predictor.initialize_from_trained_model_folder(
-    MODEL, use_folds=(0,), checkpoint_name="checkpoint_final.pth"
-)
-
-image = tifffile.imread("frame.tif").astype("float32")
-segmentation = predictor.predict_single_npy_array(
-    image[None, None], {"spacing": (999.0, 1.0, 1.0)}, None, None, False
-)
-```
-
-No nnU-Net environment variables are needed for this path. Roughly 13 s for a
-512x512 tile on an RTX 4080 SUPER.
-
-### Reimplementing the pipeline
-
-The network takes `(1, 1, H, W)` and returns 4 logit channels, and exports to
-TorchScript. If you drive it yourself, reproduce all of:
-
-- **Normalization** — z-score using *each image's own* mean and standard
-  deviation (`use_mask_for_norm=False`). No dataset statistics;
-  `foreground_intensity_properties_per_channel` in `plans.json` is for CT
-  normalization and unused here.
-- **Sliding window** — 512x512 patches, step 0.5, Gaussian-weighted overlap.
-- **Test-time augmentation** — mirroring over axes `(0, 1)`.
-- **Output** — argmax over the 4 channels.
-
-Skipping the normalization or the Gaussian window degrades results noticeably
-and without any error.
-
-## Licensing note
-
-These weights are released under **CC BY-NC-SA 4.0**: attribution required,
-**non-commercial use only**, derivatives under the same terms. Note that this
-differs from the companion application's code licence (AGPL-3.0) — the code and
-the weights are covered separately.
-
-The weights were trained on third-party imagery; if that source data carries its
-own terms, they may constrain redistribution of this model independently of this
-label.
+---
+license: cc-by-nc-sa-4.0
+library_name: nnunetv2
+pipeline_tag: image-segmentation
+tags:
+  - biology
+  - microscopy
+  - cell-segmentation
+  - microridge
+  - nnunet
+  - zebrafish
+---
+
+# MicroridgeVectorAI — v3
+
+A 2D nnU-Net that segments **actin microridges**, **cell regions** and **cell
+membranes** in projected single-channel microscopy of epithelial tissue.
+
+Companion application: <https://github.com/LBK888/MicroridgeVectorAI> (CellVector,
+AGPL-3.0). The model runs standalone with nnU-Net v2 alone — CellVector is not
+required.
+
+| | |
+|---|---|
+| Model id | `a619b15c-e00f-489b-887c-6386e3836c11` |
+| Task | 2D semantic segmentation, 4 classes |
+| Architecture | nnU-Net v2 PlainConvUNet, 8 stages, patch 512x512 |
+| Trainer / folds | `nnUNetTrainer_100epochs`, fold 0 |
+| Input | single-channel 2D image, any size |
+| Snapshot hash | `dbe134f83c52b8ecae6cb62182310205496497ec297406ed8a2c912b60ba8cc9` |
+| Label policy | `membrane-first-v2`, membrane 3 px, microridge 5 px |
+
+Labels: `0` background, `1` cell_region, `2` cell_membrane, `3` microridge.
+
+## Scores
+
+Frozen test — 36 tiles from **3 fields the model never saw**. Splits are grouped
+by source field, so no tile of a training field appears in the test set.
+
+| Metric | Value | v2 |
+|---|---|---|
+| cell_region Dice | 0.943 | 0.944 |
+| cell_membrane Dice | **0.707** | 0.471 |
+| cell_membrane boundary F1 (1 px tolerance) | **0.874** | 0.659 |
+| microridge Dice | 0.852 | 0.877 |
+| microridge precision / recall | 0.899 / 0.822 | 0.911 / 0.855 |
+| microridge skeleton length error | 0.105 | 0.100 |
+
+nnU-Net's own fold-0 validation (89 tiles): cell_region 0.964, cell_membrane
+0.696, microridge 0.886.
+
+v2 was trained on labels in which the microridge class had erased 69.6% of the
+membrane: classes are mutually exclusive and microridges were stroked last, so a
+ridge running beside a cell edge overwrote it. v3 reverses that contest. The
+membrane keeps all of its pixels and the microridge class yields 7.2% of its
+own, which it can afford at a quarter of the frame. Nothing else changed — same
+data, same architecture, same 100 epochs.
+
+**Reading the membrane number.** Dice on a 3-pixel line covering under 3% of the
+frame collapses when a prediction is offset by a pixel even where it follows the
+right path, so it understates a thin structure. The boundary F1 of 0.874, which
+allows one pixel of tolerance, is the more informative figure; the gap between
+0.707 and 0.874 is the residual sub-pixel offset, not missing membrane.
+
+## Limitations
+
+- **Cell instances are approximate.** Cells are recovered as connected
+  components separated by the predicted membrane. On a frozen-test tile holding
+  10 cells this returns 9, against 1 for v2, whose membrane was too broken to
+  separate anything. Expect near-misses where the membrane is faint, not exact
+  instance segmentation.
+- **The ground truth was not human-reviewed.** Labels were imported from
+  published raster masks and corrected only for import artifacts, not by an
+  expert. Treat this model as a proposal generator to be corrected, which is how
+  the companion application uses it.
+- **Trained on 13 fields.** Train and validation loss diverge (-0.782 vs
+  -0.636), which is what a small number of independent acquisitions looks like.
+  More fields will help more than more epochs.
+- **One fold, not an ensemble.** Only fold 0 was trained.
+- Validated on zebrafish periderm-style epithelial microridge imagery. Behaviour
+  on other tissue, magnification or modality is unknown.
+
+## Training data
+
+Wide-field frames cut into 477 tiles of at most 512x512 from 19 fields, keeping
+only regions whose raster truth is trustworthy. Uneven illumination leaves part
+of such a frame too dark for the upstream segmentation to resolve anything, and
+that failure is silent — the skeleton mask is empty while the cell mask still
+looks complete. Blocks were kept only where skeleton density cleared both an
+absolute floor and a share of the frame's own 90th percentile, **and** at least
+95% of the block was attributed to a cell. 68.3% of the field pixels survived.
+
+Labels were rasterized from vector geometry with a 3 px membrane and a 5 px
+microridge stroke.
+
+## Files
+
+```text
+registry.json                                   provenance record, metrics, checksums
+nnUNet_results/Dataset503_MicroridgeMembraneFirst/
+└─ nnUNetTrainer_100epochs__nnUNetPlans__2d/
+   ├─ dataset.json                              channel names and label map
+   ├─ plans.json                                preprocessing and architecture
+   └─ fold_0/checkpoint_final.pth               weights
+```
+
+Those three files under the trainer folder are the complete inference set. The
+directory names encode the configuration — nnU-Net parses
+`Dataset<ID>_<name>/<trainer>__<plans>__<configuration>` — so do not rename them.
+
+The checkpoint is shipped unmodified so the `checkpoint_sha256` in
+`registry.json` verifies. About half of it is optimizer state; stripping to
+`network_weights`, `init_args`, `trainer_name` and
+`inference_allowed_mirroring_axes` halves the size but invalidates that
+checksum.
+
+## Usage
+
+```bash
+pip install nnunetv2 huggingface_hub
+hf download leobk/MicroridgeVectorAI --local-dir microridge-model
+```
+
+```python
+import torch, numpy as np, tifffile
+from nnunetv2.inference.predict_from_raw_data import nnUNetPredictor
+
+MODEL = ("microridge-model/nnUNet_results/Dataset503_MicroridgeMembraneFirst"
+         "/nnUNetTrainer_100epochs__nnUNetPlans__2d")
+
+predictor = nnUNetPredictor(device=torch.device("cuda"))
+predictor.initialize_from_trained_model_folder(
+    MODEL, use_folds=(0,), checkpoint_name="checkpoint_final.pth"
+)
+
+image = tifffile.imread("frame.tif").astype("float32")
+segmentation = predictor.predict_single_npy_array(
+    image[None, None], {"spacing": (999.0, 1.0, 1.0)}, None, None, False
+)
+```
+
+No nnU-Net environment variables are needed for this path. Roughly 13 s for a
+512x512 tile on an RTX 4080 SUPER.
+
+### Reimplementing the pipeline
+
+The network takes `(1, 1, H, W)` and returns 4 logit channels, and exports to
+TorchScript. If you drive it yourself, reproduce all of:
+
+- **Normalization** — z-score using *each image's own* mean and standard
+  deviation (`use_mask_for_norm=False`). No dataset statistics;
+  `foreground_intensity_properties_per_channel` in `plans.json` is for CT
+  normalization and unused here.
+- **Sliding window** — 512x512 patches, step 0.5, Gaussian-weighted overlap.
+- **Test-time augmentation** — mirroring over axes `(0, 1)`.
+- **Output** — argmax over the 4 channels.
+
+Skipping the normalization or the Gaussian window degrades results noticeably
+and without any error.
+
+## Licensing note
+
+These weights are released under **CC BY-NC-SA 4.0**: attribution required,
+**non-commercial use only**, derivatives under the same terms. Note that this
+differs from the companion application's code licence (AGPL-3.0) — the code and
+the weights are covered separately.
+
+The weights were trained on third-party imagery; if that source data carries its
+own terms, they may constrain redistribution of this model independently of this
+label.

nnUNet_results/{Dataset502_MicroridgeField → Dataset503_MicroridgeMembraneFirst}/nnUNetTrainer_100epochs__nnUNetPlans__2d/fold_0/checkpoint_final.pth

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:0e9e440280e99deffcd772cfde6e59aaa6e0f3578f59662a12246226692dbdde
-size 370825919
+oid sha256:c513cee01f60eb21f2b9ee74f9f0fd2d44a84d99437440d7e1836ccfd91e25bb
+size 370825791

nnUNet_results/{Dataset502_MicroridgeField → Dataset503_MicroridgeMembraneFirst}/nnUNetTrainer_100epochs__nnUNetPlans__2d/plans.json

@@ -1,5 +1,5 @@
 {
-    "dataset_name": "Dataset502_MicroridgeField",
+    "dataset_name": "Dataset503_MicroridgeMembraneFirst",
     "plans_name": "nnUNetPlans",
     "original_median_spacing_after_transp": [
         999.0,

registry.json

@@ -5,36 +5,38 @@
       "artifact_sha256": {
         "dataset.json": "aa6242b569dc3fa70ee707db38970fd7e97fbfb45f48aa7f1a68a1c7a5a899cf",
         "dataset_fingerprint.json": "9234acf421a087a276d8271f214cbddfdd97c1b71f4974e18a71fe44f680c7b9",
-        "fold_0/checkpoint_best.pth": "189e5d97d34dd8750bf279e47a78b8038ebb31d95b72ddcf0425f55c2785eb75",
-        "fold_0/checkpoint_final.pth": "0e9e440280e99deffcd772cfde6e59aaa6e0f3578f59662a12246226692dbdde",
-        "plans.json": "7e403e7cb95ad1efbf184de013d651595561f248bd885d461d5b0f8fa2e73874"
+        "fold_0/checkpoint_best.pth": "74ae48ea41fb2ebe5fefe00a775f5ee61b81d3bb91963e0ffc9c35630f3f1a3a",
+        "fold_0/checkpoint_final.pth": "c513cee01f60eb21f2b9ee74f9f0fd2d44a84d99437440d7e1836ccfd91e25bb",
+        "plans.json": "edadfcb32d5d88e1da2c466bc16cf0e34521c148596c91bf57805f33b94c1d4a"
       },
       "augmentation_profile_hash": "6f738a972b6f7eba84ee6a2cd5cbd01f83dbed2afa9633439b89e76bb3a5a4dd",
       "backend_id": "nnunetv2-local",
       "backend_version": "2.8.1",
       "benchmark_id": null,
       "checkpoint_path": "fold_0/checkpoint_final.pth",
-      "checkpoint_sha256": "0e9e440280e99deffcd772cfde6e59aaa6e0f3578f59662a12246226692dbdde",
+      "checkpoint_sha256": "c513cee01f60eb21f2b9ee74f9f0fd2d44a84d99437440d7e1836ccfd91e25bb",
       "configuration": {
         "configuration": "2d",
-        "dataset_id": 502,
-        "dataset_name": "MicroridgeField",
+        "dataset_id": 503,
+        "dataset_name": "MicroridgeMembraneFirst",
         "epochs": 100,
         "executed_locally": true,
         "fold": 0,
+        "label_priority": "membrane-first-v2",
         "membrane_width_px": 3,
         "microridge_width_px": 5,
-        "plan_command": "nnUNetv2_plan_and_preprocess -d 502 -c 2d --verify_dataset_integrity",
+        "plan_command": "nnUNetv2_plan_and_preprocess -d 503 -c 2d --verify_dataset_integrity",
         "plans": "nnUNetPlans",
         "source_data": "full view field tiles, trustworthy regions only",
         "split_grouping": "specimen:field_frame_uri",
+        "supersedes": "Dataset502 (exclusive-v1) whose labels lost 71% of the membrane",
         "torch_version": "2.12.1+cu130",
-        "train_command": "nnUNetv2_train 502 2d 0 -tr nnUNetTrainer_100epochs --npz",
+        "train_command": "nnUNetv2_train 503 2d 0 -tr nnUNetTrainer_100epochs --npz",
         "trainer": "nnUNetTrainer_100epochs",
-        "training_job_id": "0305ef07-38d7-41d3-bc44-a1e51a2c0d4f"
+        "training_job_id": "064df461-43de-4393-aca9-51b2d97209e4"
       },
-      "created_at": "2026-08-31T10:00:21.285927Z",
-      "dataset_artifact_hash": "90178985de2ef8d24b5a7338b7e9fec83dfe6164e0558ef30d449d8e13439547",
+      "created_at": "2026-09-01T10:29:13.172184Z",
+      "dataset_artifact_hash": "f5a648f0dde8485a96df95d26d7b0edadd68482a8d9fa1c91420b1c58809d090",
       "folds_completed": [
         0
       ],
@@ -43,19 +45,19 @@
       "label_contract": "cellvector.annotation/1.0.0",
       "metrics": {
         "frozen_test_cases": 36,
-        "frozen_test_cell_membrane_boundary_f1": 0.6589374464002449,
-        "frozen_test_cell_membrane_dice": 0.4708712201149024,
-        "frozen_test_cell_region_dice": 0.9438357584291484,
-        "frozen_test_cell_region_iou": 0.8940270075353971,
-        "frozen_test_microridge_dice": 0.8767592825579081,
-        "frozen_test_microridge_precision": 0.9106816936813859,
-        "frozen_test_microridge_recall": 0.8550323207264082,
-        "frozen_test_microridge_skeleton_length_error": 0.0997634178921583,
-        "nnunet_validation_dice_cell_membrane": 0.4954518160625487,
-        "nnunet_validation_dice_cell_region": 0.9644053946394331,
-        "nnunet_validation_dice_microridge": 0.9114529420774974
+        "frozen_test_cell_membrane_boundary_f1": 0.87437327255091,
+        "frozen_test_cell_membrane_dice": 0.7074205306372878,
+        "frozen_test_cell_region_dice": 0.9432985097912598,
+        "frozen_test_cell_region_iou": 0.8930619679511916,
+        "frozen_test_microridge_dice": 0.8519748198693858,
+        "frozen_test_microridge_precision": 0.8986679339680429,
+        "frozen_test_microridge_recall": 0.8215124251430418,
+        "frozen_test_microridge_skeleton_length_error": 0.10468182937528298,
+        "nnunet_validation_dice_cell_membrane": 0.6959348980123595,
+        "nnunet_validation_dice_cell_region": 0.9642334995848282,
+        "nnunet_validation_dice_microridge": 0.8858968681328583
       },
-      "model_id": "8f1dbd06-6ec8-4c22-8e26-412cfee26ea9",
+      "model_id": "a619b15c-e00f-489b-887c-6386e3836c11",
       "parent_model_id": null,
       "provenance_status": "verified",
       "selected_at": null,
@@ -64,8 +66,8 @@
       "snapshot_hash": "dbe134f83c52b8ecae6cb62182310205496497ec297406ed8a2c912b60ba8cc9",
       "software_smoke_test": false,
       "status": "trained",
-      "training_job_id": "0305ef07-38d7-41d3-bc44-a1e51a2c0d4f",
-      "updated_at": "2026-08-31T10:00:21.285927Z"
+      "training_job_id": "064df461-43de-4393-aca9-51b2d97209e4",
+      "updated_at": "2026-09-01T10:29:13.172184Z"
     }
   ],
   "schema_version": "1.0.0"