mantispy.tl.hit_calling

Contents

mantispy.tl.hit_calling#

mantispy.tl.hit_calling(adata, groupby='Metadata_Perturbation', reference='negcon', method='mahalanobis', use_rep=None, n_permutations=1000, threshold=0.05, seed=0, key_added='hits', copy=False)[source]#

Call hits by testing each group’s distance from the controls.

Parameters:

  • adata (AnnData) – Object to score, at cell or well resolution.

  • groupby (str (default: 'Metadata_Perturbation')) – Column defining the groups to test.

  • reference (str | None (default: 'negcon')) – Which rows are the controls. They are split in half, one half to fit the covariance and the other to form the null (see Notes).

  • method (str (default: 'mahalanobis')) – "mahalanobis" scores the median distance of the group’s rows from the control centroid, measured in the controls’ covariance so that directions the controls already vary in count for less. "ks" scores the Kolmogorov-Smirnov statistic between the group’s and the controls’ distance distributions, which detects a shifted subpopulation that leaves the median unchanged. Use it at cell resolution. Its p-value comes from scipy.stats.ks_2samp, so n_permutations does not apply.

  • use_rep (str | None (default: None)) – Score obsm[use_rep] instead of X. When the covariance-fitting half of the controls has no more rows than there are features, the covariance is singular and a warning suggests a PCA representation.

  • n_permutations (int (default: 1000)) – Size of the permutation null. Applies to method="mahalanobis" only.

  • threshold (float (default: 0.05)) – q-value below which a group is called a hit in is_hit.

  • seed (int (default: 0)) – Seed for the control split and the permutation null.

  • key_added (str (default: 'hits')) – 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 group, n_obs, distance, pvalue, qvalue and is_hit, and joins obs[key_added + "_distance"] and obs[key_added + "_qvalue"] back onto the rows.

Notes

The controls are split in half. One half estimates the centroid and the covariance, and the other supplies the null. A null drawn from the rows that defined the centroid would be in-sample while every tested group is out-of-sample, so it would come out too small and call pure noise as hits. Because only half the controls fit the covariance, the singular-covariance warning fires when there are fewer than about twice as many controls as features.

The null is drawn from the controls only, and asks whether a group is further out than the same number of control rows would be. Drawing from every row would put real hits into the null, and a screen with many hits would look like one with none.

Calibration degrades with few controls. On pure-noise screens of 12 groups of 12 rows with 10 features (the pure_noise_screen test fixture), the false positive rate at a nominal 0.05 was 0.10 with 48 controls, 0.077 with 192 and 0.052 with 384. Across four configurations from 20 to 80 features and 48 to 200 controls, ten seeds each, it was 2.1% overall. Neither figure is a bound for another screen, and both were measured with method="mahalanobis". Under method="ks" there is no permutation null; each group’s distances are compared with those of the null half by scipy.stats.ks_2samp.

To check the rate on your own screen, diagnose_testing() relabels control wells as pseudo-treatments of your group sizes and reports the fraction called.

Contents