calculate_niche_neighborhood#
- squidpy.gr.calculate_niche_neighborhood(data, *, groups, resolutions, n_neighbors=15, spatial_connectivities_key='spatial_connectivities', scale=True, distance=1, abs_nhood=False, n_hop_weights=None, embedding_key_added='niche_embedding', key_added='nhood_niche', min_niche_size=None, cluster_mask=None, copy=False, table_key=None, flavor='igraph', n_iterations=-1, rng=None)[source]#
Compute spatial niches from local cell-type composition.
Follows monkeybread’s immunitastx/monkeybread
This method represents every observation by a neighborhood composition profile: a vector describing the cell-type labels observed in its local spatial neighborhood. Observations with similar surrounding cell-type compositions are then grouped into niches using Leiden clustering.
A spatial connectivity graph must already be available in
adata.obsp[spatial_connectivities_key]. The graph defines which observations are spatial neighbors; this function does not construct the graph itself.For each observation
i, the method:Retrieves observations reachable from
iin the spatial graph up todistancehops away.Counts the values of
groupsamong those neighboring observations.Optionally combines profiles from different graph-hop distances using
n_hop_weights.Uses either raw counts or normalized cell-type proportions as the neighborhood profile.
Optionally z-scores the resulting profile across observations (scale argument).
Constructs a k-nearest-neighbor graph from the profile embedding and applies Leiden clustering at each requested resolution.
Thus, a niche is defined by a recurring local cellular composition, rather than by the expression profile of an individual observation. For example, cells surrounded by many immune cells and fibroblasts may be assigned to one niche even when those cells themselves have different expression profiles or cell-type labels.
- Parameters:
- adata
Annotated data object.
- groups
str Column in
adata.obscontaining categorical labels used to define neighborhood composition, such as cell types, cell states, clusters, or anatomical annotations.- resolutions
float|list[float] Resolution parameter(s) for Leiden clustering. A single value produces one niche annotation. Supplying multiple values performs Leiden clustering separately for each resolution and adds one niche column per resolution to
adata.obs.- n_neighbors
int(default:15) Number of nearest neighbors used to construct the k-nearest-neighbor graph on the neighborhood composition embedding before Leiden clustering.
- spatial_connectivities_key
str(default:'spatial_connectivities') Key in
anndata.AnnData.obspcontaining the spatial connectivity matrix.- scale
bool(default:True) Whether to z-score each neighborhood-profile feature across observations before constructing the clustering graph.
- distance
int(default:1) Maximum number of graph hops used to construct each neighborhood profile.
distance=1uses direct spatial neighbors. Larger values incorporate increasingly distal observations in the spatial graph.- abs_nhood
bool(default:False) Whether to use absolute group counts in the neighborhood profile.
If
False(the default), counts are normalized to proportions, so each profile captures relative neighborhood composition and is less sensitive to differences in neighborhood size.If
True, raw counts are retained, so both composition and the total number of reachable neighbors can influence the embedding.- n_hop_weights
list[float] |None(default:None) Optional weights used when combining contributions from successive graph-hop distances. If provided, the weights determine the relative contribution of direct and higher-order neighbors to the final neighborhood profile. If not provided, equal weights are used.
- cluster_mask
Series|None(default:None) Boolean
pandas.Seriesindexed likeanndata.AnnData.obs.Falseobservations are labeled'not_a_niche'and take no part in the clustering, though they still reach their neighbors through the graph. Observations it omits are kept. To drop them from the graph as well, subset and rebuild it withspatial_neighbors().- key_added
str(default:'nhood_niche') Stem of the
anndata.AnnData.obscolumns the labels are written to, one per resolution, namedf"{key_added}_res={resolution}".- embedding_key_added
str(default:'niche_embedding') Controls the name of the key to be added in
anndata.AnnData.obsm, which will hold the niche embedding computed.- min_niche_size
int|None(default:None) Minimum number of observations required for a niche. Niches with fewer observations are relabeled
'not_a_niche'.- copy
bool(default:False) If
True, return the result, otherwise save it to theadataobject.- table_key
str|None(default:None) Key in
spatialdata.SpatialData.tableswhere the table is stored. Required whenadatais aspatialdata.SpatialDataobject and ignored otherwise.- flavor
Literal['igraph','leidenalg'] (default:'igraph') Leiden backend passed to
scanpy.tl.leiden(). Defaults to'igraph'(the'leidenalg'backend is deprecated in scanpy).- n_iterations
int(default:-1) Number of Leiden iterations.
-1iterates until convergence.- rng
int|integer|Sequence[int] |SeedSequence|Generator|BitGenerator|None(default:None) Pseudorandom number generator state, following SPEC 7. When None, a new
numpy.random.Generatoris created using entropy from the operating system. Types other thannumpy.random.Generatorare passed tonumpy.random.default_rng()to instantiate a generator. Every resolution is clustered with an independent rng derived from it.
- Returns:
AnnData|None– Ifcopy=True, returns a copy ofadatawith the neighborhood profile stored in.obsm[embedding_key_added]and niche assignments added to.obs. Otherwise, modifiesadatain place and returnsNone.
Notes
This approach is most appropriate when niches are expected to differ primarily in local cellular composition. In contrast,
calculate_niche_utag()andcalculate_niche_cellcharter()derive niche embeddings from spatially aggregated molecular or latent features rather than from categorical group frequencies.