References

Functions for loading and inspecting ALHENA single-cell references. A reference contains embeddings in the shared cell space, class codes, compatibility information, and class-support metadata.

For prebuilt references, source and license information can also be supplied by the ALHENA reference registry.

alhena.reference.Reference dataclass

Reference(info, embeddings, label_ids, class_order)

A labeled reference in the shared cell space, ready to be retrieved against.

Attributes:

Name	Type	Description
info	ReferenceInfo	Name, cell space, provenance and per-class support of the shard.
embeddings	ndarray	Unit-norm rows of the scored cells, (n_scored_cells, cell_dim).
label_ids	ndarray	Class code of each row, indexing class_order.
class_order	tuple[str, ...]	Classes of the axis, those the reference holds no cell of included, in the order that fixes their codes and breaks ties in the vote.

n_classes property

n_classes

Number of classes of the axis, those the reference holds no cell of included.

require_cell_space

require_cell_space(cell_space_id=None)

Check that the reference records the cell space it was projected into, and which.

Vectors of two runs have the same width, so only the identity tells them apart.

Parameters:

Name	Type	Description	Default
cell_space_id	str | None	Cell space identity of the encoder that queries the reference, or of the cells it annotates. None checks only that the reference records one.	None

Raises:

Type	Description
AlhenaValueError	If an empty identity is given.
CellSpaceMismatchError	If the reference records no cell space, or another than given.

self_check

self_check(k=DEFAULT_K, tau=DEFAULT_TAU, max_cells=DEFAULT_SELF_CHECK_CELLS, seed=0, progress=None)

Retrieve the reference against itself, every cell excluded from its own neighbors.

The check is necessary and not sufficient: the query is a reference cell rather than an image cell, so its similarity quantiles are not comparable to those of an annotation run. A reference of more than max_cells cells is scored on a subsample drawn under seed; the reference retrieved against is never subsampled.

Parameters:

Name	Type	Description	Default
k	int	Neighbors each cell votes over, once its own row is removed.	DEFAULT_K
tau	float	Softmax temperature over neighbor similarities.	DEFAULT_TAU
max_cells	int	Largest number of cells scored.	DEFAULT_SELF_CHECK_CELLS
seed	int	Seed of the subsample.	0
progress	bool | None	Whether to report progress on standard error. None follows ALHENA_DISABLE_PROGRESS_BARS.	None

Returns:

Type	Description
SelfCheckReport	Macro F1, accuracy, per-class recall, the similarity quantiles and the number of cells
SelfCheckReport	scored, with a note for every reading the numbers depend on.

Raises:

Type	Description
AlhenaValueError	If k, tau or max_cells is out of range for the reference.

alhena.reference.load_reference

load_reference(tissue=None, path=None, axis=DEFAULT_AXIS, *, cache_dir=None, progress=None)

Load a reference shard for one class axis.

Rows with no class on the axis are dropped, and the rest are upcast to float32 and normalized once. Coverage gaps raise ReferenceCoverageWarning, and an envelope breach at the default k raises EnvelopeWarning.

Parameters:

Name	Type	Description	Default
tissue	str | None	Tissue whose published reference to load, by tissue, alias or shard. Give this or path.	None
path	str | Path | None	Location of a shard on disk.	None
axis	str	Class axis to label the reference on: a declared axis, or, for a shard given by path, an axis it was built on.	DEFAULT_AXIS
cache_dir	str | Path | None	Root a published shard is looked for in before it is downloaded. Defaults to the resolved cache root.	None
progress	bool | None	Whether to report progress on standard error. None follows ALHENA_DISABLE_PROGRESS_BARS.	None

Returns:

Type	Description
Reference	The reference, holding only the rows the axis labels.

Raises:

Type	Description
AlhenaValueError	If not exactly one of tissue and path is given, or no reference fits.
ReferenceError	If the shard is missing or malformed, or if it holds no row the axis labels.

alhena.reference.describe_shard

describe_shard(tissue=None, path=None, axis=DEFAULT_AXIS, *, cache_dir=None)

Report a shard's name, cell space, provenance and support without reading its embeddings.

Only the header and the labels are read. No coverage warning is raised: missing_classes and thin_classes carry the same facts.

Parameters:

Name	Type	Description	Default
tissue	str | None	Tissue whose published reference to describe, by tissue, alias or shard. Give this or path.	None
path	str | Path | None	Location of a shard on disk.	None
axis	str	Class axis to count the support on: a declared axis, or, for a shard given by path, an axis it was built on.	DEFAULT_AXIS
cache_dir	str | Path | None	Root a published shard is looked for in before it is downloaded. Defaults to the resolved cache root.	None

Returns:

Type	Description
ReferenceInfo	What the shard is and what it can express on that axis.

Raises:

Type	Description
AlhenaValueError	If not exactly one of tissue and path is given, or no reference fits.
ReferenceError	If the shard is missing or malformed, or carries no label for the axis.

alhena.reference.available_tissues

available_tissues()

Return the tissue names a reference is published for.

The canonical names, one per organ; the aliases TISSUE_ALIASES declares are not listed.

alhena.reference.available_shards

available_shards()

Return the published reference shards. Several tissues may share one shard.

alhena.reference.shard_for_tissue

shard_for_tissue(tissue)

Return the shard published for a tissue.

A tissue is named by its canonical name, an alias TISSUE_ALIASES declares, or its shard, ignoring case, spacing and separators: LymphNode, lymph_node and tonsil name one shard.

Parameters:

Name	Type	Description	Default
tissue	str	Tissue the reference is wanted for, an alias of it, or its shard.	required

Returns:

Type	Description
str	Name of the shard, without a suffix.

Raises:

Type	Description
AlhenaValueError	If the name is empty, or no reference is published under it.

alhena.reference.SHARD_SUFFIX module-attribute

SHARD_SUFFIX = '.safetensors'

Suffix of a reference shard file.

alhena.reference.SHARD_DIRECTORY module-attribute

SHARD_DIRECTORY = 'shards'

Folder holding the shards, in the references repository and in a cache root.

alhena.reference.SELF_CHECK_QUANTILES module-attribute

SELF_CHECK_QUANTILES = (0.01, 0.05, 0.25, 0.5, 0.75, 0.95, 0.99)

Quantiles of the retrieved similarities a self-check reports.

alhena.reference.DEFAULT_SELF_CHECK_CELLS module-attribute

DEFAULT_SELF_CHECK_CELLS = 200000

Cells a self-check scores unless the caller asks for fewer.

---

Next: Building a reference