squidpy.experimental.im.calculate_image_features

squidpy.experimental.im.calculate_image_features(sdata, image_key=None, labels_key=None, shapes_key=None, scale=None, channels=None, features=None, tile_size=2048, overlap_margin='auto', align_mode='strict', adata_key_added='morphology', invalid_as_zero=True, n_jobs=1, inplace=True)[source]

Calculate per-cell features from segmentation masks.

Uses scikit-image regionprops for morphological/intensity features and squidpy-specific per-cell metrics (summary statistics, GLCM texture, colour histograms). Large images are automatically tiled into tile_size x tile_size chunks with overlap so that every cell is fully contained in exactly one tile.

Parameters:

  • sdata (SpatialData) – SpatialData object.

  • image_key (str | None) – Key in sdata.images. Optional: required only for intensity / squidpy features (and for shapes_key). Morphology-only runs need no image.

  • labels_key (str | None) – Key in sdata.labels with segmentation masks.

  • shapes_key (str | None) – Key in sdata.shapes (rasterized to labels internally).

  • scale (str | None) – Scale level for multi-scale data.

  • channels (list[str] | None) – Subset of channel names to use, matching those returned by spatialdata.models.get_channel_names(). None uses all channels. Integer indices are not accepted – always pass names.

  • features (list[str] | str | None) –

    Which features to compute (required; None is rejected). A list of flag strings drawn from two groups:

    • skimage regionprops – "skimage:morphology" (all shape props, from the mask alone) or "skimage:morphology:<prop>" for one (e.g. area); "skimage:intensity" (all per-channel intensity props, needs an image) or "skimage:intensity:<prop>" for one (e.g. intensity_mean). Morphology columns use skimage’s native names (area, centroid-0); intensity columns are suffixed with the channel name.

    • squidpy per-cell – "squidpy:summary" (per-channel mean / std / min / max), "squidpy:texture" (per-channel GLCM contrast, dissimilarity, homogeneity, energy, ASM, correlation), and "squidpy:color_hist" (per-channel intensity histogram).

  • tile_size (int) – Side length of the tiling grid (pixels).

  • overlap_margin (Union[int, Literal['auto']]) – Overlap around each tile to capture boundary cells. "auto" computes the minimum from the largest cell’s bounding box.

  • align_mode (Literal['strict']) – Only "strict" is supported: require image and labels to share the same pixel grid (same y/x sizes). Raise otherwise.

  • adata_key_added (str) – Key under which to store the result in sdata.tables.

  • invalid_as_zero (bool) – Replace inf and NaN values with zero.

  • n_jobs (int) – Number of parallel jobs for tile processing.

  • inplace (bool) – If True, store result in sdata.tables. Otherwise return it.

Return type:

AnnData | None

Returns:

AnnData when inplace=False, otherwise None.

Examples

>>> import squidpy as sq
>>> sq.experimental.im.calculate_image_features(
...     sdata,
...     image_key="image",
...     labels_key="cells",
...     features=["skimage:morphology", "skimage:intensity", "squidpy:summary"],
... )

Morphology-only needs no image:

>>> sq.experimental.im.calculate_image_features(
...     sdata, labels_key="cells", features=["skimage:morphology:area"]
... )

The per-cell table is stored in sdata.tables["morphology"].