squidpy.experimental.im.decompose_stains

squidpy.experimental.im.decompose_stains(sdata, image_key, reference_or_method, *, scale='auto', method_params=None, white_point=None, image_key_added=None, inplace=True, output_dtype=<class 'numpy.float16'>, tissue_mask_key=None, include_residual=True)[source]

Decompose an image into separate per-stain concentration maps.

Parameters:

  • sdata (SpatialData) – The SpatialData object and the RGB image key to decompose.

  • image_key (str) – The SpatialData object and the RGB image key to decompose.

  • reference_or_method (Union[StainReference, Literal['macenko', 'vahadane']]) – Either a decomposition StainReference (its stain matrix and white point are used) or a method name ("macenko"/"vahadane") to fit on this image first. The reference is the provenance record of how the maps were produced (method, stain matrix, white point).

  • scale (Union[str, Literal['auto']]) – As for fit_stain_reference() (only used when a method name is given; a reference is projected as-is and needs no tissue mask).

  • method_params (ReinhardParams | MacenkoParams | VahadaneParams | Mapping[str, Any] | None) – As for fit_stain_reference() (only used when a method name is given; a reference is projected as-is and needs no tissue mask).

  • white_point (ndarray | None) – As for fit_stain_reference() (only used when a method name is given; a reference is projected as-is and needs no tissue mask).

  • tissue_mask_key (str | None) – As for fit_stain_reference() (only used when a method name is given; a reference is projected as-is and needs no tissue mask).

  • image_key_added (str | None) – Key prefix for the written images when inplace=True. If None (default), image_key is used, so each stain is written as its own single-channel image sdata.images[f"{image_key}_{stain}"] (e.g. f"{image_key}_hematoxylin"). Ignored when inplace=False.

  • inplace (bool) – If True (default), write each stain as a separate single-channel image under the image_key_added prefix and return None; the write is atomic (all target keys are validated free before any is written). If False, leave sdata untouched and return the maps as a dict.

  • output_dtype (DTypeLike) – Dtype of the concentration maps. Defaults to float16 (half the storage; ~3 significant figures, adequate for concentrations); pass float32 for strict quantification.

  • include_residual (bool) – If True (default), also produce the "residual" map. The residual is the absorbance along the complement direction - a diagnostic of decomposition quality (extra chromogen, artifacts, or a poor fit), not a biological stain. Set False to keep only hematoxylin/eosin.

Return type:

dict[str, DataArray] | None

Returns:

None if inplace=True (the maps are written as separate images), otherwise a dict mapping each stain name to its (y, x) concentration DataArray ("hematoxylin", "eosin", and "residual" unless dropped).