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, 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, rng=None)

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

Deprecated since version 1.8.4: calculate_niche is deprecated and will be removed in squidpy v1.9.0. Use one of the flavor-specific functions instead:

• calculate_niche_neighborhood()

• calculate_niche_utag()

• calculate_niche_cellcharter()

• calculate_niche_spatialleiden()

See also

calculate_niche_neighborhood

Neighborhood-profile flavor with an explicit signature.

calculate_niche_utag

UTAG flavor with an explicit signature.

calculate_niche_cellcharter

CellCharter flavor with an explicit signature.

calculate_niche_spatialleiden

SpatialLeiden flavor with an explicit signature.

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) –

  Deprecated, and removed with this function in v1.9.0; no flavor function takes it. Each library is fitted on its own and its labels are prefixed lib=<id>_, so a niche in one library is unrelated to the same-numbered niche in another.

  Either way, build the graphs per library with spatial_neighbors(). For niches shared across libraries, leave this unset. For niches per library, call a flavor function on each library’s slice, which is what this does:

  adata.obs["niche"] = "not_a_niche"
  for lib in adata.obs["library"].unique():
      sub = adata[adata.obs["library"] == lib].copy()
      sq.gr.calculate_niche_utag(sub, resolutions=0.5)
      adata.obs.loc[sub.obs_names, "niche"] = f"lib={lib}_" + sub.obs["utag_niche_res=0.5"].astype(str)
  

• 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. Spelled cluster_mask on the three flavors that build an embedding, and ‘spatialleiden’ raises rather than accepting one it cannot honour. 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’. Mask can look like the following. Here, the index values would correspond to adata.obs.index. The entries that are False are the ones ignored. mask = Series([False, False, True], index = [“a”, “b”, “c”])

• 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’.

• rng (int | integer | Sequence[int] | SeedSequence | Generator | BitGenerator | None) – Pseudorandom number generator state, following SPEC 7. When None, a new numpy.random.Generator is created using entropy from the operating system. Types other than numpy.random.Generator are passed to numpy.random.default_rng() to instantiate a generator. 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