mantispy.io.from_embedding

mantispy.io.from_embedding(X, obs=None, *, like=None, resolution=None, feature_kind='embedding', object_type='Object', var_names=None)

Build an AnnData that mantispy’s tools accept from a matrix of image-model embeddings.

A deep-learning model run on the images, such as DINO or another self-supervised encoder, gives a matrix with one row per object, crop or well and one column per embedding dimension. This function puts that matrix and the metadata of its rows into one object, names the columns and stamps the object, so that aggregate(), map() and edistance() accept it. The values are stored as given, in the dtype they arrive in.

Parameters:

X ndarray

The embedding, with observations as rows and embedding dimensions as columns. Row i must describe the same object as row i of obs, or of like.obs. Only the row counts are checked, so an embedding written in a different order is mislabelled without an error.

obs DataFrame | None (default: None)

Metadata for each row, with the columns that resolution requires. Defaults to like.obs.

like AnnData | None (default: None)

An object whose rows the embedding describes, usually the cells it was computed from. Its obs, its resolution and its perturbation record carry over, so the embedding is analysed with the same metadata as the features it replaces.

resolution str | None (default: None)

What one row is, passed to stamp(): "object" for single cells, "well" or "aggregate". Defaults to the resolution that like records, and to "object" when there is no like.

feature_kind str (default: 'embedding')

What the columns hold. For an embedding it is "embedding".

object_type str (default: 'Object')

The Metadata_ObjectType written at object resolution when obs has none.

var_names Sequence[str] | None (default: None)

Names for the embedding dimensions. Defaults to embedding_0 up to embedding_{k-1}.

Return type:

AnnData

Returns:

A stamped and validated object with the embedding in X and the feature annotation in var.

Raises:

ValueError – Neither obs nor like is given, the row counts differ, or obs lacks a column that resolution requires, which the validation in stamp() reports.

Examples

Wrapping DINO features computed on single-cell crops, in the row order of the cells they came from:

>>> import mantispy as mt
>>> dino = mt.io.from_embedding(features, like=cells)
>>> wells = mt.tl.aggregate(dino, by=("Metadata_Plate", "Metadata_Well"))