sparrow.tb.allocate_intensity

sparrow.tb.allocate_intensity(sdata, img_layer=None, labels_layer=None, output_layer='table_intensities', channels=None, mode='mean', obs_stats=None, to_coordinate_system='global', chunks=None, append=False, calculate_center_of_mass=True, overwrite=True)

Allocates intensity values from a specified image layer to corresponding cells in a SpatialData object and returns an updated SpatialData object augmented with a table layer (sdata.tables[output_layer]) AnnData object with intensity values for each cell and each (specified) channel.

It requires that the image layer and the labels layer have the same shape and alignment.

Parameters:

• sdata (SpatialData) – The SpatialData object containing spatial information about cells.

• img_layer (str | None (default: None)) – The name of the layer in sdata that contains the image data from which to extract intensity information. Both the img_layer and labels_layer should have the same shape and alignment. If not provided, will use last img_layer.

• labels_layer (str | None (default: None)) – The name of the layer in sdata containing the labels (segmentation) used to define the boundaries of cells. These labels correspond with regions in the img_layer. If not provided, will use last labels_layer.

• output_layer (str, optional) – The table layer in sdata in which to save the AnnData object with the intensity values per cell.

• channels (int | str | Iterable[int] | Iterable[str] | None (default: None)) – Specifies the channels to be considered when extracting intensity information from the img_layer. This parameter can take a single integer or string or an iterable of integers or strings representing specific channels. If set to None (the default), intensity data will be aggregated from all available channels within the image layer.

• mode (Literal['sum', 'mean'] (default: 'mean')) – When mode is set to "sum", the total intensity for each label will be added to .X of the resulting output_layer; if set to "mean", it calculates the average intensity per label.

• obs_stats (list[str] | None (default: None)) – Stats that will be added to .obs of output_layer. Currently supported: ["sum", "mean", "count", "var", "kurtosis", "skew", "max", "min"]. If obs_stats contains mode, mode will not be added to .obs.

• to_coordinate_system (str (default: 'global')) – The coordinate system that holds img_layer and labels_layer.

• chunks (str | int | tuple[int, ...] | None (default: None)) – The chunk size for processing the image data. If provided as a tuple, desired chunksize for (z), y, x should be provided.

• append (bool (default: False)) – If set to True, and the labels_layer does not yet exist as a _REGION_KEY in sdata.tables[output_layer].obs, the intensity values extracted during the current function call will be appended (along axis=0) to any existing intensity data within the SpatialData object’s table attribute. If False, and overwrite is set to True any existing data in sdata.tables[output_layer] will be overwritten by the newly extracted intensity values. Note that we join the AnnData objects using anndata.concat with join="inner".

• calculate_center_of_mass (bool (default: True)) – If True, the center of mass of the labels in labels_layer will be calculated and added to sdata.tables[ output_layer ].obsm[_SPATIAL]. The center of mass is computed using scipy.ndimage.center_of_mass. Enabling calculate_center_of_mass will cause the labels_layer to be loaded into memory.

• overwrite (bool (default: True)) – If True, overwrites the output_layer if it already exists in sdata.

Return type:

SpatialData

Returns:

: An updated version of the input SpatialData object augmented with a table layer (sdata.tables[output_layer]) AnnData object.

Notes

• The function currently supports scenarios where the img_layer and labels_layer are aligned and have the same shape. Misalignments or differences in shape must be handled prior to invoking this function.

• Intensity calculation is performed per channel for each cell. The function aggregates this information and attaches it as a table (AnnData object) within the SpatialData object.

• Due to the memory-intensive nature of the operation, especially for large datasets, the function implements chunk-based processing, aided by Dask. The chunks parameter allows for customization of the chunk sizes used during processing. If sdata is backed by a Zarr store, we recommend setting chunks=None and ensuring that Dask arrays are chunked optimally for disk storage and computation.

Example

>>> sdata = sparrow.im.align_labels_layers(
...     sdata,
...     labels_layer_1="masks_nuclear",
...     labels_layer_2="masks_whole",
...     output_labels_layer="masks_nuclear_aligned",
...     output_shapes_layer=None,
...     overwrite=True,
...     chunks=256,
...     depth=100,
... )
>>>
>>> sdata = sparrow.tb.allocate_intensity(
...     sdata, img_layer="raw_image", labels_layer="masks_whole", output_layer="table_intensities", chunks=100
... )
>>>
>>> sdata = sparrow.tb.allocate_intensity(
...     sdata, img_layer="raw_image", labels_layer="masks_nuclear_aligned", output_later="table_intensities", chunks=100, append=True
... )
>>> # alternatively, save to different tables
>>> sdata = sparrow.tb.allocate_intensity(
...     sdata, img_layer="raw_image", labels_layer="masks_whole", output_layer="table_intensities_masks_whole", chunks=100
... )
>>>
>>> sdata = sparrow.tb.allocate_intensity(
...     sdata, img_layer="raw_image", labels_layer="masks_nuclear_aligned", output_later="table_intensities_masks_nuclear_aligned", chunks=100, append=True
... )