Peak–gene correlation

When to use

Use this module to nominate candidate regulatory links between accessible regions and nearby genes within each WNN cell type. It pairs consensus peaks with nearby gene transcription start sites and tests whether accessibility and expression vary together across donor–state pseudobulks: nuclei of one cell type summed by donor and ATAC-defined state, with each nucleus in at most one pseudobulk.

A hierarchical model adjusts for donor, sequencing depth and the cell type’s main chromatin states and lets the peak–gene slope vary between donors. Positive slopes that significantly exceed those of distant peaks of the same gene nominate candidate links, and SuSiE prioritizes peaks for each linked gene. Links are hypotheses: they do not establish causal regulation, and the distant-peak background cannot separate a specific enhancer from covariation within a local chromatin domain. Method details

Prerequisites

Before enabling the module, confirm that:

• you have reviewed the aggregation through checkpoint 8 and accept its final WNN cell set and cell-type annotations; and
• each cell type you want to study has at least eight donors with at least 40 of its nuclei.

Cell types and donors with too few nuclei are skipped. A cell type with fewer such donors yields diagnostics but no tests, and the strict support filter requires more shared donors than the other presets.

Outputs

Question	Output
How many candidate pairs does each support filter retain?	Filter-retention plot
Which cell types or chromosome branches were skipped, and why?	Diagnostics plot and table
Which peaks are associated with a gene’s expression?	Hierarchical results table and top-link figures
How do adjusted correlations and links vary by cell type and distance?	Summary plots and link table
Which peaks best explain a linked gene?	SuSiE prioritization table

Configure

Add peak_gene_correlation to the aggregation’s modules list, keeping its other settings:

cfg_aggregations.yaml

my_aggregation:
  modules: [peak_gene_correlation]

Then add an entry for my_aggregation to cfg_module_peak_gene_correlation.yaml in the selected configuration directory:

cfg_module_peak_gene_correlation.yaml

my_aggregation:
  peak_gene_correlation_top_links_per_cell_group: 3
  peak_gene_correlation_filter: moderate

peak_gene_correlation_top_links_per_cell_group sets the number of top-link figures per cell type; it does not change which pairs are tested. peak_gene_correlation_filter selects the lenient, moderate (default) or strict measurement-support filter, which removes pairs without enough expression, accessibility and shared donor support before testing. An empty entry, my_aggregation: {}, keeps both defaults.

Run

Preview the targets tagged for this module:

R

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

Then run the same selection:

R

targets::tar_make(
  names = targets::tar_described_as(
    tidyselect::contains("checkpoint:peak_gene_correlation")
  ) & tidyselect::ends_with(".my_aggregation")
)

Review

Review the plots (examples); each plot’s subtitle and caption say what to look for.

<store>/plots/my_aggregation/peak_gene_correlation/
├── filter_retention_plot.png
├── diagnostics_plot.png
├── top_link_aggregate_scatter_plots/
├── support_counts_plot.png
├── correlation_histogram_plot.png
├── distance_correlation_plot.png
└── significant_pairs_vs_technical_features_plot.png

Start with filter_retention_plot.png, which compares the three support filters by cell type and marks the active one. Top-link figures rank positive, estimable slopes outside self-promoter peaks by hierarchical p-value, without a significance cutoff, so appearing in a figure is not evidence of significance. diagnostics_plot.png shows skipped branches, and the other plots summarize adjusted correlations and hierarchical links.

Read the tables in R, for example the hierarchical results with BH FDR within each cell type:

R

targets::tar_read(
  peak_gene_correlation_hierarchical_results_tibble.WNN.peak_gene_correlation.my_aggregation
)

The candidate links and SuSiE prioritization are in peak_gene_correlation_links_tibble.WNN and peak_gene_correlation_finemapped_links_tibble.WNN, with the same .peak_gene_correlation.my_aggregation suffix.

Parameter reference

Open the searchable parameter browser. Peak–gene correlation methods describes the models and their key fixed values, including the support-filter presets, links to the source files and shows the target structure.