Evaluate Cell State Colocalization

This function computes cell state colocalization indices and assesses their statistical significance using permutation testing. Observed colocalization is compared against a null distribution generated by shuffling cell state labels within each cell type.

Usage

Colocalization(
  scmeta,
  coords = c("X", "Y"),
  SE = "SE",
  CellType = "CellType",
  radius = 50,
  k = 200,
  min.cell = 10,
  nperm = 1000,
  test = TRUE,
  ncores = 16
)

Arguments

scmeta

A data.frame containing single-cell metadata, where each row represents a cell. Row names should correspond to unique cell IDs.

coords

Character vector specifying column names in scmeta for spatial coordinates (e.g., c("X", "Y")).

SE

Character. Column name in scmeta specifying spatial ecotype labels.

CellType

Character. Column name in scmeta specifying cell type annotations. Permutations are performed within each cell type to preserve cell-type composition.

radius

Numeric. Maximum Euclidean distance threshold (in the same units as X and Y) for defining neighboring cells. Default is 50.

k

Integer. Number of nearest neighbors queried per cell before applying the distance filter. Default is 200.

min.cell

Integer. Minimum number of neighboring cells required for a cell to be included in the analysis. Cells with fewer neighbors are excluded. Default is 10.

nperm

Integer. Number of permutations used to generate the null distribution. Default is 1000.

test

Logical. Whether to compute statistical significance (P-values). If TRUE, both Z-scores and P-values are returned; otherwise only Z-scores are returned. Default is TRUE.

ncores

Integer. Number of cores to use for parallel computation of permutations. Default is 16.

Value

If test = TRUE, a list containing:

ColocIndex

A matrix of Z-scored colocalization indices between all cell states

Pval

A vector of P-values assessing co-association significance

If test = FALSE, returns only the Z-score matrix of colocalization indices.

Details

The function performs the following steps:

• Computes observed cell state colocalization using spatial neighbor relationships

• Generates a null distribution by permuting cell state labels within each cell type

• Computes mean and standard deviation of permuted colocalization matrices

• Standardizes observed values into Z-scores

• Optionally computes statistical significance using CoassociationTest

This approach preserves cell-type composition while testing whether spatial organization of cell states deviates from random expectation.