GPTomics Version Compatibility
Reference examples tested with: diffcyt 1.22+, CATALYST 1.26+, edgeR 4.0+, limma 3.58+.
Before using code patterns, verify installed versions match. If versions differ:
- R:
packageVersion('<pkg>')then?function_nameto verify parameters
testDA_edgeR/testDS_limma are diffcyt functions operating on count/median objects from calcCounts/calcMedians; the CATALYST-integrated path is the diffcyt() wrapper on the SCE. Confirm the signature with ?diffcyt before relying on it.
Differential Analysis
"Compare cell populations between my conditions" -> Test cluster frequencies (DA) and within-cluster marker expression (DS) between groups, with the sample (not the cell) as the unit.
- R:
diffcyt::diffcyt(sce, analysis_type='DA', method_DA='diffcyt-DA-edgeR', design, contrast) - R:
diffcyt(sce, analysis_type='DS', method_DS='diffcyt-DS-limma', ...)
The Single Most Important Modern Insight -- The Sample Is the Experimental Unit, Not the Cell
Tens of thousands of cells from one donor are technical PSEUDOREPLICATES, not independent observations. A per-cell test (Wilcoxon across all cells) treats them as n = cells and produces astronomically significant p-values from two mice - it is the single most common statistical sin in modern cytometry (Hurlbert 1984 Ecol Monogr 54:187; the cytometry mirror of the scRNA-seq pseudobulk lesson). The correct unit is the SAMPLE/subject: diffcyt aggregates cells to PER-SAMPLE-PER-CLUSTER counts (DA) and PER-SAMPLE-PER-CLUSTER arcsinh-MEDIANS (DS), then tests across samples with edgeR/limma/GLMM (Weber 2019 Commun Biol 2:183). Biological replication is mandatory (>= 2-3 per group); DA from a single sample per condition has no valid test. Paired with this: cluster proportions are COMPOSITIONAL (they sum to 1), so a real increase in one population mechanically forces apparent depletion in others - a source of false DA in "unchanged" clusters.
DA vs DS, and the type/state marker link
- DA (differential abundance): does a cluster's FREQUENCY differ? Clusters are defined by TYPE markers.
- DS (differential state): within a fixed-identity cluster, does a STATE marker's expression differ? State markers were withheld from clustering for exactly this test.
Method Taxonomy
| Method | Citation | Mechanism | When to use |
|---|---|---|---|
| diffcyt-DA-edgeR / voom | Weber 2019 Commun Biol 2:183 | edgeR/voom empirical-Bayes on per-sample counts; optional TMM | standard 2+ group with replicates (DEFAULT) |
| diffcyt-DA-GLMM / DS-LMM | Weber 2019 | random effects in the formula | paired/repeated-measures/nested (subject random effect) |
| cydar | Lun 2017 Nat Methods 14:707 | overlapping hyperspheres + edgeR + spatial FDR | continuum, avoid hard clusters |
| CITRUS | Bruggner 2014 PNAS 111:E2770 | hierarchical clustering + LASSO | predictive signature, LARGE n; correlated-not-causal; largely superseded |
| sccomp / scCODA / DCATS | Mangiola 2023 PNAS 120:e2203828120 / Buttner 2021 Nat Commun 12:6876 / Lin 2023 Genome Biol 24:151 | simplex-aware compositional models | strong compositional shift (one pop dominates); DCATS for assignment uncertainty |
Run diffcyt DA and DS
Goal: Test abundance and state on a CATALYST-clustered SCE.
Approach: Build design + contrast from ei(sce); the diffcyt() wrapper uses the stored clustering. State markers are tested in DS, type markers define DA clusters.
library(CATALYST); library(diffcyt)
sce <- readRDS('sce_clustered.rds')
design <- createDesignMatrix(ei(sce), cols_design = 'condition')
contrast <- createContrast(c(0, 1)) # Treatment vs Control
res_DA <- diffcyt(sce, clustering_to_use = 'meta20',
analysis_type = 'DA', method_DA = 'diffcyt-DA-edgeR',
design = design, contrast = contrast)
res_DS <- diffcyt(sce, clustering_to_use = 'meta20',
analysis_type = 'DS', method_DS = 'diffcyt-DS-limma',
design = design, contrast = contrast)
library(SummarizedExperiment)
rowData(res_DA$res) # cluster_id, logFC, p_val, p_adj (BH across clusters)
Paired / Repeated-Measures (mixed models)
Goal: Account for within-subject correlation (e.g. pre/post on the same donor).
Approach: Use a GLMM/LMM method with a random effect for subject via a formula.
formula <- createFormula(ei(sce), cols_fixed = 'condition', cols_random = 'patient_id')
res_DA <- diffcyt(sce, clustering_to_use = 'meta20',
analysis_type = 'DA', method_DA = 'diffcyt-DA-GLMM',
formula = formula, contrast = createContrast(c(0, 1)))
Compositional Re-Check
Goal: Confirm a headline single-population shift is not inducing artifactual reciprocal depletion.
Approach: Re-test with a simplex-aware model when one cluster changes a lot or total yield differs by group.
# If a dominant population expands, the apparent depletion of others may be a simplex artifact.
# Re-test with sccomp / scCODA (reference cell type) / DCATS (assignment uncertainty)
# before reporting reciprocal depletion as independent biology.
Per-Method Failure Modes
Per-cell pseudoreplication
Trigger: Wilcoxon/t-test across all cells. Mechanism: cells aren't independent. Symptom: p ~ 1e-40 from few subjects. Fix: aggregate to per-sample summaries (diffcyt).
Compositional false DA
Trigger: one population expands strongly. Mechanism: proportions sum to 1. Symptom: significant "depletion" of unrelated clusters. Fix: TMM only when total cell abundance is NOT itself the biological signal (else it removes real signal), or a compositional method (sccomp/scCODA/DCATS); report total-yield differences.
Batch cleaned instead of modeled
Trigger: normalizing batch out then testing naively. Mechanism: over-correction removes real signal. Symptom: attenuated effects. Fix: include batch in the design; if batch == condition, no rescue - design it out.
No replicates
Trigger: 1 sample per condition. Mechanism: no error term. Symptom: uninterpretable p. Fix: require >= 2-3 biological replicates per group.
Quantitative Thresholds
| Threshold | Source | Rationale |
|---|---|---|
| >= 2-3 biological replicates per group | Weber 2019 | minimum for a valid DA/DS error term |
| BH FDR across clusters (and clusters x markers for DS) | diffcyt | high-resolution grids have many tests |
| arcsinh median as DS statistic | Nowicka 2017 | robust per-cluster per-sample summary |
Common Errors
| Error / symptom | Cause | Solution |
|---|---|---|
testDA_edgeR(sce, ...) fails |
wrong signature | use the diffcyt() wrapper on the SCE, or calcCounts first |
| results empty | wrong clustering_to_use name |
match the stored clustering id (e.g. meta20) |
| no DS results | state markers not flagged | set marker_class='state' in the panel |
| paired design ignored | used fixed-effect method | use diffcyt-DA-GLMM with a random effect |
References
- Weber 2019 Commun Biol 2:183 — diffcyt (DA + DS).
- Bruggner 2014 PNAS 111(26):E2770-E2777 — CITRUS.
- Lun 2017 Nat Methods 14(7):707-709 — cydar hypersphere DA.
- Mangiola 2023 PNAS 120(33):e2203828120 — sccomp compositional analysis.
- Buttner 2021 Nat Commun 12:6876 — scCODA.
- Lin 2023 Genome Biol 24:151 — DCATS (assignment-uncertainty-aware).
- Nowicka 2017 F1000Research 6:748 — CyTOF workflow; arcsinh-median DS statistic.
- Hurlbert 1984 Ecol Monogr 54(2):187-211 — pseudoreplication.
Related Skills
- clustering-phenotyping - Cluster (type markers) before testing
- gating-analysis - Compare manually gated population frequencies
- differential-expression/de-results - Shared edgeR/limma output semantics (padj)
- differential-expression/edger-basics - The count-model engine diffcyt reuses
- experimental-design/multiple-testing - FDR across clusters and clusters x markers
- experimental-design/batch-design - Model batch in the design, don't clean it out