Computes pairwise spatial interaction scores between phenotypes.
Usage
InteractionMatrix(
object,
radius,
method = c("analytic", "permutation"),
n_perm = 100L,
seed = NULL
)Arguments
- object
An
SpatialCellData-classobject.- radius
Finite nonnegative numeric scalar. Radius for defining spatial neighbourhoods.
- method
Character.
"analytic"(default) compares observed neighbour counts to an expectation under random mixing;"permutation"builds the null by shuffling phenotype labels within each sample, addingz_scoreandp_valuecolumns.- n_perm
Integer of at least two. Number of label permutations when
method = "permutation". Default100.- seed
Signed integer scalar or
NULL. Random seed for the permutation null. Invalid permutation controls are rejected before RNG state changes;n_permandseedare ignored by the analytic method.
Value
A data frame with columns from, to, observed,
expected, and interaction_score; the permutation method adds
z_score and p_value. Scores are log2 observed/expected:
zero observations with positive expectation give negative infinity;
zero expectation retains the historical zero-score convention.
Permutation p_value is a two-sided normal approximation from z_score,
not an empirical permutation tail probability. If the sampled null has
zero variance but its mean differs from the observed count, both z_score
and p_value are NA. A zero-variance sampled null whose mean matches
the observation retains the compatibility convention z_score = 0,
p_value = 1.
Examples
set.seed(42)
counts <- matrix(rnorm(200), nrow = 100,
dimnames = list(NULL, c("CD3", "CD8")))
coords <- data.frame(x = runif(100, 0, 500), y = runif(100, 0, 500))
meta <- data.frame(cell_id = 1:100, sample_id = "s1",
phenotype = sample(c("CD3+", "CD8+", "Tumour"), 100, replace = TRUE))
obj <- CreateSpatialObject(counts, coords, meta)
InteractionMatrix(obj, radius = 50)
#> <phenoscapR> Phenotype interaction matrix
#> 3 phenotypes; score = log2(observed / expected)
#> strongest attractions:
#> from to interaction_score
#> CD3+ CD3+ 0.57196484
#> CD3+ CD8+ 0.46726746
#> CD8+ CD3+ 0.46726746
#> CD8+ CD8+ 0.04508789
#> CD3+ Tumour -0.08116917