9  Genetic enrichment

9.1 When to use this module

Use this module to ask which cell types or nuclei have accessible regions overlapping genetic evidence for a human trait. It connects fine-mapped GWAS variants to ATAC peaks, calculates accessibility-based enrichment, and uses SCAVENGE to summarize trait relevance across related nuclei.

A credible set contains candidate causal variants at a GWAS locus, with probabilities from fine-mapping. Enrichment helps prioritize cellular contexts; it does not by itself identify a causal cell type, gene, or mechanism.

See the output gallery for representative results and the implementation graph for upstream ATAC and WNN dependencies.

9.2 Prerequisites

Before enabling the module, confirm that:

  • the aggregation is human and you have reviewed its main results and cell-type annotations;
  • WNN metadata and graph results, consensus peaks, ATAC counts, chromVAR objects, and GEX/ATAC embeddings are available;
  • each configured sourceId represents the intended trait and population;
  • the machine can download and retain the Open Targets study and credible-set Parquet datasets; and
  • you have chosen whether to interpret individual nuclei, graph-smoothed scores, or cell-type summaries; these answer related but different questions.

9.3 Outputs

Result What to inspect
Study and variant-to-peak tables Which studies, variants, and accessible regions contributed
Single-nucleus deviations Accessibility enrichment for each nucleus
SCAVENGE plots Trait-relevance scores propagated through the cell-neighbor graph
Cell-type heatmaps and attribution tables Enrichment by cell type and the loci or variants contributing to it

9.4 Configure the module

Add modules to the existing human aggregation entry, keeping its other settings:

cfg_aggregations.yaml
your_aggregation:
  modules: [genetic_enrichment]

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

module_genetic_enrichment/cfg.yaml
your_aggregation:
  genetic_enrichment_GWAS_studies:
    lymphocyte_count:
      Category: positive_control
      sourceId: GCST90002388
      finemappingMethod: auto

sourceId values beginning with GCST use the pinned Open Targets datasets. Every other value is a local Parquet filename, resolved from the project root and tracked as a file target. Local files must satisfy the schema enforced by validate_local_finemapped_GWAS_tibble(); their study ID, fine-mapping method, build, credible-set probability, and provenance are read from the file rather than repeated in YAML.

The root workflow currently pins Open Targets release 26.03. That release identifier is recorded in downstream metadata and determines the available studies, credible sets, and fine-mapping methods.

For finemappingMethod: auto, multiomeR selects the first available supported method in this order: SuSie, SuSiE-inf, then PICS. Specify a method explicitly when the method itself is part of the analysis contract; the workflow fails if that method is unavailable for the study.

9.5 Run and review

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

R
targets::tar_manifest(
  names = targets::tar_described_as(
    tidyselect::contains("checkpoint:genetic_enrichment")
  ) & 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:genetic_enrichment")
  ) & tidyselect::ends_with(".your_aggregation")
)

Before interpreting trait scores, verify the resolved source release and fine-mapping method, the number of credible-set loci and variants retained, and the overlap with consensus peaks. Then compare direct deviation summaries with SCAVENGE-propagated scores and use the heatmap glyphs to identify cluster-median enrichment supported by within-grouping BH-adjusted degree-matched permutation P-values.

Runtime and disk use grow with studies, cells, graph representations, permutations, and attributed loci. The gallery uses a larger aggregation with six GEM wells and is not produced by the minimal quickstart.

9.6 Parameter reference

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:
  genetic_enrichment_GWAS_studies:
    LymphocyteCount_Vuckovic2020:
      Category: positive_control
      sourceId: GCST90002388
      finemappingMethod: auto
    MonocyteCount_Vuckovic2020:
      Category: positive_control
      sourceId: GCST90002393
      finemappingMethod: auto
    BCellNeoplasm_Guler2025:
      Category: B_cell_neoplasm
      sourceId: GCST90624736
      finemappingMethod: auto
    BMI_Verma2024:
      Category: negative_control
      sourceId: GCST90475159
      finemappingMethod: auto
    EducationalAttainment_Okbay2022:
      Category: brain_cognition
      sourceId: GCST90105038
      finemappingMethod: auto