Skip to main content
v2026.11,986 entries · CC-BY 4.0

ChIPseeker: Install, Annotate Peaks and Read Output

Use ChIPseeker to annotate an official peak sample in R, interpret genomic features, and preserve reference and parameter choices.

Written and maintained by CASRAI Editorial Board

Published

On this page

ChIPseeker is an R/Bioconductor package that annotates ChIP-seq peaks, associates them with nearby genes, and visualizes their genomic distribution. A useful analysis keeps three things separate: the input peak intervals, the annotation settings, and the biological interpretation. This guide follows an official sample workflow and shows how to preserve those distinctions when exporting results.

What it is used for in research

The Bioconductor ChIPseeker package page describes annotation, peak-set comparison, and visualization. The starting point is a set of genomic peaks. Researchers can examine which genomic features those intervals intersect and which genes are nearby, then use those annotations to frame further analysis.

Keep the research question narrower than the available function list. For example, “Where are these peaks relative to annotated transcription start sites?” is an annotation question. “Which biological themes occur in an associated gene list?” is a subsequent enrichment question. The clusterProfiler enrichment guide covers the latter workflow. An annotation result is an input to that discussion, rather than a complete answer to it.

For a first analysis, make the deliverable a traceable peak-annotation file and a small set of interpretable figures. Write the intended comparison beside the script: one sample’s distribution, several samples annotated consistently, or the effect of changing a promoter definition. This makes it easier to distinguish an intentional analytical choice from a copied default.

Install or access

Install ChIPseeker through BiocManager, following its official Bioconductor package page. Run these commands inside R. They install the package; they do not annotate a dataset.

if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("ChIPseeker")

Use the release documentation that matches the installed environment. The development package page includes a separate development-release instruction; it is a different installation choice. For this walkthrough, stay with the release package. The Bioconductor installation guide explains release management and diagnoses packages that are too new or outdated with:

BiocManager::valid()

The example below also uses the human hg19 transcript database and human identifier annotation. Install those named dependencies explicitly if they are absent:

BiocManager::install(c("TxDb.Hsapiens.UCSC.hg19.knownGene", "org.Hs.eg.db"))

The hg19 knownGene annotation package exposes UCSC-derived annotation as a TxDb object. Treat that identity as part of the example. Installing a transcript database does not make it appropriate for every peak file. In your own project, name the annotation source alongside the reference used to generate the peaks; the reference genome analysis-set guide explains why reference identity needs explicit documentation.

Step-by-step task: annotate an official sample

This is a documentation-based walkthrough using ChIPseeker’s supplied example data, not a new biological experiment. The core calls follow the official release vignette. Use the sample before substituting a project file so that package setup and project-specific input problems can be checked separately.

  1. Load the software and annotation. Keep the database assignment visible in the script. A collaborator should not need to infer it from a filename elsewhere.

    library(ChIPseeker)
    library(TxDb.Hsapiens.UCSC.hg19.knownGene)
    txdb <- TxDb.Hsapiens.UCSC.hg19.knownGene
  2. Locate and inspect the sample. The vignette’s fourth sample is CBX6_BF. Print the returned file list before selecting it, then inspect the imported intervals.

    files <- getSampleFiles()
    print(files)
    peak <- readPeakFile(files[[4]])
    peak

    Retain the printed sample identity with the analysis record. If you later replace this input, change the record as well as the code. Calling a project analysis “the sample workflow” after replacing the file obscures what was actually analysed.

  3. Annotate with an explicit TSS window. This call uses the vignette’s window of 3,000 bases upstream and downstream of the transcription start site, abbreviated TSS. It also requests human identifier annotation.

    peakAnno <- annotatePeak(files[[4]],
        tssRegion = c(-3000, 3000),
        TxDb = txdb, annoDb = "org.Hs.eg.db")
    peakAnno

    Record the window as an analysis setting, rather than presenting it as a biological boundary established by this example. If your project uses another definition, explain the choice and retain it in the script.

  4. Inspect the annotation and distance summaries. Start with these documented plotting functions. Read the feature distribution and TSS-distance display alongside the annotated rows, rather than selecting a figure solely because it looks persuasive.

    plotAnnoBar(peakAnno)
    plotAnnoPie(peakAnno)
    plotDistToTSS(peakAnno)
  5. Convert and export the annotated rows. ChIPseeker documents conversion to a data frame. The following export is an illustrative handoff step using that conversion; choose the destination within your project.

    annotation <- as.data.frame(peakAnno)
    head(annotation)
    write.csv(annotation, file = "chipseeker-annotation.csv",
        row.names = FALSE)

    Keep the table, script, and parameter record together. A figure alone leaves a reviewer with fewer ways to inspect an unexpected assignment or trace a gene back to its input interval.

Output and how to read it

The ChIPseeker reference manual describes the annotation interface and conversion methods. The vignette identifies the annotation result as a csAnno object. Convert it when you need a rectangular export, while retaining the original object for the package’s plotting workflow.

Read three parts of the table separately. The input interval identifies the peak. The annotation field describes its assigned genomic feature. Gene-related fields and distanceToTSS describe the nearby annotation used by the method. The manual also documents additional identifier fields when an annotation database is supplied. Do not silently treat a gene identifier and a gene symbol as interchangeable labels.

Feature summaries require attention to overlap. The documented annotation priority is promoter, 5′ UTR, 3′ UTR, exon, intron, downstream, then intergenic. The genomicAnnotationPriority parameter makes that ordering configurable. A practical interpretation is that a single-category chart reflects a classification rule, not necessarily every genomic feature intersecting an interval.

For reporting, use wording that stays close to the operation: “peaks annotated to promoter regions under the stated window,” or “genes associated through the nearest-gene annotation.” Avoid promoting proximity into a claim that the gene is a demonstrated regulatory target. That distinction is an interpretation safeguard, not an extra result calculated by the sample code.

Before comparing two figures, ask whether their scripts describe the same assignment problem. A useful review exercise is to place the database name, TSS window, and annotation priority beside each figure. If any differ, describe the contrast as a comparison of analysis choices before interpreting it as a contrast between samples.

Troubleshooting

Separate installation problems from input problems

If the package cannot load or a dependency is inconsistent, begin with the installation environment. Bioconductor’s installation guide recommends BiocManager::valid() to identify incompatible package versions. Save its diagnostic output with the environment record before changing packages. This gives a collaborator something more precise than “the install failed.”

If installation succeeds but your project file fails, return to the supplied sample and keep the annotation settings fixed. That is a diagnostic comparison: one input works and another does not. It does not establish that either dataset has biological quality, but it helps identify which part of the workflow needs investigation.

Check reference and chromosome naming explicitly

The official vignette demonstrates converting chromosome naming style when using an EnsDb annotation. Treat naming style and genome assembly as separate questions. A label change should not be recorded as evidence that coordinates were converted between assemblies. In the project record, provide separate entries for the peak reference, annotation database, and any coordinate conversion actually performed.

For the supplied walkthrough, preserve the hg19 database. For a new dataset, stop and establish the relevant reference before reusing that line. A successful function call alone is too weak a criterion for deciding whether the selected annotation answers the intended question.

Check identifier meaning before enrichment

The vignette states that geneId follows the identifier system in the TxDb. The optional annoDb argument adds mappings. Consequently, a handoff should state which column supplies the gene list, which identifier system it represents, and which downstream analysis will consume it.

Inspect several exported rows against the corresponding annotation before passing the entire column onward. If the mapping step changes which rows remain usable, document that choice separately from peak annotation. This preserves the distinction between producing an annotation table and selecting a gene set for another method.

Free alternatives

These open-source Bioconductor packages cover overlapping tasks at different levels. Their official descriptions and licences support the comparison below; neither row is a benchmark or a claim of identical output. Choose by the operation you need to inspect, rather than expecting package names to be interchangeable.

Package Documented scope Comparison with this workflow Licence
ChIPpeakAnno Batch annotation of genomic intervals, including nearest genes or other features, sequence retrieval, and enrichment. An alternative annotation workflow to evaluate when its supported feature types match the research question. GPL, version 2 or later
GenomicRanges Containers and operations for representing and manipulating genomic intervals. A lower-level foundation for custom interval work; plan the annotation and reporting logic explicitly. Artistic-2.0

GenomicRanges also explains the interval-oriented representation underlying this ecosystem. When evaluating a custom workflow, write down its intended input, assignment rule, and expected output before comparing it with a packaged report. For single-cell chromatin analysis beyond this annotation task, see the separate ArchR workflow guide.

Report a reproducible annotation

A practical handoff record should allow another analyst to distinguish the software, the annotation data, and your decisions. The data table below brings those checks together from the official documentation. It is a checklist of documented controls, not an experimental dataset or a comparison of analytical accuracy.

For an illustrative composite project, keep a short record with the input filename, reference assembly, transcript database name, identifier annotation, TSS window, annotation priority, and exported table location. State whether the input is the supplied sample or a project dataset. Record a changed setting as a changed analysis, rather than overwriting the only copy of the earlier result.

Use browseVignettes("ChIPseeker") for installed documentation and citation("ChIPseeker") for the package citation. Include the annotation database identity in the methods record as well. This is the operational side of computational reproducibility: the deliverable includes enough context to repeat the assignment, inspect its assumptions, and understand the limits of its interpretation.

Sources

Data: ChIPseeker annotation controls and reporting checks

An original documentation crosswalk linking annotation settings and environment checks to the information an analyst should preserve. Compiled from the ChIPseeker manual and vignette, Bioconductor installation guidance, and the hg19 TxDb package record; not measured experimental results.

ChIPseeker annotation controls and reporting checks
ControlDocumented interfaceDocumented value or behaviorReporting checkSource URL
TSS annotation windowtssRegionc(-3000, 3000)State the selected TSS window; the example uses the documented default.https://bioconductor.org/packages/release/bioc/manuals/ChIPseeker/man/ChIPseeker.pdf
Feature assignment ordergenomicAnnotationPriorityPromoter; 5UTR; 3UTR; Exon; Intron; Downstream; IntergenicRetain the priority setting when interpreting single-category summaries.https://bioconductor.org/packages/release/bioc/manuals/ChIPseeker/man/ChIPseeker.pdf
Annotation levelleveltranscriptRecord whether annotation uses the transcript or gene option.https://bioconductor.org/packages/release/bioc/manuals/ChIPseeker/man/ChIPseeker.pdf
Transcript referenceTxDbTxDb.Hsapiens.UCSC.hg19.knownGeneName the annotation database used by the supplied hg19 example.https://bioconductor.org/packages/release/data/annotation/html/TxDb.Hsapiens.UCSC.hg19.knownGene.html
Identifier mappingannoDborg.Hs.eg.db in the vignetteRecord the mapping package and identifier system before downstream analysis.https://bioconductor.org/packages/release/bioc/vignettes/ChIPseeker/inst/doc/ChIPseeker.html
Environment consistencyBiocManager::valid()Flags too-new or outdated packagesKeep diagnostic output with the analysis environment record.https://www.bioconductor.org/install/

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about ChIPseeker: Install, Annotate Peaks and Read Output

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →