harpy.tb.spatial_pixel_neighbors

harpy.tb.spatial_pixel_neighbors#

harpy.tb.spatial_pixel_neighbors(sdata, labels_name, size=20, mode='most_frequent', grid_type='hexagon', subset=None, spatial_neighbors_kwargs=mappingproxy({}), nhood_enrichment_kwargs=mappingproxy({}), seed=0, key_added='cluster_id', spatial_key='spatial')#

Computes spatial pixel neighbors and performs neighborhood enrichment analysis.

This function extracts grid-based cluster labels from the specified labels element of a SpatialData object, subdivides the spatial domain into a grid using a specified sampling interval, and computes spatial neighbors along with neighborhood enrichment statistics. The resulting AnnData object stores the cluster labels as a categorical observation (under the key provided by key_added) and the corresponding spatial coordinates in its .obsm attribute. squidpy is used for the spatial neighbors computation and the neighborhood enrichment analysis (i.e. squidpy.gr.spatial_neighbors() and squidpy.gr.nhood_enrichment()). Results can then be visualized using e.g. squidpy.pl.nhood_enrichment().

Parameters:

  • sdata (SpatialData) – The input SpatialData object containing spatial data.

  • labels_name (str) – The key in sdata.labels from which the cluster label data is extracted. This labels element is typically obtained using harpy.im.flowsom.

  • size (int (default: 20)) – If mode is "center", size determines the sampling interval for constructing the spatial grid. This value determines the distance (in pixels) between consecutive grid points along each axis. A smaller value produces a denser grid (higher resolution), while a larger value yields a sparser grid. If mode is "most_frequent", this value is passed to harpy.im.add_grid_labels().

  • mode (Literal['most_frequent', 'center'] (default: 'most_frequent')) – The method used to extract grid-based pixel cluster labels. Can be either "most_frequent" or "center". - "most_frequent": Assigns each grid point the most frequently occurring label within the surrounding neighborhood, determined by size and grid_type. This approach smooths local variations and provides a more representative cluster label for each region. - "center": Assigns each grid point the label of the pixel at its exact center, without considering neighboring pixels. This method maintains high spatial precision but may be more sensitive to local noise. When using "most_frequent", the grid_type parameter determines whether a hexagonal or square grid is used for sampling. If "center" is selected, grid_type is ignored.

  • grid_type (Literal['hexagon', 'square'] (default: 'hexagon')) – The type of grid used when extracting pixel cluster labels from labels_name. Can be either "hexagon" or "square". This parameter is only relevant when mode="most_frequent" and is ignored when mode="center". Passed to harpy.im.add_grid_labels.

  • subset (list[int] | None (default: None)) – A list of labels to subset the analysis to, or None to include all labels in labels_name.

  • spatial_neighbors_kwargs (Mapping[str, Any] (default: mappingproxy({}))) – Additional keyword arguments to be passed to squidpy.gr.spatial_neighbors().

  • nhood_enrichment_kwargs (Mapping[str, Any] (default: mappingproxy({}))) – Additional keyword arguments to be passed to squidpy.gr.nhood_enrichment().

  • seed (int (default: 0)) – The random seed used for reproducibility in the neighborhood enrichment computation.

  • key_added (str (default: 'cluster_id')) – The key under which the extracted cluster labels will be stored in .obs of the returned AnnData object.

  • spatial_key (str (default: 'spatial')) – The key in the resulting AnnData .obsm that will hold the x and y center of the instances (grid).

Return type:

AnnData

Returns:

: An AnnData object enriched with spatial neighbor information and neighborhood enrichment statistics.

See also

harpy.im.flowsom

flowsom pixel clustering on image elements.

harpy.im.add_grid_labels

construct a grid.