testNicheAbundance

Test whether patients with more of a niche cell type express genes differently

Description

A between-patient question that the within-patient engines cannot see: does a gene’s expression in index cell type \(k\) differ between patients whose type-\(k\) cells sit, on average, among more type-\(n\) cells? (fitSpiDE() and testSpiDE() instead ask whether expression changes with niche density WITHIN each patient.)

Usage

testNicheAbundance(spe, ...)

## S4 method for signature 'ANY'
testNicheAbundance(
  spe,
  condition = NULL,
  sigma,
  index = NULL,
  niche = NULL,
  covariates = character(),
  assay = "counts",
  cell_type = "cell_type",
  sample_id = "sample_id",
  name = "Niche",
  min.cells = 10L,
  prior.count = 1,
  max.leverage = 3,
  genesets = NULL,
  type = c("competitive", "self-contained"),
  min.size = 5L,
  max.size = 500L,
  verbose = TRUE
)

Arguments

spe a SpatialExperiment with niche reducedDims (see buildNiches()).
… further arguments passed to the method.
condition a character, the colData column of the condition (constant within sample), or NULL.
sigma a numeric, the bandwidth (one value).
index, niche character vectors restricting the index / niche cell types (NULL = all). An index type is never tested against its own niche.
covariates a character vector of sample-level colData columns to adjust for (constant within sample; the first non-missing value per sample is used).
assay a character, the counts assay.
cell_type, sample_id the colData columns of cell type and sample.
name the niche reducedDim prefix.
min.cells minimum cells of the index type a sample must contribute.
prior.count the pseudocount in the log2-CPM.
max.leverage a number above 1: samples whose leverage in a design exceeds this multiple of the average leverage are down-weighted until none does (Inf turns this off).
genesets a named list of character vectors (gene identifiers as in rownames(spe)), or NULL to test genes.
type with genesets: “competitive” (the set against the other genes) or “self-contained” (the set alone).
min.size, max.size with genesets: set size limits after intersecting with each index type’s genes.
verbose report progress.

Details

For each index cell type \(k\) and niche cell type \(n\), regresses the per-sample pseudobulk log2-CPM of every gene in the type-\(k\) cells on the per-sample mean log1p niche density of type \(n\) around those cells, across samples, with a limma moderated \(t\)-test. Without a condition the design is ~ niche + covariates and one term is reported, “niche”: the association across all samples. With a condition the design is ~ niche * condition + covariates with the condition coded \(-1/2, +1/2\), and two terms are reported: “niche”, the association averaged over the two conditions, and “condition:niche”, its difference between them (second level minus first) – the patient-level counterpart of the condition-specific niche test that testSpiDE() runs within patients. Where the conditions leave fewer than two samples each, only “niche” is reported, across all samples.

Influential samples. With tens of samples, one sample at the edge of a niche type’s abundances can carry the whole slope, and a gene whose expression is extreme in that same sample then gets a far smaller \(p\)-value than the moderated \(t\) allows. Samples whose leverage (hat value) in the design exceeds max.leverage times the average are therefore down-weighted until none does. The weights come from the design alone, never from expression, so no gene’s own values decide how much a sample counts and the estimates stay unbiased; the permutation nulls set the default. Each row reports the largest leverage before the cap and how many samples were down-weighted.

Gene sets. With genesets, sets are tested instead of genes, each like a gene. Every gene of the index type is standardised across samples, and a set’s score in a sample is the mean of its genes’ standardised pseudobulk expression there. With type = “competitive” (the default), the mean over all other genes is subtracted, so a shift that moves every gene together does not make a set call. The scores then go through the same regression, leverage cap and multiple testing as genes. This is the between-patient counterpart of spiGSEA(), which tests sets on the within-patient slopes. The set version has not yet been checked against permutation nulls.

Multiple testing. q.global is a Benjamini-Hochberg adjustment over every row of the same term, so the two terms are separate families: a strong “niche” signal no longer loosens the threshold for “condition:niche”.

This is the association that fitSpiDE()’s per-patient intercepts deliberately absorb. It is a between-patient effect with \(S\) experimental units; it is not neighbourhood-dependent differential expression, and the two must not be conflated (see the model vignette). It was compositionTest() up to spiDE 0.99.22. Samples contributing fewer than min.cells cells of the index type are dropped for that index type, and an index type with fewer than three remaining samples is skipped.

Value

a data.frame with one row per (gene, index type, niche type, term): gene, index, niche, term, estimate (log2-CPM per unit log1p density), t, p, n_patients, leverage (the largest sample leverage before the cap, as a multiple of the average), downweighted (the samples down-weighted), q (BH within each (index, niche, term) over genes) and q.global (BH over every row of the same term). With genesets, one row per (set, index type, niche type, term): the column gene becomes set, followed by size, and a direction column is added; estimate is in standard deviations of the set score per unit log1p density.

Examples

library("spiDE")

data(toySpiDE)
spe <- buildNiches(toySpiDE, sigma = 30)
na <- testNicheAbundance(spe, condition = "condition", sigma = 30)
head(na[order(na$p), ])
sets <- list(first = paste0("G", 1:6), second = paste0("G", 7:12))
nas <- testNicheAbundance(spe, condition = "condition", sigma = 30,
                          genesets = sets, verbose = FALSE)
head(nas)