mantispy.pp.normalize

mantispy.pp.normalize(adata, method='mad_robustize', by='Metadata_Plate', reference='negcon', epsilon=1e-18, keep_raw=False, layer=None, key_added=None, copy=False)

Normalize features within groups, optionally fitting on reference rows only.

Parameters:

adata AnnData

Object to normalize.

method str (default: 'mad_robustize')

"mad_robustize" computes (x - median) / (1.4826 * MAD + epsilon), "standardize" computes (x - mean) / sd, "robustize" computes (x - median) / IQR, and "center" computes x - median, which removes group offsets such as well-to-well shifts and keeps the units. Normalizing within groups that each hold one treatment removes the treatment effect along with the offset, so the recorded perturbation column, or another treatment column such as Metadata_Compound or Metadata_pert_iname, that is constant within every group of by raises a warning, whatever the method.

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

Column(s) defining the groups statistics are computed within, usually the plate. None fits one set of statistics globally.

reference str | None (default: 'negcon')

Rows to fit on: "negcon" (the default) for the rows whose Metadata_Control_Type is "negcon", None for all rows, or the name of a boolean obs column.

epsilon float (default: 1e-18)

Added to the MAD, matching pycytominer’s mad_robustize_epsilon. Unused by the other methods.

keep_raw bool (default: False)

Store the pre-normalization matrix in layers["raw"]. Off by default, because the layer doubles memory and the raw table is already on disk.

layer str | None (default: None)

Read this layer instead of X.

key_added str | None (default: None)

Write to layers[key_added] instead of overwriting X.

copy bool (default: False)

Return a normalized copy instead of normalizing in place.

Return type:

AnnData | None

Returns:

None, or the normalized copy when copy=True. Writes X or layers[key_added], and var["degenerate_scale"], or var["degenerate_scale_<key_added>"] when writing to a layer, which flags features that have no spread in some group or no reference values to centre on there, and comes with a warning; a feature with no spread in a group is set to NaN in that group, since it has no scale there. Drop the flagged features before computing distances. On a lazy X, read with mantispy.io.read() and lazy=True, the statistics are computed exactly by streaming the groups, and the result stays lazy until it is read or written.

Raises:

ValueError – If method is unknown, reference selects no rows at all or none in some group, or every feature has no spread in some group.