/peak-annotation

name: peak-annotation
description: "Guide for annotating ENCODE peaks with genomic features using ChIPseeker and GREAT. Use when users need to assign peaks to genes, determine genomic feature distribution (promoter, intron, intergenic), or perform gene ontology enrichment of peak-associated genes. Trigger on: peak annotation, ChIPseeker, GREAT, peak to gene, genomic feature, promoter enrichment, gene ontology, peak distribution, TSS distance, nearest gene."

Peak Annotation of ENCODE Data

When to Use

• User wants to annotate genomic peaks with nearby genes, regulatory features, or functional categories
• User asks about "peak annotation", "ChIPseeker", "gene assignment", or "peak-to-gene mapping"
• User needs to classify peaks as promoter, enhancer, intronic, intergenic, etc.
• User wants to run GO/pathway enrichment on genes near their peaks
• Example queries: "annotate my H3K27ac peaks with nearby genes", "what genes are near these ATAC-seq peaks?", "run pathway analysis on peak-associated genes"

Help the user annotate ENCODE peak calls with genomic features and functional enrichment. Peak annotation bridges the gap between regulatory elements (peaks) and biological function (genes, pathways). This skill covers two complementary approaches: ChIPseeker for genomic feature annotation and visualization, and GREAT for functional enrichment analysis of non-coding regions.

Literature Foundation

| Reference | Journal | Key Contribution | DOI | Citations | |-----------|---------|-----------------|-----|-----------| | Yu et al. (2015) | Bioinformatics | ChIPseeker: R/Bioconductor package for ChIP peak annotation, comparison, and visualization | [10.1093/bioinformatics/btv145](https://doi.org/10.1093/bioinformatics/btv145) | ~3,200 | | McLean et al. (2010) | Nature Biotechnology | GREAT: Genomic Regions Enrichment of Annotations Tool; assigns biological meaning to cis-regulatory regions using basal+extension gene association | [10.1038/nbt.1630](https://doi.org/10.1038/nbt.1630) | ~2,800 | | Zhu et al. (2010) | BMC Bioinformatics | ChIPpeakAnno: Bioconductor package for ChIP-seq/ChIP-chip annotation; pioneered peak-gene association | [10.1186/1471-2105-11-237](https://doi.org/10.1186/1471-2105-11-237) | ~1,200 | | Tanigawa et al. (2022) | PLOS Computational Biology | rGREAT: R/Bioconductor interface to GREAT; enables programmatic enrichment analysis | [10.1371/journal.pcbi.1010378](https://doi.org/10.1371/journal.pcbi.1010378) | ~80 | | Amemiya et al. (2019) | Scientific Reports | ENCODE Blacklist: artifact regions to exclude before annotation to avoid spurious gene associations | [10.1038/s41598-019-45839-z](https://doi.org/10.1038/s41598-019-45839-z) | ~1,372 |

Prerequisites: Obtaining ENCODE Peaks

Search for and download peak files before annotation:

encode_search_experiments(
    assay_title="Histone ChIP-seq",
    target="H3K27ac",
    organ="pancreas",
    biosample_type="tissue"
)

encode_list_files(
    experiment_accession="ENCSR...",
    file_format="bed",
    output_type="IDR thresholded peaks",
    assembly="GRCh38",
    preferred_default=True
)

encode_download_files(
    file_accessions=["ENCFF..."],
    download_dir="/data/peak_annotation/"
)

**Pre-annotation filtering**: Always remove blacklisted regions before annotation:

bedtools intersect -a peaks.narrowPeak -b hg38-blacklist.v2.bed -v > peaks_clean.narrowPeak

Part 1: ChIPseeker Annotation

ChIPseeker (Yu et al. 2015) annotates peaks with genomic features (promoter, UTR, exon, intron, intergenic) and provides publication-ready visualizations of the annotation distribution.

1a. Basic Annotation Workflow

library(ChIPseeker)
library(TxDb.Hsapiens.UCSC.hg38.knownGene)
library(org.Hs.eg.db)
library(clusterProfiler)

# Load peak file
peaks <- readPeakFile("H3K27ac_peaks_clean.narrowPeak")

# Set transcript database (must match genome assembly)
txdb <- TxDb.Hsapiens.UCSC.hg38.knownGene

# Annotate peaks with genomic features
peakAnno <- annotatePeak(
    peaks,
    TxDb = txdb,
    annoDb = "org.Hs.eg.db",
    level = "gene",
    tssRegion = c(-3000, 3000)
)

# View annotation summary
peakAnno

1b. Understanding Annotation Categories

ChIPseeker classifies each peak into one genomic feature based on priority:

| Priority | Feature | Definition | |----------|---------|------------| | 1 | Promoter | Within TSS region (default: TSS +/- 3kb) | | 2 | 5' UTR | Overlapping 5' untranslated region | | 3 | 3' UTR | Overlapping 3' untranslated region | | 4 | Exon | Overlapping exonic sequence | | 5 | Intron | Within intronic sequence | | 6 | Downstream | Within 3kb downstream of gene end | | 7 | Distal Intergenic | Everything else (>3kb from any gene) |

Each peak receives exactly one annotation based on the highest-priority feature it overlaps.

**Promoter sub-categories**: ChIPseeker can further subdivide promoter peaks:

peakAnno <- annotatePeak(
    peaks,
    TxDb = txdb,
    annoDb = "org.Hs.eg.db",
    level = "gene",
    tssRegion = c(-3000, 3000),
    # Subdivide promoter into bins
    genomicAnnotationPriority = c(
        "Promoter", "5UTR", "3UTR", "Exon", "Intron", "Downstream", "Intergenic"
    )
)

1c. Visualization Functions

ChIPseeker provides several publication-ready visualization functions:

**Genomic Feature Distribution Bar Plot**:

plotAnnoBar(peakAnno) +
    theme_minimal(base_size = 14) +
    ggtitle("H3K27ac Genomic Feature Distribution")
ggsave("annotation_barplot.pdf", width = 10, height = 5)

**Genomic Feature Distribution Pie Chart**:

plotAnnoPie(peakAnno)

**Distance to TSS Distribution**:

plotDistToTSS(
    peakAnno,
    title = "H3K27ac Distance to Nearest TSS"
) + theme_minimal(base_size = 14)
ggsave("tss_distance.pdf", width = 8, height = 5)

**Peak Coverage Across Chromosomes**:

covplot(peaks, weightCol = "V5") +
    ggtitle("H3K27ac Peak Coverage")
ggsave("chromosome_coverage.pdf", width = 12,