spacr.model_zoo¶

Workflow inputs and outputs¶

Model Zoo¶

Inspect model provenance and download/install compatible checkpoints or backends. A listed backend is not itself a checkpoint file.

Open: Make Masks → Model Zoo.

Inputs and outputs below include conditional alternatives. The guidance and handoff notes say which route applies.

Inputs

Segmentation checkpoint — Saved Cellpose-compatible checkpoint or a compatible installed backend selected with its own configuration.

Outputs

Segmentation checkpoint — Saved Cellpose-compatible checkpoint or a compatible installed backend selected with its own configuration.

API reference.

Module tutorial.

Browse, verify, fetch and benchmark spaCR segmentation and classification models.

Why this exists¶

spaCR can run a stock Cellpose model, a Cellpose model somebody on the team fine-tuned last year, a classifier checkpoint from a run three folders up, or a checkpoint downloaded from Hugging Face. Today the only way to find out which of those exist on a machine is find / -name '*.pth', the only way to know what one of them was trained on is to remember, and the only way to know whether the copy on disk is the file the author published is to hope.

This module answers those three questions and nothing else:

what is here — discover_local() walks folders and returns the checkpoints, classified as Cellpose or classifier, with whatever provenance is recoverable from the settings snapshots spaCR already writes;
is it the right bytes — sha256_file() / verify() / fetch(), which downloads atomically, checksums what arrived, and refuses to install a mismatch;
what does it do on my data — benchmark(), which is spacr.model_compare’s “three fields” harness pointed at one model instead of two.

Nothing here imports torch or cellpose at module import time. Browsing the zoo, reading provenance, checksumming a file and rendering the table all work on a machine with neither installed; only benchmark() (through spacr.model_compare.segment_with_cellpose()) needs them, and only when it is called. tests/test_model_zoo.py asserts that.

The four things that make this trustworthy rather than merely convenient¶

Every download is checksummed, and verification happens before use.

A checkpoint truncated by a dropped connection, or swapped for a different one at the same URL, still loads. It does not raise; it produces silently different masks, and the run that used it looks exactly like the run that did not. So fetch() hashes what arrived and compares it to the hash the catalogue published: a mismatch deletes the file and raises ChecksumMismatch — the entry is never registered. The hash that was actually computed is stored on the returned entry, so “verified” means “these bytes”, not “this filename”.

A catalogue entry with no published hash cannot be verified at all, and that is refused by default (require_checksum=True) rather than quietly treated as fine. Callers that knowingly accept an unverifiable source pass require_checksum=False; the resulting entry carries verified=False and says so in format_zoo().

Every download is atomic, and never overwrites.

Bytes stream into a temporary file in the destination directory (so the final os.replace is a same-filesystem rename, which is atomic) and the rename happens only after the checksum passes. An interrupted or cancelled download therefore leaves nothing behind that looks like a model — the failure mode where half a checkpoint sits at the real filename, loads, and segments badly, cannot happen.

The destination is versioned rather than overwritten (versioned_path(): foo.CP_model, foo_v2.CP_model, …). Two models with the same filename are a normal thing to have; losing the first one to the second is not.

Provenance is recorded, and “unknown” is written out in full.

A Cellpose model fine-tuned on 60x confluent HeLa is not interchangeable with one trained on 20x sparse fibroblasts, and no amount of benchmark score makes it so. What a model was trained on is the single most useful thing the zoo can show, so ModelEntry carries trained_on and trained_by, both recovered from the settings snapshots spaCR already writes beside its models (<file>_settings.csv for a Cellpose model, <dst>/settings.csv for a classifier — read through spacr.train_compare.load_run(), which already knows where to look).

Where it could not be recovered the field reads 'unknown', never ''. A blank cell in a provenance table reads as “no constraints”; that is the opposite of what it means.

Benchmarks are only comparable inside one field set.

A model’s score on your three fields says nothing whatsoever about its score on somebody else’s, and a table that sorts the two together invents a ranking out of two unrelated numbers. So every BenchmarkResult records a fieldset_id() — a hash of the actual pixels, not the folder name — and rank() raises IncomparableBenchmarks when handed results from more than one field set. rank_groups() and format_benchmarks() are the supported alternative: they group by field set, rank within each group, and label the groups.

And a fifth, smaller one: a model file that is missing, empty, or not a torch checkpoint at all fails in inspect_checkpoint() with a message naming the file, before anything tries to load it. The default failure — a KeyError on a state-dict key from deep inside torch — names nothing the user chose.

What the benchmark can and cannot say¶

There is no ground truth here. benchmark() runs one model over N fields and reports what came out: object counts, timings and the spacr.seg_qc verdict per field (fused? shattered? empty? all on the border?). That is a quality-control score, not an accuracy — it can tell you a model collapsed on your data, it cannot tell you which of two plausible segmentations is right. RANK_KEYS therefore offers exactly two keys, 'qc' and 'seconds', and no key that would read as accuracy. To compare two models against each other, use compare_entries(), which hands both to spacr.model_compare.compare_models() — the A/B harness that is explicit about neither side being the truth.

Cellpose 4 accepts and ignores model_type, diam_mean, nchan, channels and rescale; only diameter at eval still changes the masks. BenchmarkResult carries the resolved honoured and ignored parameter dicts straight from spacr.model_compare.ModelConfig so a benchmark cannot silently be a benchmark of settings nothing read.

Example:

from spacr import model_zoo as zoo

entries = zoo.catalogue() + zoo.discover_local('/data/screen1')
print(zoo.format_zoo(entries))

entry = zoo.resolve('cpsam_plaque_r3', entries)
result = zoo.benchmark(entry, source='/data/screen1/plate1/1', n_fields=3)
print(zoo.format_benchmarks([result]))

Exceptions¶

`ChecksumMismatch`	What arrived is not what the catalogue published. Nothing was installed.
`DownloadCancelled`	The caller cancelled a fetch. Nothing was left at the destination.
`IncomparableBenchmarks`	Benchmarks from different field sets cannot be ranked against each other.
`ModelUnreadable`	A model file is missing, empty, or not a checkpoint. Names the file.
`ModelZooError`	Base class for every refusal in this module.

Classes¶

`BenchmarkResult`	One model over one field set. Only comparable to results on the same set.
`FieldBenchmark`	One field's result for one model.
`ModelEntry`	One model the zoo knows about, wherever it lives.

Functions¶

`benchmark`(→ BenchmarkResult)	Run one model over N fields and report what came out. "Test on 3 fields".
`bioimageio_entries`(→ List[ModelEntry])	Every Cellpose model bioimage.io publishes, as zoo rows.
`catalogue`(→ List[ModelEntry])	Everything the zoo knows about without scanning the user's disks.
`classify_kind`(→ Optional[str])	Say whether a file is a Cellpose model, a classifier, or not a model.
`community_entries`(→ List[ModelEntry])	Unvetted models uploaded by spaCR users, or an empty list.
`compare_entries`(entry_a, entry_b[, images, source, ...])	Put two zoo entries head to head on the same fields.
`config_for`(entry[, overrides])	The `spacr.model_compare.ModelConfig` that runs this entry.
`default_local_roots`(→ List[pathlib.Path])	Folders worth scanning when the caller has not named one.
`discover_local`(→ List[ModelEntry])	Find the model checkpoints already on this machine.
`download_bundled_models`(→ str)	Pull the bundled Hugging Face model pack via the existing downloader.
`entries_from_sources`(→ List[Any])	The rows belonging to the headings that are on, in the given order.
`entry_from_file`() → ModelEntry)	Build a `ModelEntry` for a checkpoint on this machine.
`fetch`(→ pathlib.Path)	Download a model, verify it, and only then put it where it belongs.
`fieldset_id`(→ str)	A stable id for a set of fields, taken from the pixels.
`format_benchmarks`(→ str)	Render benchmarks grouped by field set, ranked only within a group.
`format_zoo`(→ str)	Render a listing a human reads before choosing a model.
`group_by_fieldset`(→ Dict[str, List[BenchmarkResult]])	Bucket benchmarks by the field set they ran on, first-seen order.
`group_by_source`(→ Dict[str, List[Any]])	Split a listing into `ZOO_SOURCES`, keeping each source's order.
`hf_uri`(→ str)	The download URL for a file in a Hugging Face repo.
`inspect_checkpoint`(→ Dict[str, Any])	Check a file is a loadable checkpoint, failing with the filename in it.
`install`(→ ModelEntry)	`fetch()` the model and return the registered local entry.
`installable_backend_entries`(→ List[ModelEntry])	Every optional segmentation backend, in whatever state it is here.
`load_catalogue_file`(→ List[ModelEntry])	Read a JSON catalogue of remote models.
`open_uri`(→ Tuple[Iterable[bytes], int])	Open a model URI for streaming. `(chunks, total_bytes)`.
`package_model_root`(→ pathlib.Path)	`<spacr>/resources/models` — where the bundled pack lives.
`publish_model`() → Dict[str, Any])	Upload a model to Hugging Face and return its catalogue row.
`rank`(→ List[BenchmarkResult])	Order benchmarks best-first — within one field set only.
`rank_groups`(→ Dict[str, List[BenchmarkResult]])	Rank inside each field set, keeping the sets apart. The safe alternative.
`resolve`(→ ModelEntry)	Turn a key, a name or a path into a `ModelEntry`.
`scorecard_html`(→ str)	The model's scorecard as an HTML table, for a tooltip.
`sha256_file`(→ str)	Hex SHA-256 of a file, read in chunks so a 2 GB checkpoint is not RAM.
`shared_catalogue`(→ Tuple[ModelEntry, ...])	The community catalogue, fetched from `REMOTE_CATALOGUE_URI`.
`shared_catalogue_is_stale`(→ bool)	Whether `shared_catalogue()` would go to the network to answer.
`source_of`(→ str)	Which of `ZOO_SOURCES` this row belongs under.
`stock_cellpose_entries`(→ List[ModelEntry])	Every model the installed Cellpose can fetch for itself.
`verify`(→ bool)	Hash the file this entry points at and compare it to a known digest.
`versioned_path`(→ pathlib.Path)	The first free destination for `filename` in `dest`.