Why Science? | diffcyt, High-Resolution Clustering and Differential Discovery

Section 1 of 36

1. Begin with two different questions

A condition can change the number of cells in a population, the signalling state of those cells, or both. Combining those questions produces ambiguous results.

diffcyt usually clusters with FlowSOM at high resolution, then tests cluster-level summaries so narrow populations are not erased by broad manual categories.

Archive sample manifests, preprocessing, feature roles, model formulae, random seeds, software versions and exclusions so another analyst can reconstruct the decision path.

Contents · Next section

Section 2 of 36

2. Define differential abundance

DA tests whether the representation of a cluster differs across sample groups after normalisation and modelling. It is a statement about observed relative counts under the design.

Differential abundance concerns cell counts or proportions across clusters; differential state concerns functional or signalling-marker values within clusters.

Keep the biological sample as the unit of replication. Many cells improve resolution, but they do not turn one donor, animal or culture into many independent experiments.

Contents · Previous section · Next section

Section 3 of 36

3. Define differential state

DS tests whether a functional marker changes within a cluster while the cluster identity remains defined by other markers. It is closer to a within-population response question.

The package offers edgeR- or limma-based fixed-effect workflows and mixed-model alternatives, making the design matrix and contrast central scientific objects.

Use negative controls, label permutations or design-matched null analyses where valid. A trustworthy signal should exceed artefacts that the same workflow can manufacture.

Contents · Previous section · Next section

Section 4 of 36

4. Choose biological replicates

Donors, animals or independent cultures support inference. Technical replicates and individual cells describe measurement precision but do not replace independent biological units.

High-resolution clusters are computational bins, not automatically stable biological cell types. Interpret them through markers, sample support and sensitivity.

Report effect direction, uncertainty, sample support and sensitivity—not only a colourful embedding, selected feature or adjusted value.

Contents · Previous section · Next section

Section 5 of 36

5. Build a design matrix

Encode condition, batch, pairing and justified covariates explicitly. A contrast should correspond to the exact scientific comparison written in the protocol.

Empirical-Bayes moderation borrows information across clusters or marker-cluster combinations to stabilise variance estimates; it does not create missing biological replication.

Create an evidence card naming the contrast, measured modality, statistical unit, model, result, validation status, unresolved alternatives and narrowest defensible claim.

Contents · Previous section · Next section

Section 6 of 36

6. Assign marker roles

Separate cell-type markers used for clustering from state markers used for DS testing. A marker can have different roles only when the rationale is transparent.

Cytometry data can contain batch, transformation and panel effects. These should be controlled by experimental design and declared preprocessing before statistical testing.

Write association, stratification, differential abundance or differential state when that is what was tested. Reserve cause, diagnosis and benefit for evidence that directly supports them.

Contents · Previous section · Next section

Section 7 of 36

7. Read the 2019 evidence in scope

Weber and colleagues presented diffcyt as a differential-discovery framework for high-dimensional cytometry based on high-resolution clustering and empirical-Bayes moderated tests adapted from transcriptomics.

diffcyt usually clusters with FlowSOM at high resolution, then tests cluster-level summaries so narrow populations are not erased by broad manual categories.

Archive sample manifests, preprocessing, feature roles, model formulae, random seeds, software versions and exclusions so another analyst can reconstruct the decision path.

Contents · Previous section · Next section

Section 8 of 36

8. Transform consistently

Apply a declared arcsinh cofactor or other transformation across samples. Small preprocessing differences can alter distance, clustering and state-marker distributions.

Differential abundance concerns cell counts or proportions across clusters; differential state concerns functional or signalling-marker values within clusters.

Keep the biological sample as the unit of replication. Many cells improve resolution, but they do not turn one donor, animal or culture into many independent experiments.

Contents · Previous section · Next section

Section 9 of 36

9. Normalise when appropriate

Mass-cytometry reference samples or bead-based procedures can reduce technical drift. Record which channels and files were adjusted and retain pre-normalisation checks.

The package offers edgeR- or limma-based fixed-effect workflows and mixed-model alternatives, making the design matrix and contrast central scientific objects.

Use negative controls, label permutations or design-matched null analyses where valid. A trustworthy signal should exceed artefacts that the same workflow can manufacture.

Contents · Previous section · Next section

Section 10 of 36

10. Remove poor events

Debris, doublets, dead cells and acquisition anomalies can form artificial clusters. Quality criteria should be outcome-blind and applied consistently.

High-resolution clusters are computational bins, not automatically stable biological cell types. Interpret them through markers, sample support and sensitivity.

Report effect direction, uncertainty, sample support and sensitivity—not only a colourful embedding, selected feature or adjusted value.

Contents · Previous section · Next section

Section 11 of 36

11. Run high-resolution clustering

FlowSOM can generate many small clusters so rare or transitional populations remain testable. Resolution is a sensitivity parameter, not a biological truth.

Empirical-Bayes moderation borrows information across clusters or marker-cluster combinations to stabilise variance estimates; it does not create missing biological replication.

Create an evidence card naming the contrast, measured modality, statistical unit, model, result, validation status, unresolved alternatives and narrowest defensible claim.

Contents · Previous section · Next section

Section 12 of 36

12. Inspect cluster markers

Review heat maps and per-sample counts before testing. Merge or label clusters only after seeing whether their marker profiles and distributions are coherent.

Cytometry data can contain batch, transformation and panel effects. These should be controlled by experimental design and declared preprocessing before statistical testing.

Write association, stratification, differential abundance or differential state when that is what was tested. Reserve cause, diagnosis and benefit for evidence that directly supports them.

Contents · Previous section · Next section

Section 13 of 36

13. Create the DA matrix

Count cells per sample and cluster. Store library sizes and sample totals so normalisation and offsets remain auditable.

diffcyt usually clusters with FlowSOM at high resolution, then tests cluster-level summaries so narrow populations are not erased by broad manual categories.

Archive sample manifests, preprocessing, feature roles, model formulae, random seeds, software versions and exclusions so another analyst can reconstruct the decision path.

Contents · Previous section · Next section

Section 14 of 36

14. Create the DS matrix

Summarise state-marker values for every sample-cluster combination. Missing combinations and sparse clusters require explicit handling.

Differential abundance concerns cell counts or proportions across clusters; differential state concerns functional or signalling-marker values within clusters.

Keep the biological sample as the unit of replication. Many cells improve resolution, but they do not turn one donor, animal or culture into many independent experiments.

Contents · Previous section · Next section

Section 15 of 36

15. Practise with a fictional diffcyt table

This classroom table is invented and is not a result from the diffcyt paper.

The package offers edgeR- or limma-based fixed-effect workflows and mixed-model alternatives, making the design matrix and contrast central scientific objects.

Use negative controls, label permutations or design-matched null analyses where valid. A trustworthy signal should exceed artefacts that the same workflow can manufacture.

Contents · Previous section · Next section

Section 16 of 36

16. Choose a DA engine

The diffcyt-DA-edgeR workflow models counts with empirical-Bayes methods from edgeR. Mixed-model variants are useful for certain paired or repeated designs but require enough samples to estimate random effects.

High-resolution clusters are computational bins, not automatically stable biological cell types. Interpret them through markers, sample support and sensitivity.

Report effect direction, uncertainty, sample support and sensitivity—not only a colourful embedding, selected feature or adjusted value.

Contents · Previous section · Next section

Section 17 of 36

17. Choose a DS engine

The diffcyt-DS-limma workflow models state summaries with limma-style moderation. State tests should use markers and clusters with adequate observations.

Empirical-Bayes moderation borrows information across clusters or marker-cluster combinations to stabilise variance estimates; it does not create missing biological replication.

Create an evidence card naming the contrast, measured modality, statistical unit, model, result, validation status, unresolved alternatives and narrowest defensible claim.

Contents · Previous section · Next section

Section 18 of 36

18. Specify contrasts before viewing results

Write the coefficient or contrast for the biological question before ranking clusters. Post-hoc contrasts selected from the most attractive heat map undermine error control.

Cytometry data can contain batch, transformation and panel effects. These should be controlled by experimental design and declared preprocessing before statistical testing.

Write association, stratification, differential abundance or differential state when that is what was tested. Reserve cause, diagnosis and benefit for evidence that directly supports them.

Contents · Previous section · Next section

Section 19 of 36

19. Adjust for multiplicity

Many clusters and marker-cluster combinations are tested. Report the correction family and distinguish adjusted evidence from exploratory patterns.

diffcyt usually clusters with FlowSOM at high resolution, then tests cluster-level summaries so narrow populations are not erased by broad manual categories.

Archive sample manifests, preprocessing, feature roles, model formulae, random seeds, software versions and exclusions so another analyst can reconstruct the decision path.

Contents · Previous section · Next section

Section 20 of 36

20. Read effect size with uncertainty

A small adjusted value does not guarantee a large or useful biological shift. Pair log effects with confidence intervals, raw distributions and sample counts.

Differential abundance concerns cell counts or proportions across clusters; differential state concerns functional or signalling-marker values within clusters.

Keep the biological sample as the unit of replication. Many cells improve resolution, but they do not turn one donor, animal or culture into many independent experiments.

Contents · Previous section · Next section

Section 21 of 36

21. Inspect each sample

A pooled cluster can appear convincing while one donor supplies most positive cells. Per-sample plots reveal dominance, zeros and unexpected batch structure.

The package offers edgeR- or limma-based fixed-effect workflows and mixed-model alternatives, making the design matrix and contrast central scientific objects.

Use negative controls, label permutations or design-matched null analyses where valid. A trustworthy signal should exceed artefacts that the same workflow can manufacture.

Contents · Previous section · Next section

Section 22 of 36

22. Run cluster-resolution sensitivity

Repeat nearby FlowSOM metacluster numbers or seeds. A robust biological region should recur as a marker-coherent set even if numeric labels change.

High-resolution clusters are computational bins, not automatically stable biological cell types. Interpret them through markers, sample support and sensitivity.

Report effect direction, uncertainty, sample support and sensitivity—not only a colourful embedding, selected feature or adjusted value.

Contents · Previous section · Next section

Section 23 of 36

23. Test marker-role sensitivity

If one marker helps define clusters and is also interpreted as a state change, rerun a defensible alternative to see whether circularity drives the result.

Empirical-Bayes moderation borrows information across clusters or marker-cluster combinations to stabilise variance estimates; it does not create missing biological replication.

Create an evidence card naming the contrast, measured modality, statistical unit, model, result, validation status, unresolved alternatives and narrowest defensible claim.

Contents · Previous section · Next section

Section 24 of 36

24. Compare with Citrus

Citrus selects a supervised signature for an endpoint. diffcyt performs explicit DA or DS tests over high-resolution clusters and returns effect-based inferential results.

Cytometry data can contain batch, transformation and panel effects. These should be controlled by experimental design and declared preprocessing before statistical testing.

Write association, stratification, differential abundance or differential state when that is what was tested. Reserve cause, diagnosis and benefit for evidence that directly supports them.

Contents · Previous section · Next section

Section 25 of 36

25. Compare with cydar

cydar searches overlapping hyperspheres and uses spatial FDR. diffcyt uses non-overlapping cluster summaries, producing a different balance between interpretability and local resolution.

diffcyt usually clusters with FlowSOM at high resolution, then tests cluster-level summaries so narrow populations are not erased by broad manual categories.

Archive sample manifests, preprocessing, feature roles, model formulae, random seeds, software versions and exclusions so another analyst can reconstruct the decision path.

Contents · Previous section · Next section

Section 26 of 36

26. Build a differential evidence card

Record DA or DS, cluster markers, formula, contrast, effect, adjusted evidence, sample support, resolution stability and validation status.

Differential abundance concerns cell counts or proportions across clusters; differential state concerns functional or signalling-marker values within clusters.

Keep the biological sample as the unit of replication. Many cells improve resolution, but they do not turn one donor, animal or culture into many independent experiments.

Contents · Previous section · Next section

Section 27 of 36

27. Design the next experiment

Repeat the key population with balanced batches and a focused panel, then add a functional perturbation or time course aligned with the hypothesised state change.

The package offers edgeR- or limma-based fixed-effect workflows and mixed-model alternatives, making the design matrix and contrast central scientific objects.

Use negative controls, label permutations or design-matched null analyses where valid. A trustworthy signal should exceed artefacts that the same workflow can manufacture.

Contents · Previous section · Next section

Section 28 of 36

28. Validate the population and the state separately

Confirm abundance with an independent gating or counting strategy; confirm state markers with calibrated assays. One validation cannot silently stand in for both questions.

High-resolution clusters are computational bins, not automatically stable biological cell types. Interpret them through markers, sample support and sensitivity.

Report effect direction, uncertainty, sample support and sensitivity—not only a colourful embedding, selected feature or adjusted value.

Contents · Previous section · Next section

Section 29 of 36

29. Connect diffcyt to school science

The DA-versus-DS distinction resembles asking whether a class has more students with a trait or whether the same students changed their measured response.

Empirical-Bayes moderation borrows information across clusters or marker-cluster combinations to stabilise variance estimates; it does not create missing biological replication.

Create an evidence card naming the contrast, measured modality, statistical unit, model, result, validation status, unresolved alternatives and narrowest defensible claim.

Contents · Previous section · Next section

Section 30 of 36

30. Try a count-and-state activity

Give groups jars of coloured beads with brightness scores. Compare both colour proportions and brightness within each colour, then discuss why the conclusions differ.

Cytometry data can contain batch, transformation and panel effects. These should be controlled by experimental design and declared preprocessing before statistical testing.

Write association, stratification, differential abundance or differential state when that is what was tested. Reserve cause, diagnosis and benefit for evidence that directly supports them.

Contents · Previous section · Next section

Section 31 of 36

31. Connect to mathematics

Counts, offsets, linear models, contrasts, shrinkage and false-discovery rates show how many comparisons can be tested without losing sight of effect size.

diffcyt usually clusters with FlowSOM at high resolution, then tests cluster-level summaries so narrow populations are not erased by broad manual categories.

Archive sample manifests, preprocessing, feature roles, model formulae, random seeds, software versions and exclusions so another analyst can reconstruct the decision path.

Contents · Previous section · Next section

Section 32 of 36

32. Connect to computing and AI literacy

High-resolution automation can reveal narrow signals, but cluster labels and ranked tables remain model outputs that need human biological interpretation.

Differential abundance concerns cell counts or proportions across clusters; differential state concerns functional or signalling-marker values within clusters.

Keep the biological sample as the unit of replication. Many cells improve resolution, but they do not turn one donor, animal or culture into many independent experiments.

Contents · Previous section · Next section

Section 33 of 36

33. Connect to school and career pathways

Learners who like instruments and models can explore immunology, biotechnology, statistics, data science, laboratory medicine or computational biology.

The package offers edgeR- or limma-based fixed-effect workflows and mixed-model alternatives, making the design matrix and contrast central scientific objects.

Use negative controls, label permutations or design-matched null analyses where valid. A trustworthy signal should exceed artefacts that the same workflow can manufacture.

Contents · Previous section · Next section

Section 34 of 36

34. Create a family evidence habit

When a headline says an immune population changed, ask whether the study means abundance, signalling state or both, and how many independent samples supported it.

High-resolution clusters are computational bins, not automatically stable biological cell types. Interpret them through markers, sample support and sensitivity.

Report effect direction, uncertainty, sample support and sensitivity—not only a colourful embedding, selected feature or adjusted value.

Contents · Previous section · Next section

Section 35 of 36

35. Use precise diffcyt language

Say differential abundance of a cluster or differential state of a marker within a cluster. Avoid cell type, mechanism or diagnostic marker without separate validation.

Empirical-Bayes moderation borrows information across clusters or marker-cluster combinations to stabilise variance estimates; it does not create missing biological replication.

Create an evidence card naming the contrast, measured modality, statistical unit, model, result, validation status, unresolved alternatives and narrowest defensible claim.

Contents · Previous section · Next section

Section 36 of 36

36. Finish with a files-to-inference bundle

Deliver raw-file manifests, transformations, marker roles, clustering seeds, design matrices, contrasts, per-sample plots, multiplicity control, sensitivity analyses and validation.

Cytometry data can contain batch, transformation and panel effects. These should be controlled by experimental design and declared preprocessing before statistical testing.

Write association, stratification, differential abundance or differential state when that is what was tested. Reserve cause, diagnosis and benefit for evidence that directly supports them.

## Source date and scope note Primary papers and official software documentation were checked for this article on 10 October 2026. Software interfaces and recommendations can change, so readers should consult the linked current documentation before reproducing an analysis.

## Final reader checklist Before accepting a claim, confirm the biological sample count, condition definition, measured modality, preprocessing, statistical unit, model formula, uncertainty, software version, negative controls, sensitivity checks, independent validation and the exact boundary between association and causation.

Contents · Previous section · Continue to the Science Learning Hub