README.md

---
license: mit
tags:
  - biology
  - plant-biology
  - microscopy
  - image-segmentation
  - cell-type-classification
  - cellpose
  - dinov2
library_name: rootscope
pipeline_tag: image-classification
---

# RootScope: Cross-species Root Cell-Type Classification from Confocal Microscopy Images

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 morpho-topological
features plus fine-tuned DINOv2 embeddings, and classifies it into one of nine
anatomical cell types using an iterative tree-based ensemble.

## Models

| | features | backbone |
|---|---|---|
| **v2** (default) | 864 = 96 morphometric + 768 embeddings | fine-tuned DINOv2 **ViT-B/14** |
| v1 | 480 = 96 morphometric + 384 embeddings | fine-tuned DINOv2 **ViT-S/14** |

v2 is at the root of this repo; v1 is in the `v1/` folder.

## Install

```bash
git clone https://github.com/ct-tranchau/Rootscope.git
cd Rootscope
conda env create -f environment.yml
conda activate rootscope
pip install .
```

## Run

```bash
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
from rootscope import predict_tif
df = predict_tif("my_image.tif", out_dir="results/")
```

## Cell types

root_cap · epidermis · exodermis · cortex · endodermis · pericycle · stele ·
xylem · phloem

## Files

| 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 | — |

## Performance

Held-out test accuracy, 864 features, 9 classes:

| 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 |

Inference: ~1.5–3 min per image on a single GPU.

## 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 (`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.

## Contact

tnchau@vt.edu