Cell typer

CellTyper combines a compatible single-cell reference with ALHENA's cell-annotation workflow. annotate() accepts either an H&E image plus nuclei or previously computed CellEmbeddings.

When previously encoded cells are supplied, the image encoder is not run again.

The image encoder is loaded only when needed

A CellTyper can annotate previously computed CellEmbeddings using only the compatible reference. UNI2-h weights and the encoder bundle are required only when H&E images still need to be encoded.

Preflight before a long run

CellTyper.preflight builds the same geometry report as describe_geometry, from shapes alone, and raises its notes as GeometryWarning before the forward pass starts. It also checks that the tiles and nuclei describe the same set of tiles, that a membership table maps its masks onto the canvas with the same geometry as the images, and that cell identifiers are integers or text. It evaluates geometry and input consistency without running the image encoder.

alhena.api.CellTyper

CellTyper(encoder, reference)

A labeled reference, and the encoder that projects cells into its space.

load_celltyper builds it. A typer built without an encoder loads one when first given tiles; any encoder is checked against the reference's cell space identity before it is kept.

Parameters:

Name	Type	Description	Default
encoder	AlhenaEncoder | None	An encoder, or None to load one when the typer is first given tiles.	required
reference	Reference	A reference as load_reference returns it.	required

Attributes:

Name	Type	Description
encoder	AlhenaEncoder | None	The adapted backbone and its projection heads, or None until it is loaded.
reference		The labeled reference cells the annotations are retrieved from.

Raises:

Type	Description
BundleError	If the encoder carries no cell head.
CellSpaceMismatchError	If the reference records no cell space, or not the encoder's.
ReferenceError	If the reference is malformed or does not fit the encoder.

axis property

axis

Class axis the reference is labeled on, and the cells are annotated on.

class_order property

class_order

Class names, in the order that indexes the columns of the mass.

cell_space_id property

cell_space_id

Identity of the space the reference lies in, which the encoder and cells must share.

load_encoder

load_encoder(progress=None)

Return the encoder, loading it the first time it is needed.

It is loaded with the arguments load_celltyper was given, or as the published encoder, and checked against the reference before it is kept.

Parameters:

Name	Type	Description	Default
progress	bool | None	Whether to announce on standard error that the UNI2-h weights are being read. None follows load_celltyper, then ALHENA_DISABLE_PROGRESS_BARS.	None

Returns:

Type	Description
AlhenaEncoder	The encoder.

Raises:

Type	Description
BackboneNotFoundError	If the UNI2-h weights cannot be located.
BundleError	If the bundle cannot be resolved, or carries no cell head.
CellSpaceMismatchError	If the encoder and the reference lie in different cell spaces.
ReferenceError	If the reference does not fit the encoder.

preflight

preflight(tiles, nuclei, mpp=None)

Describe the geometry the tiles and nuclei present, and warn about it.

Built from shapes alone, with no encoder, it checks the nuclei as annotate does. Tiles whose size is known only once they are read, as image files are, are checked by annotate instead.

Parameters:

Name	Type	Description	Default
tiles	TileInput	Raw uint8 RGB tiles, a tile source, or a batch already prepared for the model.	required
nuclei	NucleiInput	Label maps, the mapping an alhena.io reader of nuclei returns, or a membership table.	required
mpp	float | None	Microns per pixel of the tiles.	None

Returns:

Type	Description
GeometryReport	The field of view, the microns one token covers, and any geometry concern.

Raises:

Type	Description
AlhenaValueError	If mpp is out of range, or the tiles and the nuclei do not match.
GeometryError	If the nuclei of a tile are drawn on another pixel grid than the tile.
MembershipError	If a membership table is malformed or built at another resolution.

annotate

annotate(tiles, nuclei=None, mpp=None, *, cell_id=None, all_tiles=False, batch_size=None, k=DEFAULT_K, tau=DEFAULT_TAU, workers=None, progress=None)

Annotate every nucleus of a set of tiles, or every cell encoded earlier.

Given tiles and nuclei, it runs AlhenaEncoder.encode_cells, then retrieval, with the geometry and the nuclei checked before the encoder is loaded. Given the CellEmbeddings of an earlier run, it retrieves alone, against a reference in their cell space. The result carries the cells on cells; cells reaching no token are left out and counted on meta.

Parameters:

Name	Type	Description	Default
tiles	TileInput | CellEmbeddings	Raw uint8 RGB tiles, a tile source, or a batch already prepared for the model; or the CellEmbeddings of an earlier run.	required
nuclei	NucleiInput | None	Label maps, the mapping an alhena.io reader of nuclei returns, or a membership table. Needed with tiles, refused with cells.	None
mpp	float | None	Microns per pixel of the tiles, declared once for the images and the nuclei alike. Refused with cells, which record it.	None
cell_id	Sequence[Any] | ndarray | None	Unique identifier of each nucleus, for the builders that take positions rather than labels. Refused with cells.	None
all_tiles	bool	Read every tile, including those no cell is read from. Refused with cells.	False
batch_size	int | None	Tiles per forward pass, which bounds the memory the pass holds; 32 when not given. Refused with cells.	None
k	int	Number of reference neighbors each cell votes over.	DEFAULT_K
tau	float	Softmax temperature over neighbor similarities.	DEFAULT_TAU
workers	int | None	Threads retrieving neighbors at once. None uses the processors available, at most MAX_DEFAULT_WORKERS. The annotations are the same for any number.	None
progress	bool | None	Whether to report progress on standard error. None follows ALHENA_DISABLE_PROGRESS_BARS.	None

Returns:

Type	Description
AnnotationResult	The annotations, their mass, confidence and entropies, with the provenance of the run on
AnnotationResult	meta and the cell embeddings on cells.

Raises:

Type	Description
AlhenaValueError	If an argument is invalid for the input, or the nuclei cannot be read.
BackboneNotFoundError	If the UNI2-h weights are needed and cannot be located.
BundleError	If the encoder has to be loaded and its bundle cannot be resolved.
CellSpaceMismatchError	If the cells or encoder are not in the reference's cell space.
GeometryError	If the nuclei of a tile are drawn on another pixel grid than the tile.
MembershipError	If the nuclei and the tiles cannot be reconciled.

alhena.api.load_encoder

load_encoder(*, bundle=None, backbone=None, device=None, cache_dir=None, merge=False, progress=None)

Load the released encoder.

Parameters:

Name	Type	Description	Default
bundle	str | Path | None	Directory holding the bundle files, or a repository owner/name. Defaults to the published repository.	None
backbone	str | Path | None	The UNI2-h weight file, or a directory holding one. Looked for in ALHENA_BACKBONE and the Hugging Face cache when omitted.	None
device	str | device | None	Device to run on, such as "cpu", "cuda", or "mps" for the GPU of an Apple silicon Mac. Defaults to CUDA where available, the processor otherwise.	None
cache_dir	str | Path | None	Directory the bundle is downloaded into.	None
merge	bool	Fold the adapters into the fused weights instead of inserting them as modules; the forward pass then agrees with the published one to float32 rounding.	False
progress	bool | None	Whether to announce on standard error that the UNI2-h weights are being read. None follows ALHENA_DISABLE_PROGRESS_BARS.	None

Returns:

Type	Description
AlhenaEncoder	The encoder, on the resolved device.

Raises:

Type	Description
AlhenaValueError	If device names no device this machine has.
BackboneNotFoundError	If the UNI2-h weights cannot be located.
BundleError	If the bundle cannot be resolved, is incomplete or fails its digest checks.

alhena.api.load_celltyper

load_celltyper(tissue=None, reference=None, axis=None, *, encoder=None, bundle=None, backbone=None, device=None, cache_dir=None, merge=False, progress=None)

Load a reference, and pair it with the encoder into a cell typer.

The reference is loaded now, the encoder only when the typer is first given tiles, with the arguments load_encoder takes.

Parameters:

Name	Type	Description	Default
tissue	str | None	Tissue whose prebuilt reference is loaded: one of TISSUE_TO_SHARD, an alias TISSUE_ALIASES declares for one, or a shard name.	None
reference	Reference | str | Path | None	An already-loaded reference, or the path of a shard, instead of a tissue.	None
axis	str | None	Class axis the cells are annotated on: a declared axis, or one a shard given as reference was built on. A loaded reference's own when None, else DEFAULT_AXIS.	None
encoder	AlhenaEncoder | None	An encoder already loaded, checked against the reference at once, instead of bundle, backbone, device and merge.	None
bundle	str | Path | None	Directory holding the bundle files, or a repository owner/name, as load_encoder takes it.	None
backbone	str | Path | None	The UNI2-h weight file, or a directory holding one, as load_encoder takes it.	None
device	str | device | None	Device the encoder runs on, as load_encoder takes it.	None
cache_dir	str | Path | None	Directory the reference and the bundle are downloaded into.	None
merge	bool	Fold the adapters into the fused weights, as load_encoder does.	False
progress	bool | None	Whether to report progress on standard error while the reference loads, and later while the encoder does. None follows ALHENA_DISABLE_PROGRESS_BARS.	None

Returns:

Type	Description
CellTyper	A cell typer holding the reference, and the encoder where one was given.

Raises:

Type	Description
AlhenaValueError	If no tissue or reference is given, or an argument is invalid.
CellSpaceMismatchError	If the reference records no cell space, or not the encoder's.
ReferenceError	If the reference cannot be loaded or does not fit the encoder.

The forms tiles and nuclei take are TileInput and NucleiInput, on Types.

load_encoder finds the UNI2-h weights with find_backbone, and both loaders download into the directory cache_root returns.

alhena.hub.find_backbone

find_backbone(backbone=None)

Return the path of the UNI2-h weight file.

The weights are looked for at backbone, then at ALHENA_BACKBONE, either naming a file or a directory holding one, then in the model hub cache: HF_HUB_CACHE, else HF_HOME/hub, with HF_HOME defaulting to XDG_CACHE_HOME/huggingface, then ~/.cache/huggingface. A named location holding no weights is reported, not passed over.

Parameters:

Name	Type	Description	Default
backbone	str | Path | None	Path of the weight file, or of a directory holding it.	None

Returns:

Type	Description
Path	The path of the weight file.

Raises:

Type	Description
BackboneNotFoundError	If no location holds the weights.

alhena.hub.cache_root

cache_root(cache_dir=None, create=True)

Return the directory downloaded artifacts are cached in.

The first of cache_dir, ALHENA_CACHE and XDG_CACHE_HOME/alhena that is set, else a per-user cache directory.

Parameters:

Name	Type	Description	Default
cache_dir	str | Path | None	Directory to use, overriding the environment.	None
create	bool	Create the directory and its parents when they do not exist.	True

Returns:

Type	Description
Path	The cache directory.

Raises:

Type	Description
AlhenaError	If the directory has to be created and cannot be.

---

Next: Reading data