mantispy.io.stamp

mantispy.io.stamp(adata, resolution=None, *, feature_kind=None, object_type='Object', grouped_by=None, perturbation=None, copy=False)

Mark an AnnData built elsewhere as a mantispy object.

Every reader here, and every tool that returns a new object, records this already. This is the entry point for an object that did not come from one of them: a published h5ad, another pipeline’s output, a subset assembled in a notebook, or a matrix of learned embeddings with its metadata alongside.

Parameters:

adata AnnData

The object to stamp.

resolution str | None (default: None)

What one row is: "object", "well" or "aggregate". obs has to carry the columns that resolution requires. None keeps whatever resolution the object already records; an object that records none must be given one, since guessing could silently mislabel it (the internal schema.stamp and schema.get_resolution also refuse to assume one).

feature_kind str | None (default: None)

The representation every feature carries: "measurement", "embedding" or "derived". Pass it when the whole matrix is one kind (a matrix of embeddings is "embedding"); it fills every feature. Leave it None only when var["feature_kind"] is already complete and valid (as a mantispy-read object’s is).

object_type str (default: 'Object')

For "object" resolution, the name written to Metadata_ObjectType when obs does not already carry one, e.g. "cell".

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

For "aggregate" resolution, the columns that define one row; required there since there is no default.

perturbation Mapping[str, str] | None (default: None)

Optional record of where perturbation identity lives: column (the obs column naming the perturbation) and control_column (default Metadata_Control_Type). Left unset, an object with a Metadata_Perturbation column records that, and one without records nothing. Tools such as consensus() and map() read it as their default column.

copy bool (default: False)

Return a stamped copy instead of stamping in place.

Return type:

AnnData | None

Returns:

None, or the stamped copy. Writes the schema version and the resolution to uns["mantispy"], and adds the missing feature-annotation columns to var.

Raises:

ValueError – resolution is not one of the three, or obs lacks a column that resolution requires.

Notes

Stamping runs the full validate() contract (spec 16.1), so a stamped object is a valid mantispy object or the stamp is rejected; the check runs on a copy first, so a rejected stamp leaves the caller’s object untouched. validate still returns the warnings it does not block on. That includes X: the package stores features as float32, and a matrix that came out of scikit-learn or numpy.load() is float64, so an embedding wants adata.X = adata.X.astype("float32") before it is stamped.

Any of the feature-annotation columns the schema requires that var does not already have are added empty, and columns already present are left as they are. They are not filled by parsing the feature names: the parser finds structure in names that have none (it reads openphenom_nahualX_17 as the nahualX group of an openphenom object), and an embedding would then carry feature families named after the model’s own tensors. An object read by read_profiles() already has the parsed annotation and keeps it.

Examples

Bringing in a matrix of learned embeddings, one row per well:

>>> import anndata as ad
>>> import mantispy as mt
>>> adata = ad.AnnData(embeddings, obs=metadata)
>>> mt.io.stamp(adata, resolution="well", feature_kind="embedding")