rapids_singlecell.gr.calculate_niche

rapids_singlecell.gr.calculate_niche#

rapids_singlecell.gr.calculate_niche(adata, *, flavor, groups=None, n_neighbors=15, resolutions=(0.5,), distance=None, n_hop_weights=None, abs_nhood=False, scale=True, min_niche_size=None, aggregation='mean', n_components=10, use_rep=None, gmm_init='random_from_data', spatial_connectivities_key='spatial_connectivities', random_state=42, copy=False)[source]#

Compute spatial niches on the GPU.

Mirrors squidpy.gr.calculate_niche() for the "neighborhood", "utag" and "cellcharter" flavors. The spatial graph in adata.obsp[spatial_connectivities_key] must be precomputed (e.g. via squidpy.gr.spatial_neighbors()).

Parameters:
adata AnnData

Annotated data matrix.

flavor Literal['neighborhood', 'utag', 'cellcharter']

  • "neighborhood" cluster cell-type frequency profiles among spatial neighbors [].

  • "utag" cluster gene expression smoothed across spatial neighbors [].

  • "cellcharter" shell-aggregate gene expression over n-hop neighborhoods, PCA-reduce, then cluster with a Gaussian mixture [].

groups str | None (default: None)

Column in adata.obs with cell-type labels. Required for flavor="neighborhood".

n_neighbors int (default: 15)

Neighbors for the post-aggregation kNN graph passed to leiden.

resolutions float | Sequence[float] (default: (0.5,))

Resolution(s) for leiden. A label column is written for each value. Ignored for flavor="cellcharter".

distance int | None (default: None)

Number of n-hop neighborhoods to include. Defaults to 3 for cellcharter, 1 for neighborhood.

n_hop_weights Sequence[float] | None (default: None)

Per-hop weights when distance > 1 (flavor="neighborhood" only).

abs_nhood bool (default: False)

Use absolute neighbor counts instead of per-cell relative frequencies (flavor="neighborhood" only).

scale bool (default: True)

Z-score the neighborhood profile before clustering (flavor="neighborhood" only).

min_niche_size int | None (default: None)

Discard niches with fewer cells than this; relabel as "not_a_niche".

aggregation Literal['mean', 'variance'] (default: 'mean')

Per-shell aggregation for flavor="cellcharter". "mean" (default) or "variance".

n_components int (default: 10)

Number of mixture components for flavor="cellcharter".

use_rep str | None (default: None)

Key in adata.obsm to use as the embedding for flavor="cellcharter"; if provided, the first n_components columns are used and the shell-aggregation + PCA step is skipped.

gmm_init Literal['random_from_data', 'kmeans', 'sklearn_kmeans'] (default: 'random_from_data')

GMM initialization for flavor="cellcharter". "random_from_data" (default) matches Squidpy’s CellCharter path. "kmeans" uses native cuML KMeans. "sklearn_kmeans" uses sklearn-compatible k-means++ seeding followed by cuML KMeans.

spatial_connectivities_key str (default: 'spatial_connectivities')

Key in adata.obsp with the spatial connectivity matrix.

random_state int (default: 42)

Random seed for leiden / GMM.

copy bool (default: False)

Return a copy with the niche columns instead of writing in place.

Return type:

AnnData | None