Enhancer links

Peak-to-gene links from RNA, ATAC and gene coordinates.

rustscenic.enhancer

Enhancer-to-gene linking for chromatin-aware regulatory networks.

pySCENIC scores regulons as "TF → its top-N co-expressed target genes". SCENIC+ adds chromatin context:

TF → enhancer (motif enrichment, from cistarget) ↓ enhancer → target gene (peak accessibility ↔ gene expression correlated across matched cells)

The enhancer-to-gene edge is what this module produces. Combined with the motif-to-enhancer and TF-to-target edges rustscenic already computes, it is the raw material for eRegulons.

This module requires matched cells: every cell in rna_adata.obs_names must also be in atac_adata.obs_names. Multiome data (10x Multiome or nf-core/multiome) is the natural input. For non-matched samples, CCA or Harmony-style integration needs to happen upstream.

Complexity: O(n_peaks × max_genes_in_window × n_cells) where max_genes_in_window is typically 20–50. On 100k peaks × 30 candidate genes × 50k cells that is about 150 GFLOPs. The Pearson path keeps the hot loop in Rust and emits only surviving peak-gene links back to pandas.

link_peaks_to_genes(
    rna_adata,
    atac_adata,
    gene_coords: DataFrame,
    peak_coords: DataFrame | None = None,
    *,
    max_distance: int = 500000,
    min_abs_corr: float = 0.1,
    method: str = "pearson",
) -> pd.DataFrame

Link ATAC peaks to nearby gene expression.

For each peak, finds candidate target genes whose TSS is within max_distance bp of the peak center, computes the correlation of peak accessibility vs gene expression across the matched cells, and returns links whose absolute correlation exceeds min_abs_corr.

Parameters:

Name Type Description Default
rna_adata

AnnData with log-normalised expression. Cells in obs_names must match atac_adata.obs_names.

 required
atac_adata

AnnData of cells × peaks accessibility (typically from rustscenic.preproc.fragments_to_matrix). Peak coordinates may come from atac_adata.var (columns chrom, start, end) or from the explicit peak_coords argument.

 required
gene_coords DataFrame

DataFrame with columns ["gene", "chrom", "tss"] listing each gene's TSS position. Build from a GTF, a GENCODE BED, or the rustscenic.data helpers once they ship.

 required
peak_coords DataFrame | None

Optional override; DataFrame indexed by peak id with chrom, start, end. Required if atac_adata.var doesn't carry peak coordinates.

 None
max_distance int

Maximum bp between a peak's centre and a gene's TSS for the pair to be considered (default 500 kb, matching pycisTopic).

 500000
min_abs_corr float

Minimum absolute correlation to emit a link (default 0.1). Increase for stricter filtering.

 0.1
method str

Must be "pearson". This is the Rust-backed correlation path.

 'pearson'

Returns:

Type Description
DataFrame

One row per surviving peak-gene link with columns: ['peak_id', 'peak_chrom', 'peak_start', 'peak_end', 'gene', 'gene_tss', 'distance', 'correlation']. Sorted by descending |correlation|.