squidpy.gr.calculate_niche

squidpy.gr.calculate_niche(data, flavor, library_key=None, mask=None, groups=None, n_neighbors=None, resolutions=None, min_niche_size=None, scale=True, abs_nhood=False, distance=None, n_hop_weights=None, aggregation=None, n_components=None, random_state=42, spatial_connectivities_key='spatial_connectivities', latent_connectivities_key='connectivities', layer_ratio=1.0, n_iterations=-1, use_weights=True, use_rep=None, inplace=True, *, table_key=None)[source]

Calculate niches (spatial clusters) based on a user-defined method in ‘flavor’. The resulting niche labels with be stored in ‘adata.obs’.

Parameters:

  • adata – Annotated data object.

  • flavor (Literal['neighborhood', 'utag', 'cellcharter', 'spatialleiden']) –

    Method to use for niche calculation. Available options are:

    • ’neighborhood’ - cluster the neighborhood profile.

    • ’utag’ - use utag algorithm (matrix multiplication).

    • ’spatialleiden’ - cluster spatially resolved omics data using Multiplex Leiden.

    • ’cellcharter’ - a simplified version of CellCharter’s approach, using PCA for dimensionality reduction. An arbitrary embedding can be used instead of PCA by setting the use_rep parameter which will try to find the embedding in adata.obsm.

  • library_key (str | None) – If multiple library_id, column in anndata.AnnData.obs which stores mapping between library_id and obs. If provided, niches will be calculated separately for each unique value in this column. Each niche will be prefixed with the library identifier.

  • table_key (str | None) – Key in spatialdata.SpatialData.tables where the table is stored. Required when adata is a spatialdata.SpatialData object and ignored otherwise.

  • mask (Series) – Boolean array to filter cells which won’t get assigned to a niche. Note that if you want to exclude these cells during neighborhood calculation already, you should subset your AnnData table before running ‘sq.gr.spatial_neigbors’.

  • groups (str | None) – Groups based on which to calculate neighborhood profile (E.g. columns of cell type annotations in adata.obs). Required if flavor == ‘neighborhood’.

  • n_neighbors (int | None) – Number of neighbors to use for ‘scanpy.pp.neighbors’ before clustering using leiden algorithm. Required if flavor == ‘neighborhood’ or flavor == ‘utag’.

  • resolutions (float | tuple[float, float] | list[float | tuple[float, float]] | None) – List of resolutions to use for leiden clustering. In the case of spatialleiden you can pass a tuple. Resolution for the latent space and spatial layer, respectively. A single float applies to both layers. Required if flavor == ‘neighborhood’ or flavor == ‘utag’. Optional if flavor == ‘spatialleiden’.

  • min_niche_size (int | None) – Minimum required size of a niche. Niches with fewer cells will be labeled as ‘not_a_niche’. Optional if flavor == ‘neighborhood’.

  • scale (bool) – If ‘True’, compute z-scores of neighborhood profiles. Optional if flavor == ‘neighborhood’.

  • abs_nhood (bool) – If ‘True’, calculate niches based on absolute neighborhood profile. Optional if flavor == ‘neighborhood’.

  • distance (int | None) – n-hop neighbor adjacency matrices to use e.g. [1,2,3] for 1-hop,2-hop,3-hop neighbors respectively or “5” for 1-hop,…,5-hop neighbors. 0 (self) is always included. Required if flavor == ‘cellcharter’. Optional if flavor == ‘neighborhood’.

  • n_hop_weights (list[float] | None) – How to weight subsequent n-hop adjacency matrices. E.g. [1, 0.5, 0.25] for weights of 1-hop, 2-hop, 3-hop adjacency matrices respectively. Optional if flavor == ‘neighborhood’ and distance > 1.

  • aggregation (str | None) – How to aggregate count matrices. Either ‘mean’ or ‘variance’. Required if flavor == ‘cellcharter’.

  • n_components (int | None) – Number of components to use for GMM. Required if flavor == ‘cellcharter’.

  • random_state (int) – Random state to use for GMM or SpatialLeiden. Optional if flavor == ‘cellcharter’ or flavor == ‘spatialleiden’.

  • spatial_connectivities_key (str) – Key in adata.obsp where spatial connectivities are stored. Required if flavor == ‘spatialleiden’.

  • latent_connectivities_key (str) – Key in adata.obsp where gene expression connectivities are stored. Required if flavor == ‘spatialleiden’.

  • layer_ratio (float) – The ratio of the weighting of the layers; latent space vs spatial. A higher ratio will increase relevance of the spatial neighbors and lead to more spatially homogeneous clusters. Optional if flavor == ‘spatialleiden’.

  • n_iterations (int) – Number of iterations to run the Leiden algorithm. If the number is negative it runs until convergence. Optional if flavor == ‘spatialleiden’.

  • use_weights (bool | tuple[bool, bool]) – Whether to use weights for the edges for latent space and spatial neighbors, respectively. A single bool applies to both layers. Optional if flavor == ‘spatialleiden’.

  • use_rep (str | None) – Key in adata.obsm where the embedding is stored. If provided, this embedding will be used instead of PCA for dimensionality reduction. Optional if flavor == ‘cellcharter’.

  • inplace (bool) – If ‘True’, perform the operation in place. If ‘False’, return a new AnnData object with the niche labels.

Return type:

AnnData | None