8  Differential analyses

8.1 When to use this module

Use this module to ask how cell-type proportions, gene expression, or chromatin accessibility differ with a condition or donor phenotype. It requires biological replication across donors or samples. Molecular measurements are combined into pseudobulks: counts summarized for each cell type within a donor or sample.

The module does not create biological replication. The donor structure, covariates, design formula, and contrasts must be defensible for the intended analysis before the workflow is run.

See the output gallery for representative diagnostics and the implementation graph for target structure.

8.2 Prerequisites

Before enabling the module, confirm that:

  • you have reviewed the main aggregation and its cell-type annotations;
  • WNN cell-type metadata and GEX and ATAC pseudobulk matrices are available;
  • the donor metadata contains one unique row per donor_id and every variable used in a model;
  • model variables are donor- or pseudobulk-sample-level variables, not duplicated cell-level measurements; and
  • the number and distribution of donors support the specified design and contrasts.

Use differential_analyses_extended_donor_id_metadata_tsv when the modelling table needs variables beyond the aggregation’s normal donor metadata. It must retain the same unique donor_id key.

8.3 Outputs

Choose the output that matches your question:

Question Output family
Do cell-type proportions differ? Differential cell-type composition (DCTC)
Which genes change expression? Differential gene expression (DGE)
Which peaks change accessibility? Differential chromatin accessibility (DCA)
Which motif families change accessibility? ATAC-derived differential TF activity (DTFA)
Which regulators show altered expression-based activity? CollecTRI-derived differential TF activity (DCTA)

The module also produces model diagnostics, comparisons across modalities, and gene-set tests for Hallmark and Reactome pathways. Activity scores are inferred from accessibility or expression; interpret them in the context of the measurement used.

See the method details for activity inference, motif-family definitions, and gene-set testing.

8.4 Configure the module

Add modules to the existing aggregation entry, keeping its input and marker settings:

cfg_aggregations.yaml
your_aggregation:
  modules: [differential_analyses]

Then create a matching row directly in module_differential_analyses/cfg.yaml.

module_differential_analyses/cfg.yaml
your_aggregation:
  differential_analyses_DCTC_plot_phenotype_vars: condition
  differential_analyses_DCTC_formula_chr: >-
    cbind(n_nuclei, n_other_nuclei) ~ 0 + condition
  differential_analyses_psbulk_DX_models:
    condition_model:
      cell_type_subset: NULL
      design_matrix_func_name: NULL
      formula: ~ 0 + cluster + condition
      random_effect: NULL
      contrast_specs_vec:
        treated_vs_control: conditiontreated

The module selection below requests both composition and pseudobulk outputs. Configure the DCTC phenotype/formula and at least one pseudobulk model before using that broad selector. Formula terms and contrast coefficients must match columns produced by the model matrix.

The model example assumes condition distinguishes treated and control donors. Check which group is the reference and what each model coefficient represents before using conditiontreated as a contrast. Replace the example formula and contrast to match your study.

8.5 Run and review

The existing checkpoint:differential_analyses tag selects module outputs. It does not perform QC approval; the QC checkpoint procedure is under development. Preview the selected targets first:

R
targets::tar_manifest(
  names = targets::tar_described_as(
    tidyselect::contains("checkpoint:differential_analyses")
  ) & tidyselect::ends_with(".your_aggregation"),
  callr_function = NULL
)[, c("name", "description")]

Then run the same selection:

R
targets::tar_make(
  names = targets::tar_described_as(
    tidyselect::contains("checkpoint:differential_analyses")
  ) & tidyselect::ends_with(".your_aggregation")
)

Review pseudobulk depths and retained donor counts before interpreting coefficients. Check model-matrix terms, P-value distributions, effect directions, and agreement or disagreement across DGE, DCA, DTFA, and DCTA. The CollecTRI-DTFA concordance target summarizes family coverage, rank correlation, directional agreement, and joint FDR support for every configured contrast. These are complementary regulatory readouts: agreement strengthens a shared interpretation, while disagreement can reflect post-transcriptional regulation, motif-family ambiguity, or different evidence carried by expression and accessibility. Treat the gallery as a visual reference, not as a statistical acceptance threshold.

Runtime depends on donors, cell types, models, contrasts, and gene-set analyses. Use Troubleshooting if a formula, contrast, or metadata join fails.

8.6 Parameter reference

The OLINK and bulk-RNA path fields are reserved optional integration inputs and are not consumed by the current public differential-analysis selection. Leave them NULL unless the corresponding integration is implemented in your downstream workflow.

Required: supply a value directly or through inheritance. Defaulted: a value is provided. Optional: may remain NULL. Open a parameter for its type, allowed values and example.

Show the public immune_human_2x example 
YAML
immune_human_2x:
  differential_analyses_DCTC_plot_phenotype_vars: condition
  differential_analyses_DCTC_formula_chr: cbind(n_nuclei, n_other_nuclei) ~ 0 + condition
  differential_analyses_DCTC_color_by_categorical_metadata_column: NULL
  differential_analyses_psbulk_DX_models:
    condition_demo:
      cell_type_subset: NULL
      design_matrix_func_name: NULL
      formula: ~ 0 + cluster + condition
      random_effect: NULL
      contrast_specs_vec:
        lymphoma_vs_healthy: conditionlymphoma