mantispy.tl.transport#

mantispy.tl.transport(adata, by='Metadata_Plate', groupby='Metadata_Perturbation', reference='negcon', use_rep=None, weight='activity', min_shared=3, threshold=0.05, key_added='transport', copy=False)[source]#

Test whether each perturbation’s effect reproduces across settings.

Parameters:
adata AnnData

Well-level profiles. Each setting needs its own reference wells, since effects are measured against them; settings with fewer than two are left out.

by str | list[str] (default: 'Metadata_Plate')

obs column defining the setting, or a list of columns from coarsest to finest. ["Metadata_Source", "Metadata_Plate"] reports agreement between plates of one source separately from agreement between sources, and the difference shows what a change of laboratory costs beyond a change of plate. The finest level defines the units that are compared.

groupby str (default: 'Metadata_Perturbation')

The perturbation column.

reference str | None (default: 'negcon')

Which rows are the negative controls, per setting.

use_rep str | None (default: None)

Score obsm[use_rep] instead of X.

weight str (default: 'activity')

"activity" weights each comparison by the smaller of the two effect magnitudes, since the correlation of an inactive perturbation is noise. "equal" weights all comparisons the same.

min_shared int (default: 3)

Minimum number of shared perturbations for a pair of units to be compared.

threshold float (default: 0.05)

q-value cutoff for is_significant (whether a group transports). The null uses every mismatched pair of perturbations, so there is no null size or seed to set.

key_added str (default: 'transport')

Name for the outputs.

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 one row per group and level and the columns n_pairs, agreement, pvalue, qvalue and is_significant. Writes uns["mantispy"][key_added + "_units"], the units-by-units agreement matrix drawn by setting_agreement(), and joins the finest level’s agreement back onto the rows as obs[key_added + "_agreement"].

Raises:

  • ValueError – weight is not one of WEIGHTS, the unit column has a single level, or fewer than two settings have at least two reference rows.

  • KeyError – obs has no column named by by.

Notes

The null pairs a perturbation at one unit with a different perturbation at another, so a screen in which all effects look alike does not count as reproducing. This matters on screens with few mechanisms, where the mismatched null sits well above zero.

The null is computed in full rather than sampled. Standardizing the effect vectors turns all group-against-group correlations into one matrix product, so the full null is cheap to compute. A sampled null would floor the p-values at 1/(n + 1), too coarse for Benjamini-Hochberg over every (group, level) row, and the number of groups called would depend on the number of draws.

This is an observational measure. It shows whether an effect reproduced at another site, not what the effect would have been there.