mantispy.tl.replicate_saturation

mantispy.tl.replicate_saturation#

mantispy.tl.replicate_saturation(adata, groupby='Metadata_Perturbation', metric='signature_stability', max_replicates=None, min_groups=3, n_draws=5, use_rep=None, seed=0, key_added='replicate_saturation', copy=False)#

Score how much a group’s signature improves with each additional replicate.

Parameters:

  • adata (AnnData) – Well-level profiles with several replicates per group.

  • groupby (str (default: 'Metadata_Perturbation')) – The column whose groups are the replicate sets.

  • metric (str | Callable[[ndarray, ndarray, int, Generator], float] (default: 'signature_stability')) – "signature_stability" correlates two disjoint subsets of this depth. It is unbiased but needs 2 * depth replicates, so it stops early on a screen with three. "convergence" correlates a subset of this depth with the group’s full signature. It is defined up to one less than the group size and optimistic by construction. A callable (profiles, codes, depth, generator) -> float can score anything else, such as MOA retrieval or mAP.

  • max_replicates (int | None (default: None)) – Deepest subset to try. None derives it from min_groups.

  • min_groups (int (default: 3)) – Number of groups that must be able to supply a depth for it to be scored. The statistic is a median over the contributing groups, and the largest group is usually the negative controls. On 132 JUMP plates, taking the range from the largest group gives 4252 depths, and past about 66 only DMSO contributes. min_groups=1 takes the range from the largest group.

  • n_draws (int (default: 5)) – Random subsets per depth. The spread across draws is reported as std.

  • use_rep (str | None (default: None)) – Score obsm[use_rep] instead of X.

  • seed (int (default: 0)) – Seed for reproducibility.

  • key_added (str (default: 'replicate_saturation')) – Name for the output table.

  • copy (bool (default: False)) – Return a modified copy instead of mutating in place.

Return type:

AnnData | None

Returns:

None, or the modified copy. Writes uns["mantispy"][key_added] with n_replicates, mean, std and n_draws. The n_draws column counts the draws that produced a finite score, which can be fewer than the n_draws asked for, and the first depth at which every draw is NaN ends the table.

Raises:

ValueError – metric is neither a callable nor one of METRICS.

Notes

A curve that still climbs steeply at the deepest depth means the screen is under-replicated, which informs the design of the next experiment. Three replicates, as in BBBC021, give one point with the default metric and two with "convergence".