nichesphere.tl.get_spatial_radius_BG_OEratios_DF

nichesphere.tl.get_spatial_radius_BG_OEratios_DF#

nichesphere.tl.get_spatial_radius_BG_OEratios_DF(adata, cluster_col, radius=40.0, n_permutations=1000)#

Optimized version of get_spatial_radius_BG_OEratios_DF using sparse matrix multiplication.

Generate a null distribution of co-localization probabilities by label permutation.

The spatial graph is built once and held fixed. Cell type labels are then randomly shuffled n_permutations times, and the radius-based co-localization matrix is recomputed for each permutation. The resulting distribution can be used to test whether observed co-localization probabilities deviate significantly from what is expected under spatial randomness (see nichesphere.coloc.OvsE_coloc_test_adjPval).

Parameters:

  • adata (anndata.AnnData) – Spatial AnnData object. Must contain cell centroid coordinates in adata.obsm['spatial'] and a categorical cluster annotation column in adata.obs.

  • cluster_col (str) – Name of the categorical column in adata.obs containing cluster labels.

  • radius (float, default 40.0) – Spatial radius used to define the neighborhood graph. Should match the radius used in compute_radius_colocalization_matrix.

  • n_permutations (int, default 1000) – Number of label-permutation replicates to generate.

Returns:

DataFrame of shape (n_permutations, n_clusters²) containing the null co-localization probabilities. Columns are named '{CT1}-{CT2}' for all cluster pairs (including same-cluster pairs), following the convention expected by nichesphere.coloc.OvsE_coloc_test_adjPval. Rows correspond to individual permutation replicates.

Return type:

pd.DataFrame

Notes

The spatial adjacency graph is computed once before permutation, so runtime scales with n_permutations rather than re-fitting the neighbor index each time.

Examples

>>> bg_df = nichesphere.tl.get_spatial_radius_BG_OEratios_DF(
...     adata, cluster_col='cell_type', radius=300.0, n_permutations=1000
... )
>>> OvsE_df, stats = nichesphere.coloc.OvsE_coloc_test_adjPval(
...     observedColocProbs=coloc.stack(),
...     expectedColocProbs=bg_df.mean(),
...     testDistribution_df=bg_df,
...     ...
... )