Types

The objects ALHENA hands back. Three are the analytical results:

Type	One row is	Returned by	Explained on
TileEmbeddings	a tile	encode_tiles	Tile embeddings
CellEmbeddings	a cell	encode_cells	Cell embeddings
AnnotationResult	a cell with its reference-based annotation	annotate	Cell annotations

The others describe geometry, references, scores and inputs. Every class here is a dataclass, so a result can be read field by field, and every field is documented below.

Geometry metadata

ResampleInfo, GeometryReport, and TileEmbeddings expose pad_fraction and crop_fraction, which summarize how input fields were fitted to the model canvas. See Geometry.

Tile spatial metadata

TileEmbeddings records the encoding geometry and the encoder identity. When tile coordinates are available, it also records spatial bounds, centers, and the coordinate frame, with its physical scale when the resolution is declared. purpose distinguishes dedicated tile-level results from tile embeddings generated as cell context.

Cell provenance

CellEmbeddings records the encoder identity, cell_space_id, image geometry, membership provenance, and spatial positions when available. This allows saved cells to be annotated later without rerunning the image encoder. AnnotationResult.cells retains the cells used for the annotation.

alhena.types.TileEmbeddings dataclass

TileEmbeddings(embeddings, tile_index, tile_ids, geometry=None, encoder_id=None, purpose='tiles', bounds=None, bounds_frame=None, bounds_mpp=None, image_shape=None, backbone_digest=None)

Tile embeddings, with where in its source image each tile was read from.

bounds is the region of the source image each embedding stands for, in the frame the tiles were cut from, and None where the tiles share no frame. geometry says what happened to a tile on its way to the canvas, padded or cropped, and purpose what it was read for.

Attributes:

Name	Type	Description
embeddings	ndarray	One embedding per tile read, (n_tiles_read, embed_dim) float32, not normalized.
tile_index	ndarray	Index of each of those tiles among the tiles given, ascending.
tile_ids	tuple[str, ...]	Name of each of those tiles, as the tile source names it, or its position.
geometry	ResampleInfo | None	What preprocessing did to reach the canvas, as prepare_tiles records it over the tiles read, or None where the tiles arrived prepared or none was read.
encoder_id	str | None	Identity of the encoder that produced the embeddings, or None where unknown.
purpose	str	What the tiles were read for, one of TILE_PURPOSES.
bounds	ndarray | None	Spatial bounds of each tile, (n_tiles_read, 4) holding x0, y0, x1, y1, upper bounds excluded, in the pixels of the frame the tiles were cut from.
bounds_frame	str | None	Name of the frame bounds is written in, as the tile source names its origins, such as "slide.svs, level 0" or "tile origins". None where unknown.
bounds_mpp	float | None	Microns one pixel of that frame spans, so bounds * bounds_mpp is in microns. None where there are no bounds or no declared resolution.
image_shape	tuple[int, int] | None	Height and width of the image the tiles were cut from, in the pixels of that frame, or None for tiles that arrive already cut.
backbone_digest	str | None	Digest of the UNI2-h model weights the embeddings were produced with, as BundleInfo.backbone_digest records it, or None where unknown.

pad_fraction property

pad_fraction

Largest share of the canvas filled with white pad, or None where it is not recorded.

crop_fraction property

crop_fraction

Largest share of a field the center crop discarded, or None where it is not recorded.

mpp property

mpp

Microns per pixel the tiles were declared at, None where undeclared or unrecorded.

centers property

centers

Center of each tile, (n_tiles_read, 2), x then y in the frame of bounds, or None.

The mean of the tile's pixel centers, which lie at whole coordinates as for cell positions.

to_anndata

to_anndata()

Return the tiles as an AnnData table, one row per tile.

The layout is the one alhena.io describes, and alhena.io.read_tile_embeddings reads it back.

Raises:

Type	Description
AlhenaValueError	If the arrays disagree in length.

write_h5ad

write_h5ad(path)

Write the tiles to an .h5ad file, with their spatial bounds and their provenance.

Parameters:

Name	Type	Description	Default
path	str | Path	File to write. An existing file is replaced.	required

Raises:

Type	Description
AlhenaValueError	If the path does not end in .h5ad, or to_anndata refuses them.

to_spatialdata

to_spatialdata(sdata=None, shapes_key=None, table_key=None, image_key=None, overwrite=False)

Return the tiles as a SpatialData object: one rectangle and one row per tile.

Without sdata the object holds the rectangles and the table alone. As in alhena.spatial.tiles_to_spatialdata, the rectangles take the transformations of the image the tiles were cut from where sdata holds it, and the identity in alhena.spatial.DEFAULT_COORDINATE_SYSTEM otherwise.

Parameters:

Name	Type	Description	Default
sdata	Any | None	Object the rectangles and the table are added to, or None to build one.	None
shapes_key	str | None	Name the rectangles are stored under, or None for the default alhena.spatial.tiles_to_spatialdata declares.	None
table_key	str | None	Name the table is stored under, or None for that call's default.	None
image_key	str | None	Image of sdata the tiles were cut from. Defaults to the image of sdata their bounds are written in.	None
overwrite	bool	Replace elements already stored under those names.	False

Returns:

Type	Description
Any	The object, with the rectangles and the table in it.

Raises:

Type	Description
AlhenaValueError	If the tiles lack bounds, a name is taken, or image_key is wrong.
MissingExtraError	If the spatial extra is not installed.

select

select(keep)

Return the tiles keep selects, every array cut alike and the provenance as recorded.

Parameters:

Name	Type	Description	Default
keep	Any	A boolean mask, one entry per tile, or the positions of the tiles to keep, in the order they are kept in.	required

Returns:

Type	Description
TileEmbeddings	The tiles kept, with the geometry and the provenance of the run that read them.

Raises:

Type	Description
AlhenaValueError	If a mask does not fit, or a position repeats or is out of range.

locate

locate(cells)

Name the tile whose region holds each cell, wherever the cells were encoded.

A region runs from the first pixel of a tile's bounds to its last, pixel centers at integer coordinates, as alhena.viz.tile_regions draws it. Where regions overlap, the tile whose center lies nearest holds the cell. The frames of the tiles and of the cells must agree where both are recorded.

Parameters:

Name	Type	Description	Default
cells	Any	CellEmbeddings, the AnnotationResult carrying them, a table of cells ALHENA wrote, or an (n_cells, 2) array of x and y in the frame of bounds.	required

Returns:

Type	Description
ndarray	The name of each cell's tile, as tile_ids names it, in the order of the cells; None
ndarray	for a cell outside every tile.

Raises:

Type	Description
AlhenaValueError	If the tiles lack bounds, the cells positions, or their frames differ.

alhena.types.CellEmbeddings dataclass

CellEmbeddings(cell_id, backbone, cell_space, alpha, tile_index, n_candidate_tiles, valid, encoder_id=None, cell_space_id=None, geometry=None, membership_source=None, membership_approximate=None, n_cells_without_tokens=None, centroids=None, centroids_frame=None, centroids_mpp=None, tiles=None, backbone_digest=None)

Cell embeddings pooled from tile tokens, with the provenance needed to annotate them later.

AlhenaEncoder.encode_cells fills every field; pool_cells fills those a membership table records and leaves the others None.

Attributes:

Name	Type	Description
cell_id	ndarray	Identifier of each cell, in the order of every other array here.
backbone	ndarray	Pooled pre-projection cell embeddings, (n_cells, embed_dim).
cell_space	ndarray | None	Embeddings after the cell projection, (n_cells, cell_dim), or None when the bundle carries no cell head.
alpha	ndarray	Nucleus pixels supporting each cell in the tile it was read from.
tile_index	ndarray	Index of the tile each cell was read from.
n_candidate_tiles	ndarray	How many tiles contained the nucleus.
valid	ndarray	False where the embedding is unusable and no label may be emitted.
encoder_id	str | None	Identity of the encoder that produced the embeddings, or None where unknown.
cell_space_id	str | None	Identity of the space cell_space lies in, or None where unknown; only a reference of the same identity annotates the cells.
geometry	GeometryReport | None	The geometry the tiles presented to the model, as describe_geometry reports it, or None where unknown.
membership_source	str | None	Kind of nucleus input the membership was built from: labels, centroids, polygons, or unknown for a table assembled by hand.
membership_approximate	bool | None	Whether the pooling weights approximate the nucleus shape, or None where the membership records no provenance.
n_cells_without_tokens	int | None	Nuclei of the input that reached no token and so have no row here, or None where the membership records no set of input cells.
centroids	ndarray | None	Position of each nucleus, (n_cells, 2) x then y in the pixels of the frame the tiles share, pixel centers at integer coordinates; None without a shared frame.
centroids_frame	str | None	Name of that frame, such as "slide.svs, level 0", "tile origins" or "polygons". None where unknown.
centroids_mpp	float | None	Microns one pixel of that frame spans, so centroids * centroids_mpp is in microns. None where no position or no resolution is recorded.
tiles	TileEmbeddings | None	Embeddings of the tiles read in the same pass, recording purpose="cell_context", or None.
backbone_digest	str | None	Digest of the UNI2-h model weights the embeddings were produced with, as BundleInfo.backbone_digest records it, or None where unknown.

mpp property

mpp

Microns per pixel the tiles were declared at, None where undeclared or unknown.

to_anndata

to_anndata()

Return the cells as an AnnData table, one row per cell.

The layout is the one alhena.io describes, and alhena.io.read_cells reads it back. alhena.io.add_annotation adds the annotations made from the cells to it.

Raises:

Type	Description
AlhenaValueError	If the arrays disagree, or an identifier is neither integer nor text.

write_h5ad

write_h5ad(path)

Write the cells to an .h5ad file, with the provenance needed to annotate them later.

Parameters:

Name	Type	Description	Default
path	str | Path	File to write. An existing file is replaced.	required

Raises:

Type	Description
AlhenaValueError	If the path does not end in .h5ad, or to_anndata refuses them.

to_spatialdata

to_spatialdata(sdata, region, table_key=None, overwrite=False)

Write the cells into a SpatialData object, as the table of the element of their nuclei.

alhena.spatial.cells_to_spatialdata with its default columns. The annotations of the cells are added to the same table later, by AnnotationResult.to_spatialdata.

Parameters:

Name	Type	Description	Default
sdata	Any	The object the table is stored in, holding the element of the nuclei.	required
region	str	Element the table annotates, whose instances the cell identifiers name.	required
table_key	str | None	Name the table is stored under, or None for that call's default.	None
overwrite	bool	Replace a table of cells already stored under that name.	False

Returns:

Type	Description
AnnData	The table of cells, stored in the object.

Raises:

Type	Description
AlhenaValueError	If the identifiers are not of the element, or the name is taken.
MissingExtraError	If the spatial extra is not installed.

select

select(keep)

Return the cells keep selects, every array cut alike and the provenance as recorded.

Parameters:

Name	Type	Description	Default
keep	Any	A boolean mask, one entry per cell, or the positions of the cells to keep, in the order they are kept in.	required

Returns:

Type	Description
CellEmbeddings	The cells kept, with the tiles read and the provenance of the run that encoded them.

Raises:

Type	Description
AlhenaValueError	If a mask does not fit, or a position repeats or is out of range.

alhena.types.AnnotationResult dataclass

AnnotationResult(cell_id, labels, confidence, mass, class_order, class_entropy, neighbor_entropy, neighbor_similarity, valid, axis, meta=dict(), cells=None)

Cell-type annotations and their supporting quantities.

Attributes:

Name	Type	Description
cell_id	ndarray	Identifier of each cell, in the order of every other array here.
labels	ndarray	Predicted class name, empty string where no annotation was assigned.
confidence	ndarray	Mass the winning class received, between 1 / n_classes and 1; NaN where no annotation was assigned.
mass	ndarray	Per-class mass, shape (n_cells, n_classes). Each row sums to one, and is NaN where no annotation was assigned.
class_order	tuple[str, ...]	Class names indexing the columns of mass.
class_entropy	ndarray	Entropy of the per-class mass.
neighbor_entropy	ndarray	Entropy of the neighbor weights.
neighbor_similarity	ndarray	Cosine similarity of each retrieved neighbor.
valid	ndarray	False where no annotation was assigned.
axis	str	Class axis the reference was labeled on.
meta	dict[str, Any]	Provenance of the annotation, such as k, tau, the cell space identity, the class support of the reference and the median effective number of neighbors.
cells	CellEmbeddings | None	The cell embeddings the annotations were made from, in the same order, as CellTyper.annotate attaches them; None from annotate_cells until they are set.

missing_classes property

missing_classes

Classes of the axis the reference held no cell of, as meta records them, or none.

to_anndata

to_anndata(name=None)

Return the annotations and the cells they were made from as an AnnData table.

It is the table CellEmbeddings.to_anndata returns, with the annotation added under name as alhena.io.add_annotation adds it: on the default axis, alhena_celltype_lineage_v1. alhena.io.read_annotations reads it back.

Parameters:

Name	Type	Description	Default
name	str | None	Name the fields of the annotation carry, the axis of the annotations by default.	None

Raises:

Type	Description
AlhenaValueError	If no cells, or other cells, are attached, or the name is unusable.

write_h5ad

write_h5ad(path, name=None)

Write the annotations, the cells they were made from and both provenances to .h5ad.

Parameters:

Name	Type	Description	Default
path	str | Path	File to write. An existing file is replaced.	required
name	str | None	Name the fields of the annotation carry, the axis of the annotations by default.	None

Raises:

Type	Description
AlhenaValueError	If the path does not end in .h5ad, or to_anndata refuses them.

to_spatialdata

to_spatialdata(sdata, region, table_key=None, name=None, overwrite=False)

Write the annotations into the table of cells of the element their nuclei came from.

alhena.spatial.cells_to_spatialdata with its default columns: the first call creates the table, and a later one adds its annotation to it.

Parameters:

Name	Type	Description	Default
sdata	Any	The object the table is stored in, holding the element of the nuclei.	required
region	str	Element the table annotates, whose instances the cell identifiers name.	required
table_key	str | None	Name the table is stored under, or None for that call's default.	None
name	str | None	Name the fields of the annotation carry. Defaults to the axis of the annotations.	None
overwrite	bool	Replace the annotation the table holds under name, and that one alone.	False

Returns:

Type	Description
AnnData	The table of cells, stored in the object, with the annotation in it.

Raises:

Type	Description
AlhenaValueError	If the cells are missing or not of the element, or the name is taken.
MissingExtraError	If the spatial extra is not installed.

to_frame

to_frame()

Return the annotations as a table, one row per cell.

The table holds the identifier, the predicted class, the confidence, both entropies, the validity flag and one mass_<class> column per class, and, where the cells are attached, what each records apart from its embeddings.

Raises:

Type	Description
AlhenaValueError	If the attached cells are not those the annotations describe.

select

select(keep)

Return the annotations of the cells keep selects, with those cells attached.

Every per-cell array is cut alike. meta is kept as recorded, so its counts describe the run that made the annotations, not the cells kept.

Parameters:

Name	Type	Description	Default
keep	Any	A boolean mask, one entry per cell, or the positions of the cells to keep, in the order they are kept in.	required

Returns:

Type	Description
AnnotationResult	The annotations kept, on the same axis and class order.

Raises:

Type	Description
AlhenaValueError	If a mask does not fit, or a position repeats or is out of range.

alhena.types.TILE_PURPOSES module-attribute

TILE_PURPOSES = ('tiles', 'cell_context')

What a set of tile embeddings was read for: tiles or cell_context.

alhena.types.BundleInfo dataclass

BundleInfo(encoder_id, cell_space_id, backbone, embed_dim, cell_dim, lora_rank, lora_alpha, input_size, patch_size, reference_mpp, image_mean, image_std, interpolation, has_image_proj, has_cell_proj, scconcept_model, scconcept_version, version, backbone_digest=None)

Identity and geometry of an encoder bundle.

Attributes:

Name	Type	Description
encoder_id	str	Identity of the encoder: the first sixteen hexadecimal digits of the SHA-256 of the adapter file.
cell_space_id	str	Identity of the cell space the cell and reference heads project into, which a reference must record to annotate the encoder's cells.
backbone	str	Repository of the UNI2-h weights the adapters were trained on.
embed_dim	int	Width of the backbone's tokens and embeddings.
cell_dim	int	Width of the shared cell space.
lora_rank	int	Rank of the low-rank adapters.
lora_alpha	float	Scaling of the adapters, whose updates are multiplied by lora_alpha / lora_rank.
input_size	int	Side of the canvas the encoder reads, in pixels.
patch_size	int	Side of one token, in pixels of the canvas.
reference_mpp	float	Microns per pixel the encoder reads, to which tiles of a declared resolution are resampled.
image_mean	tuple[float, float, float]	Mean of each color channel, subtracted from a tile on the unit scale.
image_std	tuple[float, float, float]	Standard deviation of each color channel, which the centered tile is divided by.
interpolation	str	Interpolation tiles are resampled with.
has_image_proj	bool	Whether the bundle carries the tile head, image_proj.
has_cell_proj	bool	Whether it carries both heads of the cell space, img_tok_proj and st_node_proj.
scconcept_model	str	Single-cell model the reference embeddings come from.
scconcept_version	str	Version of that model.
version	str	Version of ALHENA the bundle states it was published for, else this one.
backbone_digest	str | None	SHA-256 of the UNI2-h tensors, each read as float32 in the order of their names, so either file they are distributed in gives one digest; None where not computed.

alhena.types.ResampleInfo dataclass

ResampleInfo(source_mpp, target_mpp, scale, source_size, resampled_size, pad_fraction, crop_fraction, padded, cropped, mpp_declared)

What preprocessing did to a batch of tiles to reach the model input geometry.

Attributes:

Name	Type	Description
source_mpp	float | None	Microns per pixel the tiles were declared at, or None where none was.
target_mpp	float	Microns per pixel the tiles were resampled toward.
scale	float	Factor the tiles were resized by, one where they passed through untouched.
source_size	tuple[int, int]	Height and width of the tiles as they arrived; for tiles of several sizes, those of the tile that padded most, else cropped most, else the first.
resampled_size	tuple[int, int]	Height and width that same tile reached before being fitted to the canvas.
pad_fraction	float	Share of the canvas filled with pad rather than the image, over the tile that padded most. Zero where nothing was padded.
crop_fraction	float	Share of the resampled tile the center crop discards, over the tile that lost most, whichever tile the sizes describe. Zero where nothing was cropped.
padded	bool	Whether any tile was padded.
cropped	bool	Whether any tile was cropped.
mpp_declared	bool	Whether a resolution was declared for the tiles.

alhena.types.GeometryReport dataclass

GeometryReport(mpp, tile_size_px, field_of_view_um, token_footprint_um, reference_mpp, mpp_ratio, median_nucleus_tokens, pad_fraction=0.0, crop_fraction=0.0, warnings=())

Physical geometry a batch of tiles presents to the model.

Attributes:

Name	Type	Description
mpp	float | None	Microns per pixel of the tiles, or None where none was declared.
tile_size_px	int	Side of the tiles, in pixels.
field_of_view_um	float	Microns one tile covers, NaN where the resolution is undeclared.
token_footprint_um	float	Microns one token covers on the canvas.
reference_mpp	float	Microns per pixel the model reads at.
mpp_ratio	float | None	Ratio of mpp to reference_mpp, None where the resolution is undeclared.
median_nucleus_tokens	float | None	Side of a typical nucleus, in tokens.
pad_fraction	float	Share of the canvas the tiles pad with white; zero where the resolution is undeclared, as tiles are then resized to the canvas.
crop_fraction	float	Share of each field the center crop discards; zero where the resolution is undeclared.
warnings	tuple[str, ...]	Concerns the geometry raises, one or a few sentences each.

alhena.types.ReferenceInfo dataclass

ReferenceInfo(name, axis, cell_space_id, n_cells, n_scored_cells, class_order, class_support, source, license, scconcept_model, scconcept_version, coverage_verified=False)

Name, cell space, provenance and class support of a reference shard, on one class axis.

Attributes:

Name	Type	Description
name	str	Name of the shard.
axis	str	Class axis the support is counted on.
cell_space_id	str	Identity of the cell space the shard was projected into, or undeclared.
n_cells	int	Rows of the shard, whether or not they carry a class of the axis.
n_scored_cells	int	Rows carrying a class of the axis, which form the retrieval pool.
class_order	tuple[str, ...]	Classes of the axis, in the order that fixes their codes.
class_support	dict[str, int]	Reference cells of each class, in class order.
source	str	Where the atlas comes from, as the shard or the registry beside it records it, or undeclared.
license	str	Terms the atlas is distributed under, recorded likewise, or undeclared.
scconcept_model	str	Single-cell model the embeddings of the shard come from, or undeclared.
scconcept_version	str	Version of that model, or undeclared.
coverage_verified	bool	Whether the shard stamps the class support of the axis, found equal to the one its labels give; a stamp that differs is refused.

missing_classes property

missing_classes

Classes of the axis the reference holds no cell for.

thin_classes property

thin_classes

Classes the reference supports too thinly for retrieval to be reliable.

alhena.types.SelfCheckReport dataclass

SelfCheckReport(reference, axis, k, tau, macro_f1, accuracy, per_class_recall, similarity_quantiles, n_cells_evaluated, warnings=())

Leave-one-out retrieval of a reference against itself.

A reference that cannot recover its own labels under the default operator cannot support annotation from images. A reference that can is not thereby shown to support it.

Attributes:

Name	Type	Description
reference	str	Name of the reference checked.
axis	str	Class axis its labels are read on.
k	int	Neighbors each cell voted over, its own row removed.
tau	float	Softmax temperature over the neighbor similarities.
macro_f1	float	Mean F1 over the classes the scored cells carry.
accuracy	float	Share of the cells scored whose own label was recovered.
per_class_recall	dict[str, float]	Recall of every class of the axis, NaN for a class no scored cell carries.
similarity_quantiles	dict[str, float]	Quantiles of the similarities to the neighbors voted over, keyed p01 to p99.
n_cells_evaluated	int	Cells scored: every cell of the reference, or a subsample of max_cells.
warnings	tuple[str, ...]	Every reading the numbers depend on, such as a subsample or an absent class, one sentence or two each.

alhena.types.ScoreReport dataclass

ScoreReport(macro_f1, balanced_accuracy, accuracy, n_cells, n_present_classes, class_order, per_class, confusion, floor_macro_f1, floor_accuracy, macro_min_support, frequency_matched_macro_f1=float('nan'), missing_classes=())

Agreement between predicted and known labels.

Two baselines travel with the headline, over the same cells and macro denominator: the commonest-class baseline, which gives every cell the commonest class, and the frequency-matched baseline, computed from its expected counts.

Attributes:

Name	Type	Description
macro_f1	float	Mean F1 over the classes entering the macro average.
balanced_accuracy	float	Mean recall over the classes entering the macro average.
accuracy	float	Share of the scored cells predicted correctly. A cell without a prediction is an error.
n_cells	int	Cells scored, whether or not a prediction was made for them.
n_present_classes	int	Classes entering the macro average, the realized macro denominator.
class_order	tuple[str, ...]	Classes of the axis, in the order indexing the confusion matrix.
per_class	dict[str, dict[str, float]]	Support, predicted support, precision, recall and F1 of every class, and whether it enters the macro average.
confusion	ndarray	Cells of each known class (rows) predicted as each class (columns). A cell without a prediction enters no column.
floor_macro_f1	float	Macro F1 of the commonest-class baseline.
floor_accuracy	float	Accuracy of the commonest-class baseline.
macro_min_support	int	Cells a class must carry to enter the macro average.
frequency_matched_macro_f1	float	Macro F1 of the frequency-matched baseline: the mean share of the scored cells over the classes entering the average.
missing_classes	tuple[str, ...]	Classes of the axis the reference held no cell of, as the annotations scored record them; empty where labels were scored without them.

alhena.types.MEMBERSHIP_COLUMNS module-attribute

MEMBERSHIP_COLUMNS = ('tile_index', 'cell_id', 'token_index', 'nucleus_px')

Columns of a nucleus-to-token membership table, in order.

alhena.types.TileInput module-attribute

TileInput = 'np.ndarray | Sequence[np.ndarray] | torch.Tensor'

Raw uint8 RGB tiles, one array per tile or one stacked array, or a prepared batch.

alhena.types.NucleiInput module-attribute

NucleiInput = 'np.ndarray | Sequence[np.ndarray] | Mapping[str, Any] | pd.DataFrame'

Label maps, the mapping an alhena.io reader of nuclei returns, or a membership table.

---

Next: Errors and warnings