Document v1 and v2; replace the pre-leak-fix accuracy table with verified v2 numbers

README.md

@@ -14,12 +14,22 @@ pipeline_tag: image-classification
 
 # RootScope: Cross-species Root Cell-Type Classification from Confocal Microscopy Images
 
-Trained model weights for **[RootScope](https://github.com/ct-tranchau/Rootscope)**.
+Trained model weights for RootScope.
 
 RootScope takes a raw confocal root-tip cross-section TIFF, segments every cell
-with **Cellpose-SAM**, describes each cell with hand-crafted morpho-topological
-features plus fine-tuned **DINOv2** embeddings, and classifies it into one of
-nine anatomical cell types using an iterative tree-based ensemble.
+with Cellpose-SAM, describes each cell with hand-crafted morpho-topological
+features plus fine-tuned DINOv2 embeddings, and classifies it into one of nine
+anatomical cell types using an iterative tree-based ensemble.
+
+## Two model versions
+
+| | features | backbone | use |
+|---|---|---|---|
+| **v2** (default) | 864 = 96 morphometric + 768 embeddings | fine-tuned DINOv2 **ViT-B/14** | the model evaluated in the manuscript, and the one the hosted demo runs |
+| v1 | 480 = 96 morphometric + 384 embeddings | fine-tuned DINOv2 **ViT-S/14** | the earlier release, kept for reproducing previous results |
+
+v2 lives in the `v2/` folder of this repo; v1 is at the root. RootScope
+downloads whichever you select and caches it.
 
 ## Install
 
@@ -40,6 +50,12 @@ rootscope --tif my_image.tif --out results/
 `results/` gets a per-cell CSV and a labeled overlay PNG, per model plus the
 ensemble.
 
+To use the earlier model instead:
+
+```bash
+rootscope --tif my_image.tif --out results/ --model-version v1
+```
+
 Or from Python:
 
 ```python
@@ -49,35 +65,55 @@ df = predict_tif("my_image.tif", out_dir="results/")
 
 ## Cell types
 
-`root_cap` · `epidermis` · `exodermis` · `cortex` · `endodermis` · `pericycle` ·
-`stele` · `xylem` · `phloem`
+root_cap · epidermis · exodermis · cortex · endodermis · pericycle · stele ·
+xylem · phloem
 
 ## Files
 
-| File | Size |
-|------|------|
-| `model_RandomForest.joblib` | 349 MB |
-| `backbone.pt` (fine-tuned DINOv2) | 88 MB |
-| `model_LightGBM.joblib` | 29 MB |
-| `model_XGBoost.joblib` | 14 MB |
-| scalers, feature columns, label encoder | small |
+| File | v2 | v1 |
+|------|----|----|
+| `backbone.pt` (fine-tuned DINOv2) | 330 MB | 84 MB |
+| `model_RandomForest.joblib` | 100 MB | 333 MB |
+| `model_LightGBM.joblib` | 13 MB | 28 MB |
+| `model_XGBoost.joblib` | 7 MB | 13 MB |
+| scalers, feature columns, label encoder | small | small |
+| `meta.json` | small | — |
+
+`meta.json` records the backbone architecture. It must travel with
+`backbone.pt`: without it the loader builds ViT-S/14 and silently discards
+mismatched ViT-B weights, leaving the classifiers a 384-wide feature block where
+they expect 768.
 
 ## Performance
 
-Held-out test accuracy, 480 features, 9 classes:
+**v2**, held-out test split, 11,070 cells across 26 sections, 9 classes,
+864 features. Accuracy after the iterative neighbour labels converge, with 95%
+bootstrap confidence intervals over sections:
+
+| Model | Test | 95% CI |
+|-------|------|--------|
+| XGBoost | **0.861** | 0.828 – 0.895 |
+| LightGBM | 0.858 | 0.823 – 0.895 |
+| RandomForest | 0.832 | 0.798 – 0.869 |
+
+The three-model ensemble scores 0.860, statistically indistinguishable from
+XGBoost alone; the differences among all of these sit inside the confidence
+intervals.
 
-| Model | Test |
-|-------|------|
-| LightGBM | **0.965** |
-| XGBoost | 0.959 |
-| RandomForest | 0.937 |
+**v1** has not been re-evaluated since the neighbour-label leak was corrected.
+The figure of 0.965 published here previously was measured with ground-truth
+neighbour labels in place, which inflates the result by roughly 3 points, and it
+is not comparable to the v2 figures above. Use v2 for any quantitative claim.
 
-Inference: ~1.5–3 min per image on a single GPU.
+Inference: ~1.5–3 min per image on a single GPU. v1 and v2 measured within 2% of
+each other end to end — the heavier v2 backbone costs a few seconds, while
+Cellpose segmentation dominates and is identical for both.
 
 ## Notes
 
 - Set `--um-per-px` to your image's real scale — it is not auto-detected, and
-  the default of 1.0 distorts every size feature.
+  the default of 1.0 distorts every size feature (`area_um2`, `perimeter_um`,
+  `dist_from_centroid_um`).
 - Input must be a raw image, not a segmentation mask.
 - CPU works but is far slower (~15–30 min per image).
 - `scikit-learn` is pinned to 1.7.2, the version these models were saved with.