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