Compute co-association of cell states across samples

This function computes pairwise co-association (Pearson correlation) between cell states (defined as combinations of spatial ecotype (SE) and cell type) across samples. Co-association is evaluated under multiple abundance calculation schemes that differ in the inclusion of NonSE cells and the treatment of absent cell states, and the resulting correlation matrices are averaged to obtain a robust co-association matrix.

Usage

Coassociation(
  scmeta,
  Sample = "Sample",
  SE = "SE",
  CellType = "CellType",
  NonSE = "NonSE",
  nperm = 1000,
  test = TRUE
)

Arguments

scmeta

A data.frame containing single-cell metadata.

Sample

Character. Column name in scmeta specifying sample IDs.

SE

Character. Column name in scmeta specifying spatial ecotype labels.

CellType

Character. Column name in scmeta specifying cell type annotations.

NonSE

Character. Label used to denote non-SE cells (default: "NonSE").

nperm

Integer. Number of permutations used for significance testing when test = TRUE. Default is 1000.

test

Logical. If TRUE (default), performs permutation testing using CoassociationTest() and returns both the co-association matrix and the corresponding p-value matrix. If FALSE, only the co-association matrix is returned.

Value

If test = TRUE, a list with the following components:

CoassociationIndex

A symmetric matrix of averaged Pearson correlation coefficients between cell states.

Pval

A matrix of permutation-based p-values for the co-association scores.

If test = FALSE, a symmetric matrix of averaged Pearson correlation coefficients between cell states.

Details

Cell states are defined as concatenations of SE and cell type labels. For each sample and cell type, the relative abundance of each cell state is calculated under four schemes:

1. Including both SE and NonSE cell states, with absent states represented as NA.

2. Excluding NonSE cell states, with absent states represented as NA.

3. Including both SE and NonSE cell states, with absent states filled with zero.

4. Excluding NonSE cell states, with absent states filled with zero.

Pairwise Pearson correlations between cell states are then computed across samples for each abundance matrix using cor(method = "pearson", use = "pairwise.complete.obs"). The final co-association matrix is obtained by averaging the correlation coefficients across the four schemes while ignoring missing values.