README.md

---
license: mit
tags:
- cellpose
- segmentation
- toxoplasma
- microscopy
- spacr
library_name: spacr
pipeline_tag: image-segmentation
---

# Toxoplasma PV v1

Segments *Toxoplasma gondii* parasitophorous vacuoles from a parasite stain (anti-Toxoplasma-biotin, or DsRed in the PV lumen). Round 2.

> **Superseded.** [Toxoplasma PV v2 (round 5)](https://huggingface.co/einarolafsson/toxoplasma-pv-segmentation-cpsam-r5) is trained on 556 images against this model's 229 and is 5-fold cross-validated. Prefer v2 for new work; v1 remains here for reproducibility.

- **Architecture:** Cellpose-SAM (cpsam_v2)
- **Model Zoo key:** `toxoplasma_pv_v1`
- **Checkpoint:** `cpsam_v2_toxo_r2`
- **Trained by:** einarolafsson

## Use it in spaCR

This model is distributed through the spaCR **Model Zoo**. spaCR is an open-source
package for spatial phenotype analysis of CRISPR screens and microscopy images.

```bash
pip install spacr
```

### Model Zoo (GUI)

Launch the GUI and open the **Model Zoo**:

```bash
spacr
```

Find **Toxoplasma PV v1** in the model list and press **Download**. The Model Zoo verifies
the checkpoint's SHA-256 after download, so a truncated or substituted file is
rejected rather than silently used.

### Model Zoo (Python)

```python
from spacr import model_zoo

entry = next(e for e in model_zoo.catalogue() if e.key == "toxoplasma_pv_v1")
path  = model_zoo.install(entry, dest="~/spacr_models")
print(path)   # verified local checkpoint
```

### Mask generation

Point spaCR's mask generation at the downloaded checkpoint:

```python
from spacr.core import preprocess_generate_masks

settings = {
    "src": "/path/to/images",
    "pathogen": "cellpose",
    "pathogen_model": str(path),     # the checkpoint fetched above
    "pathogen_diameter": 12,
}
preprocess_generate_masks(settings)
```

In the GUI the same thing is under **Make masks** — choose the downloaded model in
the Cellpose model field for the relevant object.

API: :func:`spacr.core.preprocess_generate_masks`,
:func:`spacr.spacr_cellpose.generate_masks_from_imgs`

## Performance

| model | train | train obj. | test | test obj. | CV | F1 @ IoU 0.5 | AJI | Dice | final train loss | final val loss | val - train | best epoch |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| stock cpsam_v2 (no fine-tuning) | — | — | 11 | not recorded | — | 0.7130 | 0.4260 | — | — | — | — | — |
| **this model (round 2)** | 229 | not recorded | 11 | not recorded | no | **0.8640** | 0.8090 | — | not recorded | not recorded | — | 100 / 100 |

Scored on 11 held-out in-house wells at IoU 0.5. On the current literature set, whose truth leans toward this model's lineage, it ties stock Cellpose-SAM on detection (F1 0.403 against 0.400).

Superseded by [Toxoplasma PV v2 (round 5)](https://huggingface.co/einarolafsson/toxoplasma-pv-segmentation-cpsam-r5), which is trained on 556 images and 5-fold cross-validated.

*Objects are reference (ground-truth) objects. Object counts and the per-epoch loss history were not recorded for this run, so those columns and the training curves are unavailable; the scores are the ones its own run reported.*

## Training data

229 training images from 2 datasets — round 1's 104 plus 125 newly curated RH and
ME49 fields — of *Toxoplasma* tachyzoite parasitophorous vacuoles stained with goat
anti-Toxoplasma-biotin, and tachyzoites expressing DsRed in the PV lumen.
100 epochs, base `cpsam_v2`.


## Environment

| | |
|---|---|
| cellpose (training) | not recorded |
| cellpose (scoring) | not recorded |
| GPU | not recorded |
| base weights | cpsam_v2 |

## Files in this repository

| path | what |
|---|---|
| `cpsam_v2_toxo_r2` | the checkpoint |
| `metadata.txt` | the checkpoint |
| `round2.log` | the checkpoint |
| `round2_heldout_metrics.csv` | the checkpoint |
| `round2_vs_round1.csv` | the checkpoint |
| `train_report.json` | the checkpoint |
| `vanilla_vs_finetuned.json` | the checkpoint |

## Limitations

- Accuracy falls sharply above IoU 0.8 — suited to counting and area rather than precise morphometry.
- The held-out literature scorecard is pending a stock-seeded re-curation.
- Superseded by Toxoplasma PV v2 (round 5).

## Links

- spaCR on GitHub: https://github.com/EinarOlafsson/spacr
- Model Zoo API: `spacr.model_zoo` — `catalogue()`, `install()`, `fetch()`, `verify()`
- Mask generation API: `spacr.core.preprocess_generate_masks`
- Issues and questions: https://github.com/EinarOlafsson/spacr/issues