squidpy.experimental.im.normalize_stains

squidpy.experimental.im.normalize_stains(sdata, image_key, reference, *, scale='auto', method_params=None, image_key_added=None, inplace=True, output_dtype=None, tissue_mask_key=None, preserve_background=True)[source]

Normalize an image to a fitted stain reference.

Parameters:

  • sdata (SpatialData) – SpatialData object containing the source image.

  • image_key (str) – Key of the RGB image in sdata.images to normalize.

  • reference (StainReference) – A StainReference fitted with fit_stain_reference(). Dispatch is on reference.method.

  • scale (Union[str, Literal['auto']]) – Scale level to normalize. "auto" (default) uses the finest level so the result is not downsampled; source statistics are reduced lazily so memory stays bounded.

  • method_params (ReinhardParams | MacenkoParams | VahadaneParams | Mapping[str, Any] | None) – Params matching reference.method (instance, mapping, or None).

  • image_key_added (str | None) – Key for the written image when inplace=True. If None (default), f"{image_key}_normalized" is used. Ignored when inplace=False.

  • inplace (bool) – If True (default), write the normalized image to sdata.images[image_key_added] (rebuilding the pyramid for multiscale sources, preserving transforms) and return None; raises if the key already exists. If False, leave sdata untouched and return the lazy normalized DataArray.

  • output_dtype (DTypeLike | None) – Dtype of the result. If None (default), the source image’s dtype is used. The reconstruction is clipped to that dtype’s valid range and rounded (for integer dtypes) at the write boundary.

  • tissue_mask_key (str | None) – Key of a tissue-label element in sdata.labels restricting the source statistics to tissue pixels. As for fit_stain_reference(), a tissue mask is required (defaults to f"{image_key}_tissue"; raises if missing).

  • preserve_background (bool) – If True (default), non-tissue (background) pixels are passed through unchanged from the source image, so the normalization recolours only tissue. The colour map is a global linear transform that would otherwise tint background/white pixels. Set False for full-frame normalization.

Return type:

DataArray | None

Returns:

None if inplace=True (the image is written), otherwise the lazy normalized xarray.DataArray.