mantispy.metrics.variance_carried#

mantispy.metrics.variance_carried(adata, reference, use_rep='X_pca', groupby='feature_group', n_splits=5)[source]#

How much of a named feature block a learned embedding linearly carries.

A learned embedding has no var vocabulary, so a hit read off it is only a compound ID. This scores, per named feature, the out-of-fold R^2 of predicting that feature from the embedding with a cross-fit ridge, so a value near 1 means the embedding carries the feature and near 0 means it does not.

Parameters:
adata AnnData

Object holding the learned embedding in obsm.

reference AnnData

Object whose X holds the named block (e.g. CellProfiler features) to recover.

use_rep str (default: 'X_pca')

obsm key of the embedding used as the predictor.

groupby str | None (default: 'feature_group')

reference.var column to average over, one row of the result per group; None returns one row per feature instead.

n_splits int (default: 5)

Folds of the cross-fit that produces the out-of-fold predictions.

Returns:

columns ["feature", "variance_carried"] when groupby is None, else ["<groupby>", "variance_carried", "n_features"] holding the mean over each group.

Return type:

DataFrame

Raises:

  • KeyError – obsm holds nothing under use_rep.

  • ValueError – The two objects share no obs_names.

  • ValueError – adata or reference has non-unique obs_names.

  • ValueError – groupby is not None and not a column of reference.var.

Notes

The two blocks may hold the same wells in different row orders, so the rows are aligned on the shared obs_names before regressing; matching by position instead returns a near-zero R^2 for an informative block, which reads as a real negative result.