assign_consensus_enhancers

alphagenome.interpretation.enhancer_scoring.assign_consensus_enhancers(enhancers_df, *, min_reciprocal_overlap=0.5)

Assigns cross-biosample consensus peak bounds via reciprocal-overlap NMS.

Calling active enhancers per biosample on a sliding tile grid can place summits of the same regulatory element on slightly shifted overlapping tiles; clustering them into shared consensus coordinates lets callers compare enhancer scores or count active biosamples across conditions.

Within each (gene_id, chromosome) group, distinct (start, end) enhancer intervals are ranked by their row count in enhancers_df (breaking ties by ascending (start, end)) and clustered greedily: each candidate interval is assigned to the highest-overlapping already-accepted representative peak whose mutual overlap overlap / max(len_a, len_b) is at least min_reciprocal_overlap, or starts a new consensus peak otherwise.

Parameters:

• enhancers_df (DataFrame) – DataFrame of called enhancer-gene links (such as the output of get_active_enhancers) containing at least gene_id, chromosome, start, and end columns. Any existing consensus_peak_start and consensus_peak_end columns are replaced.

• min_reciprocal_overlap (float (default: 0.5)) – Minimum mutual overlap fraction overlap / max(len_a, len_b) in (0, 1] required to merge an interval into an existing consensus representative.

Return type:

DataFrame

Returns:

Copy of enhancers_df (preserving its index and row order) with integer consensus_peak_start and consensus_peak_end columns appended.

Raises:

ValueError – If min_reciprocal_overlap is not in (0, 1], if enhancers_df is missing any of gene_id, chromosome, start, or end, if those columns contain null values, or if any interval does not satisfy start < end.