Retrieval

Lower-level operators for reference retrieval and voting in the shared cell space.

Each query cell retrieves nearby labeled reference cells. Their cosine similarities are converted into normalized neighbor weights, and those weights are aggregated by class to obtain the class masses used for annotation.

CellTyper.annotate() provides the high-level workflow and performs compatibility and provenance checks around these lower-level functions.

alhena.annotate.annotate_cells

annotate_cells(cell_space, reference_embeddings, reference_labels, class_order, k=DEFAULT_K, tau=DEFAULT_TAU, cell_id=None, valid=None, axis=DEFAULT_AXIS, depth=RETRIEVAL_DEPTH, cell_space_id=None, chunk_size=_REFERENCE_BLOCK, query_chunk_size=_QUERY_BLOCK, workers=None, progress=None)

Predict a cell type for every cell, by retrieval against a labeled reference.

The reference must be L2-normalized, with no unscorable row. The winning class is the argmax of the class mass, ties going to the lowest index. A cell whose embedding is not finite or of zero length, or which is marked invalid, gets an empty label, NaN confidence and mass, and valid False. Coverage gaps raise ReferenceCoverageWarning, an envelope breach EnvelopeWarning.

Parameters:

Name	Type	Description	Default
cell_space	ndarray | CellEmbeddings	An (n_cells, d) array of cell-space embeddings, or CellEmbeddings, whose identifiers and validity are then the defaults.	required
reference_embeddings	ndarray	An (n_reference, d) array of unit-norm reference embeddings.	required
reference_labels	ndarray	An (n_reference,) integer array of class codes into class_order.	required
class_order	Sequence[str]	Class names, in the order that indexes the columns of the mass.	required
k	int	Number of neighbors each cell votes over.	DEFAULT_K
tau	float	Softmax temperature over neighbor similarities.	DEFAULT_TAU
cell_id	ndarray | None	Unique identifier of each cell.	None
valid	ndarray | None	False where the caller has already ruled a cell out.	None
axis	str	Name of the class axis the reference is labeled on.	DEFAULT_AXIS
depth	int	Number of neighbors retrieved before the slice to k.	RETRIEVAL_DEPTH
cell_space_id	str | None	Identity of the cell space both sides were projected into; CellEmbeddings recording another are refused.	None
chunk_size	int	Reference rows read into one similarity block.	_REFERENCE_BLOCK
query_chunk_size	int	Query cells scored against one reference block.	_QUERY_BLOCK
workers	int | None	Threads scoring blocks of query cells at once, as retrieve reads them.	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, and the retrieved similarities.
AnnotationResult	meta records the operating point, reference_class_support, unexpressed_classes,
AnnotationResult	thinly_supported_classes, and effective_k, the median over the annotated cells of
AnnotationResult	exp(neighbor_entropy), or None.

Raises:

Type	Description
AlhenaValueError	If the cells, identifiers or hyperparameters are malformed.
BundleError	If the cells carry no cell-space projection.
CellSpaceMismatchError	If the cells record a cell space other than cell_space_id.
ReferenceError	If the reference or its labels are malformed, or it is smaller than k.

alhena.annotate.retrieve

retrieve(query, reference, k=DEFAULT_K, depth=RETRIEVAL_DEPTH, chunk_size=_REFERENCE_BLOCK, query_chunk_size=_QUERY_BLOCK, workers=None, progress=None)

Return the k nearest reference rows of each query cell and their cosine similarities.

Queries are L2-normalized here; reference rows must be of unit length already. Neighbors are ordered by descending similarity, then ascending reference row. The number of threads never changes the result, nor do the chunk sizes unless more than depth - k rows tie with a cell's k-th neighbor.

Parameters:

Name	Type	Description	Default
query	ndarray	An (n_cells, d) array of cell embeddings, not necessarily normalized.	required
reference	ndarray	An (n_reference, d) array of unit-norm reference embeddings.	required
k	int	Number of neighbors returned per cell.	DEFAULT_K
depth	int	Number of neighbors retrieved before the slice to k.	RETRIEVAL_DEPTH
chunk_size	int	Reference rows read into one similarity block.	_REFERENCE_BLOCK
query_chunk_size	int	Query cells scored against one reference block.	_QUERY_BLOCK
workers	int | None	Threads scoring blocks of query cells at once. None uses the processors available, at most MAX_DEFAULT_WORKERS.	None
progress	bool | None	Whether to report progress on standard error. None follows ALHENA_DISABLE_PROGRESS_BARS.	None

Returns:

Type	Description
ndarray	The reference row of each neighbor, (n_cells, k) int64, and its cosine similarity,
ndarray	(n_cells, k) float32.

Raises:

Type	Description
AlhenaValueError	If the query is malformed or not finite, or a count is not positive.
ReferenceError	If the reference is malformed, not of unit length, or smaller than k.

alhena.annotate.vote

vote(neighbor_sim, neighbor_labels, n_classes, tau=DEFAULT_TAU)

Turn retrieved neighbors into per-class mass, rows summing to one.

Each neighbor gets a softmax weight over its similarity divided by tau, added to the column of its class.

Parameters:

Name	Type	Description	Default
neighbor_sim	ndarray	An (n_cells, k) array of neighbor cosine similarities.	required
neighbor_labels	ndarray	An (n_cells, k) integer array of neighbor class codes.	required
n_classes	int	Width of the class axis.	required
tau	float	Softmax temperature.	DEFAULT_TAU

Returns:

Type	Description
ndarray	An (n_cells, n_classes) float32 array of class mass.

Raises:

Type	Description
AlhenaValueError	If the two inputs disagree in shape, or if tau is not positive.
ReferenceError	If a class code falls outside the class axis.

alhena.annotate.l2_normalize

l2_normalize(x, eps=L2_EPS)

Scale every row to unit length, leaving a zero row at zero.

Parameters:

Name	Type	Description	Default
x	ndarray	An (n, d) array of embeddings.	required
eps	float	Floor applied to each row norm, so a zero row stays zero instead of becoming NaN.	L2_EPS

Returns:

Type	Description
ndarray	An (n, d) float32 array.

Raises:

Type	Description
AlhenaValueError	If the input is not two-dimensional.

alhena.annotate.THIN_SUPPORT_WARNING module-attribute

THIN_SUPPORT_WARNING = 'The thinnest class the'

Opening of the warning that the thinnest class of a reference has too few cells for k.

alhena.annotate.MAX_DEFAULT_WORKERS module-attribute

MAX_DEFAULT_WORKERS = 8

Default cap on retrieval threads, each holding about 0.4 GB at the default block sizes.

---

Next: References