Histopia treats a stale cache as worse than a slow fit

Serial sections, aligned and rebuilt in three dimensions

Histopia is computational research software for serial-section histology and proteomic image analysis, which is a narrower and stranger problem than it first sounds.

A serial section is a thin slice of tissue, and studying one specimen properly means you have many slices, each imaged separately, each slightly different from its neighbour. The five capabilities the project lists are the five things you need before any of that becomes data: reviewed inter-section alignment, group-aware tissue masking, global morphology segmentation, spatial topology, and interactive 3D reconstruction across the sections.

Every one of those has a review step attached, which is the through-line of the software. Alignment is reviewed, section orientation and order are reviewed, and registration and semantic results are fingerprinted and explicitly review-gated.

The package is on PyPI, there is a QuPath extension, and there is an interactive presentation demo hosted on GitHub Pages with separate views for registration and for a cellular protein atlas. The repository's recent release tags are all versions of that demo, which tells you where the visible work has been going.

Six extras and a base install with two dependencies

The base install is deliberately small. A plain pip install of the package brings in only two dependencies, a packaging library and a TOML reader for older Python versions. The heavy science stacks arrive only when you ask for them:

pip install histopia

There are six extras, one per workflow: registration and whole-slide imaging, semantic, topology, stain, a feature extractor called uni2h, and qupath. You can combine them in one specifier or install them one at a time, which matters because the stain extra pulls in an image-processing stack, the whole-slide extra pulls in libvips bindings, and the topology extra pulls in an image-segmentation library.

For anything meant to be reproduced exactly, the project points at checked-in constraint files rather than at version ranges, documented in a dependency management page. That is the difference between a set of lower and upper bounds, which let a patch release change your numbers, and pinned versions that do not.

The package metadata records the state honestly: version 0.1.0, an alpha development status, and Python 3.10 through 3.13 as the supported classifiers.

A cache is only reusable if five things still match

The caching rules are the most opinionated part of the design, and they exist because a reused result that is subtly wrong is worse than no result.

Registration ordering and viewer assets use exact, checksummed caches. Semantic fitting is stricter: a fitted result is reused only when it is fully sealed and its feature contents, slide order, scientific controls, algorithm revision and numerical runtime all match what the current run would produce.

Then there is invalidation. Any change to reviewed masks, geometry, orientation, transforms, semantic labels or encoding settings invalidates the affected cache. In practice that means fixing one reviewed mask throws away work downstream of it, which is inconvenient and correct.

Because a long fit is expensive, there is an explicit override for the case where you know the inputs have not changed but you want a new fit anyway, such as after benchmarking or algorithm development. That flag is the counterpart to the sealing: the system will not quietly redo the work, and it will not quietly keep it either.

The philosophy is consistent with the rest of the package, where a workflow is only as good as the evidence that it ran as configured.

The audit report separates approved from pending

Before a cohort is published or consumed downstream, the project asks you to audit it, and the design of that command is the clearest statement of its values.

The audit takes the four runs that make up a cohort, registration, semantic, stain and topology, plus the viewer manifest, and produces a path-free report:

histopia-visualize audit \
  --run sample=/path/to/registration-run \
  --semantic-run sample=/path/to/semantic-run \
  --stain-run sample=/path/to/stain-run \
  --topology-run sample=/path/to/topology-run \
  --viewer-manifest /path/to/viewer/manifest.json

Path-free matters for a report meant to be circulated: it distinguishes approved results, explicit review gates, missing stages and integrity failures without embedding machine-specific paths in the evidence.

Two scoping rules appear in the report. Stain approval is family-scoped, so approval does not silently leak from one stain family to another. And topology is bound to the exact registration and semantic results it was computed from, so a topology result cannot be presented alongside a re-run registration.

Publishing is split along the same line. Stable viewer builds publish approved results only, while a separate review command generates a review hub containing the pending registration, 3D, semantic and stain evidence. And the project is explicit that its public demo site includes both approved and visibly identified review-stage demonstration cohorts, and is not a production release manifest.

Compute settings are flags, not config edits

Long jobs in this package can be moved between machines without editing their scientific configuration, which is the difference between a run you can reproduce and one you can only hope matches.

Feature extraction accepts a device setting with several forms: automatic selection, CPU, CUDA, a specific CUDA device by index, or the Apple Metal backend. Notably, none of this requires importing the deep learning framework when the base package is imported, so a machine without it can still install and use the rest of the toolchain.

Before committing to a long extraction, there is a doctor command that reports the active machine for a given device, and the QuPath integration has its own doctor with a workflow selector and a minimum API level to require.

The extraction command takes batch size, patch worker count and libvips thread count as flags, and the fit command takes a fit thread count, plus the override flag for forcing a fresh fit. Registration exposes its own bounded controls for thumbnails, masks, ordering, rigid pairs, quality control and native libvips workers, so nothing has to be tuned by editing a configuration file.

Semantic atlases, topology surfaces and stain density

The semantic workflow fits morphology regions globally with a foundation-style feature extractor, applies a guarded slide correction so a staining difference between slides does not shift the regions, evaluates the number of regions automatically rather than making you fix it by hand, and carries topology across sections.

The topology layer is where the physics becomes explicit. It works from registered tissue envelopes and produces two kinds of semantic surface, a confidence-core version and an exhaustive selected-region version, and validates reconstruction on held-out data. It also requires explicit physical spacing in the z direction, which sounds pedantic until you realise that an arbitrary scale makes any depth measurement meaningless.

Connected volumes are reviewed with uncertainty in view rather than presented as a single answer, which is the honest treatment of a segmentation that could plausibly be joined two ways.

Stain profiling is separate and operates in source space. It measures relative optical density for four stains, H-DAB, Sirius Red, PAS and Alcian Blue, each with guarded background correction, meaning the background is estimated defensively rather than subtracted optimistically.

QuPath runs the same jobs from inside the viewer

The QuPath integration is not a thin script that calls the library from outside; it launches the real workflows from inside the image viewer, against a specific extension release for QuPath 0.7.

What it adds is provenance and integration. Registration and semantic jobs are launched from the extension rather than by hand. Workflow integrity audits fail closed, meaning an unverifiable state stops the job instead of producing output nobody can account for. Regions are written as compact checksummed GeoJSON, so a region file can be checked for tampering rather than merely opened. Region count selection is dynamic rather than fixed in advance, and coordinates stay in the native whole-slide image space instead of being rescaled into something convenient.

Taken with the audit command and the sealed caches, the picture is consistent: the package is built for a lab where a figure has to be traceable to a reviewed input, a recorded configuration and an unbroken chain of caches, months apart. That is a narrower goal than being easy, and for this particular problem it is the right one.

The stated limits are equally clear: the project remains research software, and its current validation does not establish clinical use, cell-level correspondence, or conformance to final OME metadata.

Editorial conclusion

Histopia fits a lab that cuts serial sections, runs several modalities over them, and needs to know which results a reviewer has actually signed off before a figure reaches a paper. It does not fit a clinical deployment, because the project states plainly that its validation does not establish clinical use or cell-level correspondence. Before you rely on it, read the audit output rather than the demo, since the public demo site deliberately includes review-stage cohorts and is not a release manifest, and keep the constraint files for anything you intend to reproduce.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. oncologylab/histopia on GitHub
3. Project website
4. README
5. Releases