Building a reference

Functions for building a custom reference from precomputed single-cell atlas embeddings and labels. Reference construction projects atlas representations into the shared cell space and records the cell_space_id used later for compatibility checks.

alhena.refbuild.build_reference

build_reference(embeddings, labels, encoder, output, *, name=None, axis=DEFAULT_AXIS, class_order=None, label_column=None, dataset=DEFAULT_DATASET, unlabeled=DEFAULT_UNLABELED, source='', license='', k=DEFAULT_K, tau=DEFAULT_TAU, batch_size=DEFAULT_PROJECTION_BATCH, self_check_cells=None, seed=0, overwrite=False, progress=None)

Build a reference shard from single-cell embeddings and a user's own labels.

The embeddings are projected by the reference head and written at half precision in atlas order, with one class-code array per axis, -1 where a row has no class. The shard is read back and retrieved against itself for the report. A custom taxonomy raises EnvelopeWarning, since k and tau were not selected on it. The shard is marked user_built.

Parameters:

Name	Type	Description	Default
embeddings	str | Path | ndarray	Path of the HDF5 file holding cls_emb, or an (n_cells, 512) array, in the row order of the source atlas.	required
labels	LabelSource | Mapping[str, LabelSource]	One label per cell, as an array, a table or the path of a table; or a mapping from axis name to any of those.	required
encoder	AlhenaEncoder	The encoder whose reference head defines the cell space.	required
output	str | Path	Path of the shard to write.	required
name	str | None	Name the shard carries. Defaults to the file stem.	None
axis	str	Axis the self-check runs on, one of the axes coded.	DEFAULT_AXIS
class_order	Sequence[str] | Mapping[str, Sequence[str]] | None	Class names of a custom taxonomy in the order fixing their codes, or a mapping from axis name to such an order. Omitted for a declared axis.	None
label_column	str | Mapping[str, str] | None	Column holding the labels when a table has several columns, or a mapping from axis name to column.	None
dataset	str	Dataset holding the embeddings in the HDF5 file.	DEFAULT_DATASET
unlabeled	Sequence[str]	Label values read as no label.	DEFAULT_UNLABELED
source	str	Where the atlas comes from, recorded in the shard.	''
license	str	Terms the atlas is distributed under, recorded in the shard.	''
k	int	Neighbors the self-check votes over.	DEFAULT_K
tau	float	Softmax temperature the self-check votes at.	DEFAULT_TAU
batch_size	int	Rows projected in one pass.	DEFAULT_PROJECTION_BATCH
self_check_cells	int | None	Cells the self-check samples. Its own default when omitted.	None
seed	int	Seed of the self-check sample.	0
overwrite	bool	Replace a shard already at output.	False
progress	bool | None	Whether to report progress on standard error. None follows ALHENA_DISABLE_PROGRESS_BARS.	None

Returns:

Type	Description
ShardBuildReport	The path written, the shard's name, cell space and support, and its self-check.

Raises:

Type	Description
AlhenaValueError	If an input is malformed, a label matches no class, or output exists.
ReferenceError	If the projection cannot be stored, or if the shard does not load back.
BundleError	If the encoder carries no reference head.

alhena.refbuild.read_scconcept_embeddings

read_scconcept_embeddings(path, *, dataset=DEFAULT_DATASET)

Read single-cell embeddings from the HDF5 file the embedding step writes.

Parameters:

Name	Type	Description	Default
path	str | Path	Path of the HDF5 file.	required
dataset	str	Dataset holding the embeddings.	DEFAULT_DATASET

Returns:

Type	Description
ndarray	An (n_cells, 512) float32 array in the row order of the source atlas.

Raises:

Type	Description
AlhenaValueError	If the file or dataset is missing, or the array is not (n_cells, 512).

alhena.refbuild.read_labels

read_labels(source, *, n_rows, column=None)

Read one label per cell, matched to the embeddings by row position, never by identifier.

Parameters:

Name	Type	Description	Default
source	LabelSource	An array of labels, a table, or the path of a .csv, .tsv or .parquet file.	required
n_rows	int	Number of cells the labels must cover.	required
column	str | None	Column holding the labels, needed when a table holds several.	None

Returns:

Type	Description
ndarray	An (n_rows,) array of stripped label strings, empty where the value is null.

Raises:

Type	Description
AlhenaValueError	If the file, the column or the row count does not match.

alhena.refbuild.encode_labels

encode_labels(labels, class_order, unlabeled=DEFAULT_UNLABELED)

Code labels against a class order, marking rows carrying no class.

Parameters:

Name	Type	Description	Default
labels	LabelSource	One label per cell.	required
class_order	Sequence[str]	Class names, in the order fixing their codes. The unknown class codes no row.	required
unlabeled	Sequence[str]	Label values read as no label.	DEFAULT_UNLABELED

Returns:

Type	Description
tuple[ndarray, dict[str, int]]	An int8 array of class codes, -1 where a row carries no class, and the cells per class.

Raises:

Type	Description
AlhenaValueError	If the class order is empty, repeated or too long, or a label is unknown.

alhena.refbuild.shard_metadata

shard_metadata(path)

Read the metadata of a shard without reading its tensors.

Parameters:

Name	Type	Description	Default
path	str | Path	Path of the shard.	required

Returns:

Type	Description
dict[str, str]	The metadata fields, all of them strings.

Raises:

Type	Description
ReferenceError	If the file is missing or is not a shard.

alhena.refbuild.is_user_built

is_user_built(reference)

Report whether a reference was built from a user's own atlas.

The mark is USER_BUILT_KEY in the metadata of a shard, and USER_BUILT_SOURCE in ReferenceInfo.source.

Parameters:

Name	Type	Description	Default
reference	ReferenceLike	A loaded reference, a ReferenceInfo, or the path of a shard.	required

Returns:

Type	Description
bool	True when the reference was built from a user's own atlas.

Raises:

Type	Description
AlhenaValueError	If the argument is none of those three.

alhena.refbuild.ShardBuildReport dataclass

ShardBuildReport(path, name, axis, axes, class_orders, n_rows, n_labeled, n_invalid_embeddings, class_support, cell_space_id, user_built, info, self_check)

What a reference build wrote, and how the reference reads at the build's k and tau.

Attributes:

Name	Type	Description
path	Path	Path of the shard.
name	str	Name the shard carries.
axis	str	Axis the self-check was run on.
axes	tuple[str, ...]	Every axis the shard codes, in the order the labels declared them.
class_orders	dict[str, tuple[str, ...]]	Classes of each axis, in the order fixing their codes. The unknown class, stored after them and coding no row, is left out.
n_rows	int	Rows written: every row of the source atlas.
n_labeled	dict[str, int]	Rows carrying a class, per axis.
n_invalid_embeddings	int	Rows whose projection is unusable, so they carry no class on any axis.
class_support	dict[str, dict[str, int]]	Cells per class, per axis.
cell_space_id	str	Identity of the cell space the reference was projected into.
user_built	bool	Always True for a shard written here.
info	ReferenceInfo	Name, cell space and support of the shard as the loader reads it.
self_check	SelfCheckReport	Leave-one-out retrieval of the reference against itself.

alhena.refbuild.DEFAULT_DATASET module-attribute

DEFAULT_DATASET = 'cls_emb'

Dataset holding the embeddings in the HDF5 file the embedding step writes.

alhena.refbuild.UNLABELED_CODE module-attribute

UNLABELED_CODE = -1

Class code of a row carrying no label on an axis.

alhena.refbuild.MAX_CLASSES module-attribute

MAX_CLASSES = 127

Largest class code an int8 array can hold, so the widest taxonomy a shard carries.

alhena.refbuild.DEFAULT_UNLABELED module-attribute

DEFAULT_UNLABELED = (UNKNOWN_LABEL, '')

Label values read as no label. The unknown class is always among them.

alhena.refbuild.DEFAULT_PROJECTION_BATCH module-attribute

DEFAULT_PROJECTION_BATCH = 8192

Rows projected in one pass.

alhena.refbuild.USER_BUILT_KEY module-attribute

USER_BUILT_KEY = 'user_built'

Metadata key marking a shard built from a user's own atlas.

alhena.refbuild.USER_BUILT_SOURCE module-attribute

USER_BUILT_SOURCE = 'user-built'

Prefix of ReferenceInfo.source marking a user-built shard once loaded.

alhena.refbuild.ROW_ORDER module-attribute

ROW_ORDER = 'source_atlas'

Value of the metadata field recording that rows keep the order of the source atlas.

alhena.refbuild.EMBEDDINGS_TENSOR module-attribute

EMBEDDINGS_TENSOR = 'embeddings'

Name of the embedding tensor in a shard; every other tensor codes the classes of an axis.

alhena.refbuild.SHARD_SUFFIX module-attribute

SHARD_SUFFIX = '.safetensors'

Suffix of a reference shard file.

alhena.refbuild.LabelSource module-attribute

LabelSource = 'str | Path | Sequence[str] | np.ndarray | pd.DataFrame'

Labels given as an array, a table, or the path of a table.

alhena.refbuild.ReferenceLike module-attribute

ReferenceLike = 'Reference | ReferenceInfo | str | Path'

A loaded reference, its ReferenceInfo, or the path of its shard.

---

Next: Scoring