mantispy.tl.consensus

Contents

mantispy.tl.consensus#

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

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

Parameters:

  • adata (AnnData) – Profiles to summarize, normally well level.

  • by (str (default: 'Metadata_Perturbation')) – Column defining a 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 "perturbation" 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.

Contents