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.

Scope¶

spaCR can run a stock Cellpose model, a fine-tuned Cellpose model, a classifier checkpoint from a training run, or a checkpoint downloaded from Hugging Face. Three questions follow for any machine: which of those models are on it, what each one was trained on, and whether the copy on disk is the file the author published.

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.

Safeguards¶

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, whatever their benchmark scores. ModelEntry therefore 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 does not predict its score on somebody else’s, and a table that sorts the two together produces a ranking 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.

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`	Downloaded bytes do not match the published digest; nothing was installed.
`DownloadCancelled`	Raised when the caller cancels a fetch; nothing is 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`	Record of one model: its location, checksum and provenance.

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, ...])	Compare two zoo entries on the same fields.
`config_for`(entry[, overrides])	The `spacr.model_compare.ModelConfig` that runs this entry.
`default_local_roots`(→ List[pathlib.Path])	Default folders to scan for models when the caller names none.
`default_version_index`(→ int)	Which version a model family's row opens on.
`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_repo_of`(→ str)	The `owner/repo` a Hugging Face download URL points into, or `''`.
`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.
`is_alternative`(→ bool)	Whether a row is a published alternative rather than a default.
`is_spacr_owned`(→ bool)	Whether a row's file lives in a repository owned by the einarolafsson account.
`is_third_party`(→ bool)	Whether a row is a published model that spaCR did not train.
`load_catalogue_file`(→ List[ModelEntry])	Read a JSON catalogue of remote models.
`mitonet_instances`(→ numpy.ndarray)	Turn MitoNet's three output heads into labelled mitochondria.
`mitonet_weights`(→ pathlib.Path)	The MitoNet v1 mini weights on this machine, downloaded on first use.
`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.
`resolve`(→ ModelEntry)	Turn a key, a name or a path into a `ModelEntry`.
`scorecard_export_rows`(→ List[Dict[str, Any]])	Every model's scorecard as long-format rows, one per metric.
`scorecard_html`(→ str)	The model's scorecard as an HTML table, for a tooltip.
`scorecard_state`(→ str)	How far a model's scorecard has come, as one word.
`scorecard_state_text`(→ str)	The sentence a spaCR model's tooltip and card give for an unfinished scorecard.
`segment_mitonet`(→ numpy.ndarray)	Segment the mitochondria of a TEM image with MitoNet v1 mini.
`sha256_file`(→ str)	Hex SHA-256 of a file, read in chunks so the whole file is never in memory.
`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`.