get_active_enhancers

get_active_enhancers#

alphagenome.interpretation.enhancer_scoring.get_active_enhancers(gradients_outputs, *, gtf, accessibility_outputs=None, accessibility_output_type=SC_ATAC, tile_size=500, step_size=250, window_size=2400, sigma=300.0, gradient_score_threshold='auto', atac_score_threshold=1.25, prefer_observed_accessibility=True)[source]#

Calls and merges active enhancer-to-gene links from input gradients.

For each (biosample_name, gene_id) locus, tile_interval windows are scored with score_enhancers and filtered by gradient_score_threshold and optional 1-bp chromatin accessibility (atac_score, the per-tile maximum accessibility averaged across channels). Passing tiles are reduced per gene to local gradient_score summits within overlapping clusters, then overlapping summits across genes in the same (biosample_name, chromosome) are merged to their [min(start), max(end)] span while retaining each gene’s top summit scores.

Parameters:

  • gradients_outputs (Sequence[InputGradientsOutput]) – InputGradientsOutput sequence with unique (biosample_name, gene_id) pairs.

  • gtf (DataFrame) – GENCODE GTF DataFrame used to resolve MANE_Select transcript TSSs.

  • accessibility_outputs (Sequence[Output] | None (default: None)) – dna_output.Output sequence aligned with gradients_outputs, or None when atac_score_threshold is None.

  • accessibility_output_type (Literal[SC_ATAC, ATAC] (default: SC_ATAC)) – Accessibility track to use (SC_ATAC or ATAC).

  • tile_size (int (default: 500)) – Candidate tile width in bp.

  • step_size (int (default: 250)) – Step between adjacent tiles in bp.

  • window_size (int (default: 2400)) – Gaussian smoothing window width around each tile midpoint (bp).

  • sigma (float (default: 300.0)) – Gaussian kernel standard deviation (bp).

  • gradient_score_threshold (Union[float, Literal['auto']] (default: 'auto')) – Minimum gradient_score, or 'auto' to use DEFAULT_GRADIENT_SCORE_THRESHOLDS (0.0012 for SC_GENE_EXPRESSION, 0.0017 for RNA_SEQ).

  • atac_score_threshold (float | None (default: 1.25)) – Minimum atac_score, or None to skip accessibility filtering.

  • prefer_observed_accessibility (bool (default: True)) – If True, averages atac_score over observed channels when present, falling back to all channels otherwise.

Return type:

DataFrame

Returns:

DataFrame with one row per (biosample_name, merged peak, gene_id) link and columns chromosome, start, end, name, biosample_name, gene_id, gradient_score, tss, and tss_distance (|0.5 * (start + end) - tss|), plus gene_name when present on any target gene and atac_score when accessibility_outputs is provided.

Raises:

ValueError – If tiling or window parameters are invalid, if 'auto' lacks a threshold for output_type, if accessibility_outputs is missing, misaligned, not 1-bp SC_ATAC/ATAC, narrower than a gradient interval, or from a different biosample_name, if (biosample_name, gene_id) pairs repeat, or if a target gene has no MANE_Select TSS on its chromosome in gtf.