squidpy.gr.nhood_enrichment

squidpy.gr.nhood_enrichment(adata, cluster_key, library_key=None, connectivity_key=None, n_perms=1000, numba_parallel=False, rng=None, copy=False, n_jobs=None, backend='loky', show_progress_bar=True, *, table_key=None)[source]

Compute neighborhood enrichment by permutation test.

Changed in version 1.8.4: Every permutation now uses an independent numpy.random.Generator spawned from a numpy.random.SeedSequence. Consequently the permutation-based results no longer depend on n_jobs / backend, but results obtained with a given seed differ from those produced by squidpy < 1.8.4. See #1232 and #1233.

Changed in version 1.8.4: seed / random_state were renamed to rng, which also accepts a numpy.random.Generator (SPEC 7). The old names still work but emit a FutureWarning.

Parameters:

  • adata (AnnData | SpatialData) – Annotated data object.

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

  • cluster_key (str) – Key in anndata.AnnData.obs where clustering is stored.

  • library_key (str | None) – If multiple library_id, column in anndata.AnnData.obs which stores mapping between library_id and obs.

  • connectivity_key (str | None) – Key in anndata.AnnData.obsp where spatial connectivities are stored. Default is: anndata.AnnData.obsp ['spatial_connectivities'].

  • n_perms (int) – Number of permutations for the permutation test.

  • numba_parallel (bool) – Whether to use numba.prange() or not. If None, it is determined automatically. For small datasets or small number of interactions, it’s recommended to set this to False.

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

  • copy (bool) – If True, return the result, otherwise save it to the adata object.

  • n_jobs (int | None) – Number of parallel jobs to use. None is serial and -1 uses all available cores; asking for more cores than are available warns and falls back to all of them, while 0 and values below -1 raise, since scanpy only supports n_jobs >= -1. For backend="loky", the number of cores used by numba for each job spawned by the backend will be set to 1 in order to overcome the oversubscription issue in case you run numba in your function to parallelize. To set the absolute maximum number of threads in numba for your python program, set the environment variable: NUMBA_NUM_THREADS before running the program.

  • backend (str) – Parallelization backend to use. See joblib.Parallel for available options.

  • show_progress_bar (bool) – Whether to show the progress bar or not.

Return type:

NhoodEnrichmentResult | None

Returns:

If copy = True, returns a NhoodEnrichmentResult with the z-score and the enrichment count.

Otherwise, modifies the adata with the following keys: