test_niche_abundance

test_niche_abundance(
    adata,
    condition=None,
    sigma=None,
    index=None,
    niche=None,
    covariates=(),
    assay='counts',
    cell_type='cell_type',
    sample_id='sample_id',
    name='Niche',
    min_cells=10,
    prior_count=1,
    max_leverage=3,
    genesets=None,
    type='competitive',
    min_size=5,
    max_size=500,
    verbose=True,
)

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

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? (R testNicheAbundance.)

For each index type k and niche type n, the per-sample pseudobulk log2-CPM of every gene in the type-k cells is regressed 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, "niche", is reported. 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, second level minus first). Where the conditions leave fewer than two samples each, only "niche" is reported.

Samples whose leverage in the design exceeds max_leverage times the average are down-weighted until none does (weights from the design alone, never from expression). With genesets, sets are tested instead of genes: genes are standardised across samples and a set’s score is the mean of its genes’ values, less the other genes’ mean when type="competitive". q_global of R (column q.global) is one Benjamini-Hochberg family per term.

Parameters

Name Type Description Default
adata AnnData With niche matrices in obsm (see build_niches). required
condition str The obs column of a two-level condition (constant within sample). None
sigma float The niche bandwidth (one value). Required: None raises an error. None
index str or sequence of str Restrict the index cell types. None
niche str or sequence of str Restrict the niche cell types. An index type is never tested against its own niche: itself, or the merged niche it is a member of (see merge_niches). None
covariates str or sequence of str Sample-level obs columns to adjust for (first non-missing value per sample). ()
assay str The layer of raw counts. "counts"
cell_type str The obs column of the cell type. "cell_type"
sample_id str The obs column of the sample. "sample_id"
name str The niche key prefix. "Niche"
min_cells int Minimum cells of the index type a sample must contribute (else dropped for that type). 10
prior_count float The pseudocount of the log2-CPM. 1
max_leverage float A number above 1; inf turns the cap off. 3
genesets dict {set name: gene identifiers}; tests sets instead of genes. None
type ('competitive', 'self-contained') With genesets: the set against the other genes, or the set alone. "competitive"
min_size int With genesets: smallest set size, after intersecting with each index type’s genes. 5
max_size int With genesets: largest set size, after intersecting with each index type’s genes. 500
verbose bool Report progress on stderr. True

Returns

Name Type Description
pandas.DataFrame One row per (gene, index type, niche type, term) with columns gene, index, niche, term, estimate, t, p, n_patients, leverage, downweighted, q (BH within each index, niche, term) and q.global. With genesets the column gene becomes set, followed by size, and a direction column is added.

See Also

build_niches : Builds the niche matrices this reads. spi_gsea : The within-patient gene-set tests.

Examples

from spidepy import build_niches, test_niche_abundance
from spidepy.datasets import toy_spide
adata = build_niches(toy_spide(), sigma=30)
ab = test_niche_abundance(adata, condition="condition", sigma=30, verbose=False)
ab.shape
(240, 12)
sorted(ab["term"].unique())
['condition:niche', 'niche']