mantispy.tl.consensus

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

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: 'modz')) – "modz" weights replicates by their agreement, so a single bad replicate moves the signature far less than it would a plain mean. "median" is the unweighted alternative, identical to tl.aggregate by the same column.

• 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.

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, or correlation is not one of CORRELATIONS.

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. On BBBC021, not-same-compound MOA retrieval was 0.777 with method="median" and 0.660 with modz. It is the default because it matches pycytominer and is the usual definition of a consensus signature. Compare both methods on your own data.

Normalize before taking a consensus, and first drop the features pp.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.