Clarify model description and organize evaluation details

README.md

@@ -1,45 +1,55 @@
----
-license: bsd-3-clause
-tags:
-- microscopy
-- image-segmentation
-- experimental
----
-# Cytellect
-
-Experimental NCL-staining-specific nucleolar segmentation weights, fine-tuned from the untouched Cellpose-SAM `cpsam_v2` checkpoint. These weights are not the product default. Product integration and a user-operated local PoC are not completed. NPM1 staining and cytoplasm performance are not validated.
-
-The 750-update candidate is intended for a bounded detection PoC. The earlier 375-update candidate remains available for reproducibility. This is not a general-purpose or fully validated nucleolar model. No synthetic images were used in this fine-tuning run.
-
-## Data and comparison
-
-Training used 8 human-approved objects in 2 regions from one experiment. Development used 4 reference objects in one region from a separately cultured and treated experiment. That development image was not a training input, but it was used for candidate selection and is not an untouched final test. There is no completed untouched final test.
-
-The table uses the same development reference and fixed local product preprocessing, parent-nucleus gating and postprocessing. Matching requires IoU at least 0.5. Training-region results are not pooled into development performance.
-
-| Product output | TP | FP | FN | Instance F1 | Union Dice | Total area difference |
-|---|---:|---:|---:|---:|---:|---:|
-| Untouched baseline | 3 | 4 | 1 | 0.5455 | 0.8534 | -20.38% |
-| 375 updates | 4 | 2 | 0 | 0.8000 | 0.9349 | -2.69% |
-| 750 updates | 4 | 0 | 0 | 1.0000 | 0.8951 | -11.70% |
-
-At 750 updates, the three better-segmented objects have area errors of +5, -6 and +5 pixels. The remaining object has 360 predicted pixels versus 608 reference pixels: **40.8% undersegmentation**, with IoU 0.5638. F1 of 1 means four matches pass the selected threshold; it does not mean perfect boundaries or quantification. At IoU 0.7, instance F1 is 0.75.
-
-Raw model output at 750 updates has TP 3, FP 1, FN 1 and F1 0.75. The fourth object's raw IoU is about 0.428; fixed product postprocessing raises it above 0.5. Raw and product output are not interchangeable. Removing the two unmatched fragments seen at 375 improves instance detection but worsens overall area agreement and union Dice. Some training-region geometry errors and a downstream parent-gate exclusion remain.
-
-## Use and limits
-
-Use the matching NCL input conditions and reviewed product processing. Preserve the base model and record the exact checkpoint identity. Do not treat this pilot's development scores as expected accuracy on new experiments. Human reference agreement between two annotators, native fluorescence measurement accuracy, reduced correction time and broad generalization are not established.
-
-Only model state-dict weights and aggregate metadata are distributed. No research images, annotations, optimizer state, raw logs, specimen identifiers or private filesystem paths are included.
-
-| Version | File | SHA256 |
-|---|---|---|
-| 750 updates | `ncl/r1-step0750.pt` | `9d2c2ec06aa1aa71f36695b49b0828f82fd3cb633da2832c99a9f194d0bd4099` |
-| 375 updates | `ncl/r1-step0375.pt` | `bc5ea7f25ce9a9f96e9ff510cee20587e1328ac834a0f7f82aee0bc06156d906` |
-
-The corresponding JSON files contain the fixed recipe, package versions, provenance hashes and aggregate metrics. These are state dictionaries; load only with a compatible, reviewed Cellpose-SAM implementation and `weights_only=True`, rather than executing arbitrary serialized objects.
-
-## License and attribution
-
-The upstream fixed-revision model card declares BSD-3-Clause. See `NOTICE.md` for the exact upstream revision and base checkpoint, and `LICENSE.cellpose` for the upstream copyright, conditions and disclaimer. The weights have been modified by fine-tuning; no upstream endorsement is implied.
+---
+license: bsd-3-clause
+tags:
+- microscopy
+- image-segmentation
+---
+# Cytellect
+
+Cytellect provides fine-tuned Cellpose-SAM weights for nucleolar segmentation in microscopy images. The models build on the `cpsam_v2` checkpoint and are distributed with checkpoint hashes, processing recipes and evaluation metadata for reproducible use.
+
+This repository includes checkpoints at 750 and 375 training updates. Fine-tuning used human-reviewed microscopy annotations, with no synthetic images.
+
+## Model checkpoints
+
+| Version | File | SHA256 |
+|---|---|---|
+| 750 updates | `ncl/r1-step0750.pt` | `9d2c2ec06aa1aa71f36695b49b0828f82fd3cb633da2832c99a9f194d0bd4099` |
+| 375 updates | `ncl/r1-step0375.pt` | `bc5ea7f25ce9a9f96e9ff510cee20587e1328ac834a0f7f82aee0bc06156d906` |
+
+The corresponding JSON files contain the fixed recipe, package versions, provenance hashes and aggregate metrics. The training images use NCL staining.
+
+## Evaluation
+
+The following development-set comparison uses the same reference annotations, fixed local product preprocessing, parent-nucleus gating and postprocessing for all checkpoints. Instance matching uses an IoU threshold of 0.5.
+
+| Product output | TP | FP | FN | Instance F1 | Union Dice | Total area difference |
+|---|---:|---:|---:|---:|---:|---:|
+| Untouched baseline | 3 | 4 | 1 | 0.5455 | 0.8534 | -20.38% |
+| 375 updates | 4 | 2 | 0 | 0.8000 | 0.9349 | -2.69% |
+| 750 updates | 4 | 0 | 0 | 1.0000 | 0.8951 | -11.70% |
+
+The 750-update checkpoint achieves the highest instance F1 in this comparison; the 375-update checkpoint has the highest union Dice and closest total area agreement. These metrics describe complementary aspects of detection and segmentation.
+
+<details>
+<summary>Evaluation data and measurement details</summary>
+
+Training used 8 human-approved objects in 2 regions from one experiment. Development used 4 reference objects in one region from a separately cultured and treated experiment. The development image was excluded from training and used for checkpoint selection. The reported results are development-set measurements, not an independent final-test estimate. Training-region results are excluded from the comparison.
+
+At 750 updates, three objects have area errors of +5, -6 and +5 pixels. The fourth object has 360 predicted pixels versus 608 reference pixels, corresponding to 40.8% undersegmentation and IoU 0.5638. Instance F1 of 1.0 represents four matches at IoU 0.5; at IoU 0.7, instance F1 is 0.75. Boundary and area agreement are reported separately from instance detection.
+
+Raw model output at 750 updates has TP 3, FP 1, FN 1 and F1 0.75. The fourth object has raw IoU of approximately 0.428; fixed product postprocessing raises it above 0.5. The table above reports the processed output. Relative to 375 updates, the 750-update checkpoint removes two unmatched fragments, with lower union Dice and a larger total area difference. Training-region inspection also recorded geometry errors and a downstream parent-gate exclusion.
+
+The results describe the stated images and processing conditions. Performance on other staining protocols and experiments should be evaluated using corresponding reference annotations.
+
+</details>
+
+## Usage and reproducibility
+
+Use the input conditions and processing recipe documented in the accompanying metadata. Preserve the base model and record the exact checkpoint identity. Load these state dictionaries with a compatible Cellpose-SAM implementation and `weights_only=True`.
+
+The repository distributes model state-dict weights and aggregate metadata. Research images, annotations, optimizer state, raw logs, specimen identifiers and private filesystem paths are excluded.
+
+## License and attribution
+
+The upstream fixed-revision model card declares BSD-3-Clause. See `NOTICE.md` for the exact upstream revision and base checkpoint, and `LICENSE.cellpose` for the upstream copyright, conditions and disclaimer. The weights have been modified by fine-tuning; no upstream endorsement is implied.