mantispy.tl.consensus

mantispy.tl.consensus(adata, by=None, method='median', correlation='spearman', min_replicates=2, min_weight=0.01, precision=4, use_rep=None)

One profile per group, weighting replicates by how well they agree.

Parameters:

adata AnnData

Profiles to summarize, normally well level.

by str | None (default: None)

Column defining a perturbation, by default the perturbation column the object records, else Metadata_Perturbation.

method str (default: 'median')

"median" (the default, matching pycytominer and identical to aggregate() by the same column) or "modz", which weights replicates by their agreement so a single bad replicate moves the signature far less than a plain mean would.

correlation str (default: 'spearman')

How replicate agreement is measured: "spearman" (pycytominer’s default, and insensitive to a few extreme features) or "pearson".

min_replicates int (default: 2)

Groups with fewer replicates are dropped.

min_weight float (default: 0.01)

Floor on a replicate’s weight. A group whose replicates all land on the floor becomes an unweighted mean.

precision int (default: 4)

Decimals the weights are rounded to, as in pycytominer.

use_rep str | None (default: None)

Reduce this obsm representation (e.g. an embedding from tvn()/harmony()) instead of X; the result’s X holds the reduced representation and var is a plain range index, since the axes are not named features.

Return type:

AnnData

Returns:

A new object at "aggregate" resolution, one row per group, with Metadata_ReplicateCount and the metadata that is constant within a group. uns["mantispy"]["consensus_weights"] keeps the weight given to every input row, including the rows of groups dropped for having too few replicates, so a signature can be traced back to its replicates. Under method="median" no weights are computed and every row is recorded as 1.0, since a median is not a weighted sum.

Raises:

ValueError – method is not one of METHODS, correlation is not one of CORRELATIONS, or use_rep is not a 2-D representation in obsm.

Notes

A missing value is filled with its own replicate’s mean before the replicates are correlated. Zero would be an extreme value among ranks, and two replicates sharing a gap would look alike. The signature itself is a weighted sum, so a NaN feature stays NaN.

modz is a weighted mean: with one outlying replicate it drifts about forty times less than the unweighted mean, but it does not beat a median. median is at least as robust as modz for consensus signatures, so compare both on your own data.

Normalize before taking a consensus, and first drop the features normalize() flags in var["degenerate_scale"]. A feature that is constant among the controls is divided by epsilon, and a weighted mean carries the resulting values of order 1e17 into the signature, where a median would discard them.