mantispy.pp.correct_plate_position

mantispy.pp.correct_plate_position#

mantispy.pp.correct_plate_position(adata, method='b_score', by='Metadata_Plate', reference=None, plates=None, max_iter=10, tol=0.0001, key_added=None, copy=False)[source]#

Remove row and column position effects, per plate and per feature.

Both methods fit the row and column effects with Tukey’s two-way median polish, which is robust to a few extreme wells.

Parameters:

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

  • method (str (default: 'b_score')) – "b_score" (default) is the B-score of Brideau et al. [2003]: the median-polish residual, divided by the plate’s median absolute deviation, so each feature becomes a robust, position-corrected z-score per plate. "median_polish" subtracts the row and column effects only, keeping each feature’s original level and units. The B-score is the screening standard for calling hits against a positional gradient; it also re-scales each plate, so it doubles as a normalization and should not be followed by a second per-plate scaling.

  • by (str (default: 'Metadata_Plate')) – Column identifying the plate.

  • reference (str | None (default: None)) – Fit the row and column effects on these rows only. "negcon" is the usual choice, so that treatments laid out in particular columns are not absorbed into a column effect. None fits on every well.

  • plates (Sequence[object] | None (default: None)) – Correct only these by values and leave every other plate untouched. None corrects every plate. Pair it with detect_plate_position() to correct only the plates whose artifact is learnable.

  • max_iter (int (default: 10)) – Maximum number of median-polish iterations.

  • tol (float (default: 0.0001)) – Convergence tolerance of the median polish.

  • key_added (str | None (default: None)) – Write to layers[key_added] instead of overwriting X.

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

Return type:

AnnData | None

Returns:

None, or the modified copy. Writes X or layers[key_added], and the fitted effects per corrected plate to uns["mantispy"]["plate_position"].

Raises:

ValueError – If method is unknown, a corrected plate holds no reference rows, or plates names a value absent from by.

Notes

The polish is fitted on the well grid. At cell resolution each well is first reduced to its median, and the fit is then applied to every cell of that well. The B-score’s level and scale are taken from the fitted wells, so with a reference they are the reference wells’ median and spread. That scale is a per-well statistic; at cell resolution the per-cell B-score is therefore standardized only on average, not to an exact unit MAD.