SpatialData

Functions connecting ALHENA inputs and outputs with SpatialData.

• tile_source() exposes an image stored in SpatialData through the standard ALHENA TileSource interface.
• cells_from_shapes() converts a nucleus shapes element into the membership representation used for cell encoding.
• tiles_to_spatialdata() adds tile-level results to an existing SpatialData object.
• cells_to_spatialdata() adds the table of cells associated with a nucleus element, from the cells alone or from their annotations, then each further annotation of the same cells.
• tile_embeddings() and Alhena support the alternative sopa patch workflow. See Advanced: sopa patch pipeline.

See Writing into a SpatialData object.

ALHENA tables retain the same embedding and annotation fields used by the AnnData representations, with the additional SpatialData region/instance metadata required to connect observations to spatial elements.

Needs the spatial extra

pip install "alhena[spatial]" brings in spatialdata and sopa. See optional extras.

alhena.spatial.tile_source

tile_source(sdata, *, image_key=None, tile_px=None, stride_px=None, mpp=None, edge='shift', patches=None, coordinate_system=None)

Return the tiles of an image of a SpatialData object as a tile source.

The tiles are a grid cut as alhena.io.read_image cuts an image, or the windows patches selects, in the level-zero pixels of the image. The pixels of a window are read when its tile is read.

Parameters:

Name	Type	Description	Default
sdata	Any	The object holding the image.	required
image_key	str | None	Image the tiles are cut from, needed only when the object holds several.	None
tile_px	int | None	Side of each tile, in level-zero pixels. Defaults to the side that fills the canvas at mpp, or with patches to the side of its windows, which it must then equal.	None
stride_px	int | None	Step between tile origins. Defaults to tile_px; refused beside patches.	None
mpp	float | None	Microns per pixel of the image at level zero, carried by the tiles.	None
edge	str	One of alhena.io.EDGE_RULES: what becomes of the tiles the edge of the image cuts.	'shift'
patches	str | ndarray | None	Shapes element holding one box per tile, or an (n_tiles, 4) array of x0, y0, x1, y1 windows, squares of one side, read as patch_bounds reads them.	None
coordinate_system	str | None	Coordinate system the windows of patches are carried through into the pixels of the image.	None

Returns:

Type	Description
TileSource	A tile source over the image, naming its tiles by their origin, in the frame named after
TileSource	the image, such as image 'he', level 0.

Raises:

Type	Description
AlhenaValueError	If the image is missing or ambiguous, or the windows or sizes do not fit.
GeometryError	If the image is not three channels of bytes.
MissingExtraError	If the spatial extra is not installed.

alhena.spatial.tiles_to_spatialdata

tiles_to_spatialdata(sdata, tiles, shapes_key=None, table_key=None, image_key=None, overwrite=False)

Write tile embeddings back as one rectangle and one table row per tile.

The rectangles are the regions of the source image the embeddings stand for, and the table is the one TileEmbeddings.write_h5ad writes, tied to them. With sdata None, both go into an object of their own. The rectangles take the transformations of the image the tiles were cut from, else the identity in DEFAULT_COORDINATE_SYSTEM.

Parameters:

Name	Type	Description	Default
sdata	Any | None	Object the rectangles and the table are added to, or None to build one.	required
tiles	TileEmbeddings	The tile embeddings, carrying the spatial bounds of their tiles.	required
shapes_key	str | None	Name the rectangles are stored under. Defaults to TILE_SHAPES_KEY.	None
table_key	str | None	Name the table is stored under. Defaults to TILE_TABLE_KEY.	None
image_key	str | None	Image of sdata the tiles were cut from, whose transformations the rectangles take. 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.

alhena.spatial.tile_embeddings

tile_embeddings(sdata, encoder, patch_width=INPUT_SIZE, patch_overlap=0, mpp=None, level=0, magnification=None, image_key=None, batch_size=DEFAULT_BATCH_SIZE, roi_key='region_of_interest', key_added=None)

Embed the patches of an image inside sopa's patch pipeline, and store them in the object.

The pipeline reads the patches at the level or the magnification chosen, never resampled to the encoder's resolution, so that choice sets the field of view: mpp has it checked, else a GeometryWarning says it goes unchecked. For a TileEmbeddings result, read the image with tile_source and embed it with AlhenaEncoder.encode_tiles.

Parameters:

Name	Type	Description	Default
sdata	Any	The object holding the image.	required
encoder	AlhenaEncoder	The loaded encoder.	required
patch_width	int	Side of a patch, in pixels: the input size the model reads.	INPUT_SIZE
patch_overlap	int	Overlap between neighboring patches, in pixels.	0
mpp	float | None	Microns per pixel of a patch as the model reads it, after any resizing to magnification.	None
level	int | None	Image level the patches are read from.	0
magnification	int | None	Target magnification, resolving the level when it is given instead.	None
image_key	str | None	Image to read, needed only when the object holds several.	None
batch_size	int	Patches per forward pass, run on the device the encoder was loaded on.	DEFAULT_BATCH_SIZE
roi_key	str | None	Shapes element patches must touch to be kept; every patch is kept when None.	'region_of_interest'
key_added	str | None	Name the embeddings are stored under. Defaults to TILE_EMBEDDINGS_KEY.	None

Returns:

Type	Description
str	The key the embeddings were stored under.

Raises:

Type	Description
AlhenaValueError	If the patch width is not the input size or an argument is out of range.
MissingExtraError	If the spatial extra is not installed.

alhena.spatial.cells_from_shapes

cells_from_shapes(sdata, shapes_key, *, patches=PATCHES_KEY, coordinate_system=None, image_key=None, multipart='refuse', mpp=None, tile_scale=1.0, progress=None)

Build a token membership table from nucleus boundaries held in a SpatialData object.

Each boundary is rasterized into the window of every tile it falls in, and carried onto the canvas as the image of the tile is. The boundaries and the windows are read in the level-zero pixels of image_key, else in coordinate_system or as stored; windows given as an array are refused where an image sits in that frame other than by the identity. cells_to_spatialdata cannot write the polygons multipart="split" yields, which are not instances of the element.

Parameters:

Name	Type	Description	Default
sdata	Any	The object holding the boundaries and the tile windows.	required
shapes_key	str	Shapes element holding one polygon per nucleus, indexed by cell identifier.	required
patches	str | ndarray	Shapes element holding one box per tile, read as patch_bounds reads it, or an (n_tiles, 4) array of windows.	PATCHES_KEY
coordinate_system	str | None	Coordinate system both elements are read in, or carried through into the pixels of image_key.	None
image_key	str | None	Image the tiles are read from, in whose level-zero pixels both elements are read.	None
multipart	str	One of alhena.io.MULTIPART_RULES, applied as alhena.io.read_polygons applies it.	'refuse'
mpp	float | None	Microns per pixel of the tiles, as the call annotating the cells declares. Without it, each raster is stretched onto the whole canvas.	None
tile_scale	float	Pixels of the frame one tile pixel spans, the coords_scale of the tiles.	1.0
progress	bool | None	Whether to report progress on standard error. None follows ALHENA_DISABLE_PROGRESS_BARS.	None

Returns:

Type	Description
DataFrame	A table with MEMBERSHIP_COLUMNS, recording the windows and the resolution, with positions
DataFrame	in the frame the boundaries were read in, named such as image 'he', level 0,
DataFrame	coordinate system 'global' or polygons.

Raises:

Type	Description
AlhenaValueError	If an element is missing or empty, or no frame holds both elements.
MembershipError	If the boundaries and the windows are placed in different frames.
MissingExtraError	If the spatial extra is not installed.

alhena.spatial.cells_to_spatialdata

cells_to_spatialdata(sdata, cells, region, table_key=None, region_key=REGION_KEY, instance_key=INSTANCE_KEY, name=None, overwrite=False)

Write cells, or their annotations, into the table of cells of the element of their nuclei.

The first call creates the table write_h5ad writes, tied to the element by region_key and instance_key; a later call with annotations of the same cells adds them, as alhena.io.add_annotation does. The cell identifiers must be instances of the element. The positions are those the cells record, else the boundary centroids, with no resolution recorded.

Parameters:

Name	Type	Description	Default
sdata	Any	The object the table is stored in.	required
cells	CellEmbeddings | AnnotationResult	The cells encode_cells returns, or the annotations CellTyper.annotate returns, which carry them.	required
region	str	Element the table annotates, whose instances the cell identifiers name.	required
table_key	str | None	Name the table of cells is stored under, CELL_TABLE_KEY when None.	None
region_key	str	Column naming the annotated element.	REGION_KEY
instance_key	str	Column holding the instance identifiers.	INSTANCE_KEY
name	str | None	Name the fields of an annotation carry. Defaults to the axis of the annotations.	None
overwrite	bool	Replace the annotation the table holds under name, and that one alone; for cells, replace the table they would be written to.	False

Returns:

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

Raises:

Type	Description
AlhenaValueError	If the identifiers do not match the element, or a stored table conflicts.
MissingExtraError	If the spatial extra is not installed.

alhena.spatial.patch_bounds

patch_bounds(sdata, *, patches=PATCHES_KEY, coordinate_system=None, image_key=None)

Return the window of every tile, in the frame the nuclei are read against.

Windows given as an array are returned as they are. The windows of a shapes element are read in the frame cells_from_shapes reads, and refused where that frame rotates, mirrors or shears them. A bboxes column keeping each full window beside a geometry clipped to the tissue is read instead; without one, every geometry must fill its bounds, and a window clipped along the axes reads as a smaller tile.

Parameters:

Name	Type	Description	Default
sdata	Any	The object holding the tile windows.	required
patches	str | ndarray	Shapes element holding one box per tile, or an (n_tiles, 4) array of x0, y0, x1, y1 windows. The tile index is the row index.	PATCHES_KEY
coordinate_system	str | None	Coordinate system the windows are read in, or carried through into the pixels of image_key.	None
image_key	str | None	Image the tiles are read from, in whose level-zero pixels the windows are read.	None

Returns:

Type	Description
ndarray	An (n_tiles, 4) float64 array of x0, y0, x1, y1 windows.

Raises:

Type	Description
AlhenaValueError	If the windows are missing or malformed, or cannot be read as boxes.
MissingExtraError	If the spatial extra is not installed.

alhena.spatial.Alhena

Alhena(encoder)

Bases: Module

ALHENA's backbone behind the tile-embedding hook of a patch pipeline.

The pipeline hands over unnormalized tiles on the unit scale and never sets evaluation mode, so the module normalizes them, is in evaluation mode from construction, and moves each batch to the device of its weights. The pipeline stores the result under TILE_EMBEDDINGS_KEY, the class name followed by _embeddings; a subclass under its own name.

Parameters:

Name	Type	Description	Default
encoder	AlhenaEncoder	The encoder load_encoder returns, whose backbone is shared.	required

Attributes:

Name	Type	Description
embed_dim		Width of the embedding one tile produces.
input_size		Side, in pixels, of the canvas the model reads.
reference_mpp		Microns per pixel that canvas is meant to cover.

Raises:

Type	Description
BundleError	If encoder is not one load_encoder returns.

forward

forward(images)

Embed a batch of tiles given on the unit scale.

Parameters:

Name	Type	Description	Default
images	Tensor	A (B, 3, W, W) float tensor with values in [0, 1], W the input size the model reads.	required

Returns:

Type	Description
Tensor	A (B, embed_dim) float32 tensor, not normalized.

Raises:

Type	Description
GeometryError	If the batch is not RGB tiles of the input size on the unit scale.

alhena.spatial.TILE_EMBEDDINGS_KEY module-attribute

TILE_EMBEDDINGS_KEY = f'{Alhena.__name__}_embeddings'

Key a patch pipeline stores the tile embeddings under, after the class name Alhena.

alhena.spatial.PATCHES_KEY module-attribute

PATCHES_KEY = 'embeddings_patches'

Shapes element a patch pipeline writes its tile windows to.

alhena.spatial.TILE_SHAPES_KEY module-attribute

TILE_SHAPES_KEY = 'alhena_tiles'

Name the rectangles of a tile-embedding result are stored under by default.

alhena.spatial.TILE_TABLE_KEY module-attribute

TILE_TABLE_KEY = 'alhena_tile_embeddings'

Name the table of tile embeddings is stored under by default.

alhena.spatial.DEFAULT_COORDINATE_SYSTEM module-attribute

DEFAULT_COORDINATE_SYSTEM = 'global'

Coordinate system rectangles are placed in where no image places them.

alhena.spatial.CELL_TABLE_KEY module-attribute

CELL_TABLE_KEY = 'alhena_cells'

Name the table of cells is stored under by default.

alhena.spatial.REGION_KEY module-attribute

REGION_KEY = 'region'

Column of the table of cells naming the element it annotates, by default.

alhena.spatial.INSTANCE_KEY module-attribute

INSTANCE_KEY = CELL_ID_COLUMN

Column of the table of cells holding the instance identifiers: the cell identifiers.

---

Next: Plotting