# How to Annotate Genomic Plots in R By the end of this guide you will be able to take a genomic plot made in R and add the layers that make it interpretable: gene models under a coverage track, labeled variant points on a locus plot, chromosome-level feature maps, and clinical or functional annotations beside a mutational landscape. You will need R (4.2 or newer is a sensible baseline), RStudio or another editor, an internet connection for installing packages, and a basic familiarity with data frames. If you have never used R for bioinformatics before, this walkthrough doubles as a gentle Bioconductor tutorial, because most genomic annotation data in R flows through Bioconductor infrastructure. Annotation here means adding biological meaning to plotted coordinates: which gene a peak falls in, which variant sits where in a protein, which chromosome carries which feature. Recent genomic visualization tools built in R reflect exactly this need. The yEvo Mutation Browser, an R Shiny tool for teaching experimental evolution, combines an interactive chromosome map, mutation type summaries, and a gene viewer that shows mutation sites within genes, all because raw variant coordinates mean little without gene context [1]. The same principle drives package design across the field. ## What Annotation Means in a Genomic Plot A genomic plot maps measurements onto coordinates along a genome: a coverage depth curve, a GWAS association signal, a set of variant calls. An annotation is any overlay or label that connects those coordinates to biology. The common annotation types are: 1. **Gene and transcript tracks**, which show exons, introns, strand, and gene names under or above the data. 2. **Feature labels**, which name specific points, peaks, or regions directly on the plot. 3. **Chromosome-level maps**, which place genes, repeats, or data tracks across whole chromosomes [2]. 4. **Variant annotations**, such as lollipop plots that mark the position of single nucleotide variations or protein modifications along a sequence [3]. 5. **Cohort-level summaries**, such as oncoprint-style mutation landscapes with clinical annotations attached [4]. 6. **Regional context**, such as [linkage disequilibrium](/knowledge/bioinformatics/linkage-disequilibrium-and-haplotype-mapping) (LD, the non-random co-inheritance of nearby variants) colored around a lead SNP in a regional association plot [5]. Two data structures matter throughout. The first is the data frame, which ggplot2 consumes. The second is the GRanges object from Bioconductor's GenomicRanges package, which stores genomic intervals with chromosome, start, end, and strand. Almost every annotation task reduces to moving intervals between these two representations correctly. ## Set Up Your R Environment Install CRAN packages for plotting and Bioconductor packages for genomic infrastructure. BiocManager is the standard installer for Bioconductor, the project that supplies most of the annotation machinery used in R for bioinformatics. ```r install.packages("BiocManager") BiocManager::install(c( "GenomicRanges", # interval arithmetic on genomes "GenomeInfoDb", # chromosome naming and style helpers "rtracklayer", # import and export BED, GFF, BigWig "AnnotationHub" # query annotation resources remotely )) install.packages(c("ggplot2", "ggrepel", "gggenes", "scales")) ``` Verify the installation by loading the core libraries and printing versions. Recording versions is a reproducibility habit worth building now. ```r library(GenomicRanges) library(ggplot2) packageVersion("ggplot2") ``` Expected output looks like this, with your own version numbers: ``` [1] '3.5.1' ``` Some specialized tools covered later, such as GenVisR, live on Bioconductor and install the same way with `BiocManager::install("GenVisR")` [4]. Others, such as ggcoverage and locuszoomr, are also available through Bioconductor or CRAN depending on the release cycle, so check each package's landing page rather than guessing the repository [5], [6]. ## Annotate Genomic Plots in R, Step by Step ![Five step flow showing import of gene intervals, conversion to a data frame, drawing gene arrows, adding repelled labels, and stacking panels.](/article-images/illustrations/annotate-genomic-plots-r-annotation-workflow.webp) This walkthrough builds a small annotated locus plot from scratch. The data are toy coordinates, but every command is real and runs as written. Replace the toy objects with your own BED files or variant tables when you adapt it. ### Step 1: Create or Import a Gene Annotation Track Start with a small set of genes on one chromosome. In practice you would import these from a GFF3 or BED file rather than typing them. ```r library(GenomicRanges) genes <- GRanges( seqnames = "chr1", ranges = IRanges(start = c(2000, 6000, 11000), end = c(4800, 8500, 16000)), strand = c("+", "-", "+"), gene = c("GENEA", "GENEB", "GENEC") ) genes ``` Expected output: ``` GRanges object with 3 ranges and 1 metadata column: seqnames ranges strand | gene | [1] chr1 2000-4800 + | GENEA [7] chr1 6000-8500 - | GENEB [3] chr1 11000-16000 + | GENEC ``` If your annotation lives in a file, rtracklayer reads it directly into a GRanges object: ```r library(rtracklayer) genes <- import("genes.bed", format = "BED") ``` BED files use zero-based, half-open coordinates, meaning the interval 0 to 100 covers bases 1 through 100 in one-based human terms. rtracklayer converts this for you on import, which is exactly why manual coordinate arithmetic is a frequent source of off-by-one errors (covered under common mistakes below). ### Step 2: Convert the GRanges Object to a Data Frame ggplot2 plots data frames, so the conversion step is the hinge between Bioconductor and ggplot2. This small conversion is the single most reusable trick in annotating genomic plots in R. ```r gene_df <- as.data.frame(genes) gene_df ``` Expected output: ``` seqnames start end width strand gene 1 chr1 2000 4800 2801 + GENEA 2 chr1 6000 8500 2501 - GENEB 3 chr1 11000 16000 5001 + GENEC ``` ### Step 3: Draw the Gene Track with gggenes The gggenes package draws genes as arrows oriented by strand, which is clearer than rectangles when genes run in both directions. ```r library(gggenes) gene_track <- ggplot(gene_df, aes(xmin = start, xmax = end, y = "genes", forward = strand == "+", label = gene)) + geom_gene_arrow(fill = "grey70", color = "black") + geom_gene_label(fontsize = 3) + scale_y_discrete(limits = "genes") + theme_genes() + labs(y = NULL, x = "Position on chr1 (bp)") gene_track ``` You now have an annotation-only panel. Keep it as a separate ggplot object. The next steps assemble it with a data panel. ### Step 4: Plot Your Data and Add Repelled Labels Suppose you have variants with a significance score. Plot the scores as points, then label each point with the gene it overlaps. To find overlaps between variants and genes, use `findOverlaps` on GRanges objects, then bring the gene names back into the data frame. ```r variants <- GRanges( seqnames = "chr1", ranges = IRanges(start = c(3000, 7000, 12500), width = 1), score = c(8.1, 6.4, 9.2) ) hits <- findOverlaps(variants, genes) variants$gene <- NA_character_ variants$gene[queryHits(hits)] <- genes$gene[subjectHits(hits)] var_df <- as.data.frame(variants) var_df ``` Expected output: ``` seqnames start width strand score gene 1 chr1 3000 1 * 8.1 GENEA 2 chr1 7000 1 * 6.4 GENEB 3 chr1 12500 1 * 9.2 GENEC ``` Now plot the data panel and label points with ggrepel, which offsets text labels algorithmically so they do not collide with points or each other. The dplyr, ggrepel, and tidyr stack appears in published genomic profiling workflows precisely for this kind of labeled plotting [8]. ```r library(ggrepel) data_panel <- ggplot(var_df, aes(x = start, y = score)) + geom_point(size = 2, color = "firebrick") + geom_text_repel(aes(label = gene), size = 3, max.overlaps = 20, segment.color = "grey40") + labs(x = NULL, y = "Score") + theme_classic() ``` `max.overlaps` controls how many labels ggrepel will tolerate before dropping the worst offenders. Raising it keeps more labels but risks clutter. `segment.color` styles the connector line from label to point, which helps readers trace a label to its exact coordinate in a dense plot. ### Step 5: Stack the Data Panel and the Gene Track Two panels share the same x axis, so patch them vertically and align widths. The patchwork package handles this in two lines. ```r # install.packages("patchwork") library(patchwork) combined <- data_panel / gene_track + plot_annotation(title = "Variants in context on chr1") combined ``` Because both panels use the same position aesthetic, ggplot2 keeps the coordinates aligned. When you zoom the x axis with `coord_cartesian(xlim = c(1000, 17000))`, apply it to both panels or apply it before patching so the annotation stays registered with the data. Misaligned axes are one of the most common failures when people assemble annotated genomic figures by hand. ### Step 6: Style the Axis in Genomic Units Raw base-pair numbers are unreadable past a few thousand. Rescale the x axis to kilobases or megabases. ```r combined <- combined & scale_x_continuous(labels = function(x) paste0(x / 1000, " kb")) combined ``` The `&` operator in patchwork applies a setting to every panel at once, which prevents the common bug where the data panel and gene track end up with different axis labels. ### Step 7: Save a Publication-Quality File ```r ggsave("locus_annotated.png", combined, width = 7, height = 4, dpi = 300, bg = "white") ggsave("locus_annotated.pdf", combined, width = 7, height = 4) ``` Use a vector format such as PDF or SVG when the journal accepts one, because text in vector figures stays sharp and selectable. For raster output, 300 dpi is the conventional floor for print, and setting `bg = "white"` avoids transparent backgrounds that render dark in some viewers. ## Using Purpose-Built Annotation Packages The manual ggplot2 workflow above teaches you the mechanics. In day-to-day work, specialized packages save hours because they bundle annotation retrieval and plotting together. The choice among them depends on the scale of your plot and the kind of data. | Package or tool | Plot scale | What it annotates | Notes | |--|--|--|--| | ggplot2 plus ggrepel, gggenes | Any | Points, labels, gene arrows | Full manual control, most code [8] | | ggcoverage | Locus to chromosome | Genome coverage for WGS, WES, RNA-seq, ChIP-seq | Reads BAM, BigWig, BedGraph, TSV, layers annotations with + [6] | | locuszoomr | Regional locus | GWAS signal with gene tracks, LD, recombination rate | Queries Ensembl through Bioconductor or AnnotationHub, interactive via plotly [5] | | GenVisR | Cohort | Mutation landscapes, copy number, clinical annotation | Bioconductor package with protocol-level documentation [4] | | chromoMap | Whole chromosomes | Genes, repeats, expression, methylation on chromosome maps | BED-like input, interactive hover, static or HTML output [2] | | Shiny frameworks (ChroKit, shinyChromosome, XVCF) | Varies | Interactive annotation without coding per figure | Point-and-click re-analysis and export [9], [10], [11] | ### Coverage Plots with ggcoverage ggcoverage is designed for the specific problem of visualizing [sequencing depth](/knowledge/diagnostics/molecular/how-to-calculate-sequencing-depth-and-coverage-for-your-ngs-run) and adding the right annotation for each assay type, whether whole-genome sequencing, RNA-seq, or ChIP-seq [6]. It accepts BAM, BigWig, BedGraph, and TSV inputs, handles read normalization and consensus peak generation, and lets you superimpose annotation layers with the `+` operator the same way you would in plain ggplot2 [6]. The practical pattern is to let ggcoverage build the coverage track and then append your own ggplot2 layers for labels and styling, which keeps one consistent grammar across the figure. Check the package vignette for the current function signatures before scripting against it, since arguments are revised between releases. ### Regional GWAS Plots with locuszoomr If your task is annotating regional association plots, locuszoomr reproduces the classic LocusZoom style inside R, plotting genomic or GWAS data with gene annotation tracks through either base graphics or ggplot2 [5]. Its helper functions pull gene information from Ensembl databases via Bioconductor or AnnotationHub, so the gene track matches your species without manual curation [5]. It can overlay linkage disequilibrium data from the 1000 Genomes Project through the LDlink API and recombination rate data from UCSC, and it supports plotly-based interactive versions for quickly identifying which point is which [5]. It is also fast, identifying 50 peaks in a GWAS of roughly 8 million SNPs in around 0.6 seconds and exporting 50 locus plots with a 1 megabase window and recombination rate in about 30 seconds [5]. That speed matters because annotation errors are usually discovered by iterating, and slow iteration discourages checking. ### Cohort Mutation Plots with GenVisR For cancer genomics and other cohort-level work, GenVisR is a Bioconductor package built to lower the entry point for publication-quality genomic graphics [4]. Its Waterfall function creates oncoprint-style plots of the mutational landscape of a tumor cohort, and the published protocols walk through installation, data import, adding clinical annotation, customizing mutation burden, and final plot configuration [4]. The annotation lesson transfers directly: clinical columns are joined to the mutation table by sample identifier, then passed as separate annotation data to the plotting function, keeping the data layer and annotation layer distinct. ### Chromosome Maps with chromoMap chromoMap builds interactive chromosome-level visualizations where any feature with known coordinates, from protein-coding genes to microsatellites, is painted onto rendered chromosomes [2]. Input is simple: tab-delimited BED-like files or R objects describing chromosome and element coordinates, plus an optional data file to color regions by expression, methylation, or chromatin state [2]. Hovering over a window reveals details about the elements inside it, and the same function call can produce a static image or a standalone HTML widget [2]. This is the fastest path from a BED file to an annotated whole-genome figure, though it works at chromosome resolution rather than base-pair resolution. ### Lollipop Plots for Sequence-Level Annotation When the coordinates you care about run along a gene or protein rather than a chromosome, lollipop plots are the standard form. M2Viz, a web tool with a Python backend, demonstrates the demand for these plots across [DNA methylation](/blog/guides/dna-methylation) sites, single nucleotide variations, protein post-translational modifications, and single amino acid variations, with an end-to-end pipeline from upload through annotation to graphical output [3]. You can build the same figure natively in R with two ggplot2 layers: a segment from the sequence axis up to each event, and a point at the event. ```r events <- data.frame( pos = c(120, 340, 780, 1150), h = c(2.0, 3.1, 1.4, 2.6), type = c("SNV", "SNV", "PTM", "SNV") ) ggplot(events, aes(x = pos, xend = pos, y = 0, yend = h)) + geom_segment(linewidth = 0.5, color = "grey40") + geom_point(aes(y = h, color = type), size = 3) + scale_x_continuous(labels = function(x) paste0(x, " aa")) + labs(x = "Position in protein (amino acids)", y = "Relative height", color = "Event type") + theme_minimal() ``` Map color or shape to the event type so readers can distinguish variant classes without a legend table, and keep the stem heights uniform unless height encodes a real quantity such as allele frequency. ### Interactive Annotated Plots with Shiny R Shiny applications represent the other end of the annotation spectrum, where the plot is annotated through a graphical interface rather than code. Several published tools show the range. ChroKit is a Shiny framework for ChIP-seq and similar enrichment data that performs region annotation by proximity to genomic features, gene ontology association, and signal enrichment, with plots that users manipulate by point and click and working sessions that can be exported for reproducibility [9]. shinyChromosome provides a GUI for creating non-circular whole genome diagrams annotated through diverse widgets, deployable on personal computers or public servers [10]. XVCF wraps the vcfR and maftools packages in a Shiny interface to summarize and visualize variant data from VCF files, extracting read depth, mapping quality, genotype, and allele frequency from otherwise unannotated data [11]. For proteomics, PSpecteR annotates mass spectra with fragmentation patterns, tests post-translational modifications, and plots where identified fragments map to reference sequences, with exportable figures inside one interface [7]. If you annotate the same plot type repeatedly for collaborators, building or adopting a Shiny front end can pay for itself, but keep the underlying rendering code in version control so the figures remain reproducible. ## Annotate Genomic Plots in R: Tips That Save Time These tips come up in nearly every annotated-figure session. 1. **Keep annotation and data in separate objects.** Join them by coordinates or identifiers at plot time. This mirrors how published Shiny tools separate data processing from visualization [9] and makes it trivial to swap assemblies or annotation releases. 2. **Normalize chromosome naming before plotting, not during.** The `seqlevelsStyle` function in GenomeInfoDb converts between styles such as `1` (Ensembl) and `chr1` (UCSC). Do this once, on both the data and the annotation objects. 3. **Use `scale_x_continuous` with a function for units.** Dividing by 1000 or 1,000,000 inside the labels function produces kilobase or megabase ticks without changing the underlying data. 4. **Tune ggrepel deliberately.** `max.overlaps`, `nudge_x`, and `segment.color` interact. For dense loci, label only the top hits and accept that most points stay anonymous, which is also how the standard locus plot tools behave [5]. 5. **Check overlaps computationally before labeling.** `findOverlaps` returns a Hits object, and forgetting that `queryHits` and `subjectHits` index into the two original objects, not into each other's ranges, is a frequent bug. 6. **Facet by chromosome for genome-wide scatter plots.** `facet_wrap(~seqnames, scales = "free_x")` gives each chromosome its own x scale while keeping a shared y, which is the honest way to show genome-wide signals. 7. **Prefer colorblind-safe palettes and direct labels over legends where possible.** Interactive tools rely on hover text for this, and the hover pattern in chromoMap, where hovering a window reveals annotated element details, is worth imitating in static figures through direct labels [2]. 8. **Record your session.** `sessionInfo()` at the end of a script, plus a saved copy of the exact annotation file, is the difference between a figure you can regenerate in a year and one you cannot. Shiny frameworks that export working sessions for reproducibility are solving the same problem [9]. 9. **Match the assembly version of your annotation to your data.** Coordinates from one assembly are meaningless against another. State the assembly in the figure legend or caption. 10. **Iterate on the interactive version first.** plotly conversion of a ggplot object, as locuszoomr supports for identifying points, lets you confirm labels are attached to the right coordinates before you commit to a static export [5]. ## Common Mistakes and Limitations ### Off-by-one coordinate errors from BED files BED is zero-based and half-open. GFF, GTF, VCF, and most R conventions are one-based. If you read a BED file with `read.table` instead of rtracklayer's `import`, every feature shifts by one base, which is invisible at plot resolution but wrong when anyone reads exact positions off the figure. Use rtracklayer or convert explicitly, and document which convention your input used. ### Chromosome name mismatches ![Decision path for empty overlap results, checking chromosome naming first, then coordinate convention, before re-running findOverlaps.](/article-images/illustrations/annotate-genomic-plots-r-overlaps-empty.webp) Your data might say `1` while your annotation says `chr1`, or your mitochondrion might be labeled `MT` in one source and `chrM` in another. Symptoms are silent: overlaps return nothing, tracks vanish, and the plot looks complete while missing annotations. Run `seqlevels(data)` and `seqlevels(annot)` and compare them before any `findOverlaps` call. Fix with `seqlevelsStyle` or explicit renaming. ### Labels that overlap into unreadability Default `geom_text` places labels exactly on points, so dense regions become ink blots. Use `geom_text_repel` with a sane `max.overlaps` value, or thin the label set to the points that matter. A figure where every point is labeled communicates less than one where the three relevant points are labeled clearly. ### Mixing coordinate systems across panels When a coverage panel, a variant panel, and a gene track are assembled separately, any difference in x limits or axis breaks makes annotations point at the wrong bases. Apply shared scales before combining panels, and verify alignment by checking that a known feature (for example, a variant inside a gene) visually lands inside the correct arrow. ### Assuming the plot is the annotation A labeled figure is not a verified mapping. A point labeled with a gene name is only as good as the overlap logic and the annotation release behind it. Spot-check a few labels by querying the coordinates against a genome browser for the same assembly. Published annotation-heavy tools reduce but do not eliminate this burden, since they depend on the annotation databases they query [5]. ### Forgetting strand when drawing gene models Gene arrows drawn without strand information point in arbitrary or uniform directions, which misrepresents the biology and can mislead readers about transcript orientation. Carry the strand column from the GRanges object into the aesthetic mapping, as the gggenes `forward` aesthetic does above. ### Saving figures with the wrong geometry A locus plot squeezed into a wide, short rectangle distorts perceived distances. Set `width` and `height` in `ggsave` to the intended print dimensions, and check that the aspect ratio does not compress introns so far that a gene looks like a single block. ### Scale and tool limitations Packages are versioned software. Function signatures change between releases, and an annotation package that queried one database version last year may query a different one today. Pin package versions in your project, note the annotation release alongside the genome assembly, and re-run the plotting script after any upgrade. Finally, remember that annotation quality varies by species and by region of the genome, so a beautifully annotated track is not evidence that the annotation itself is complete or correct. ## Frequently Asked Questions ### What does annotating a genomic plot in R actually involve? It means overlaying biological context onto plotted genomic coordinates, most often gene tracks under data tracks, text labels on specific points or peaks, chromosome-level feature maps, or variant positions along a gene or [protein sequence](/blog/guides/protein-sequence). The typical workflow imports intervals into a GRanges object, converts them to data frames, and adds them as ggplot2 layers [6],. ### Do I need Bioconductor to annotate genomic plots in R? For anything involving real genome annotations, effectively yes. Bioconductor supplies GenomicRanges for interval operations, rtracklayer for reading BED and GFF files, and AnnotationHub for querying annotation resources. Plain CRAN packages handle the drawing, but the annotation data itself almost always passes through Bioconductor infrastructure, which is why R for bioinformatics is so tightly tied to that ecosystem [5]. ### How do I add a gene track below my data in ggplot2? Import the annotation with rtracklayer, convert the GRanges object to a data frame with `as.data.frame`, and draw it as its own ggplot object using arrow-shaped gene glyphs from gggenes or simple segments. Then stack the data panel and gene track vertically with patchwork so they share the same x axis. Alignment of the two panels is the critical step, not the drawing itself. ### How do I stop point labels from overlapping? Use ggrepel's `geom_text_repel` instead of `geom_text`. It offsets labels algorithmically with connector lines back to the points. The `max.overlaps` argument controls how many collisions are tolerated before labels are dropped, and `segment.color` styles the connectors. Published genomic profiling workflows use ggrepel for exactly this reason [8]. ### Can I make an annotated genomic plot interactive? Yes. chromoMap renders chromosomes with hoverable windows that reveal annotated elements, output either as static images or HTML widgets [2]. locuszoomr converts locus plots to plotly for point identification [5]. For fully interactive applications, Shiny frameworks such as ChroKit support point-and-click re-analysis of annotated genomic regions [9]. ### Why do my overlaps return nothing even though the coordinates look right? Two suspects, in order of likelihood. First, chromosome naming differs between your data and annotation, such as `1` versus `chr1`, so `findOverlaps` matches zero intervals. Second, one input was parsed with the wrong coordinate convention, typically a zero-based BED file read without rtracklayer. Compare `seqlevels` on both objects and confirm coordinate conventions before debugging anything else. ### How do I export an annotated plot for publication? Use `ggsave` with explicit `width` and `height` matching your target figure size, a vector format such as PDF or SVG when allowed, and 300 dpi or higher for raster formats. For multi-panel annotated figures, apply shared scales and themes across panels before saving so labels and axes stay consistent in the exported file. ### Which tool should I use for cohort-level mutation annotation? GenVisR on Bioconductor is purpose-built, with a Waterfall function for oncoprint-style mutation landscapes and documented protocols for adding clinical annotation, customizing mutation burden, and configuring plots [4]. For chromosome-scale mapping of many feature types at once, chromoMap takes BED-like input and renders interactive annotated chromosome maps [2]. For lollipop-style plots of variants along a gene or protein, the two-layer ggplot2 approach shown above reproduces the format popularized by dedicated tools [3]. ## Sources 1. [The yEvo Mutation Browser: Enhancing student understanding of experimental evolution and genomics through interactive data visualization.](https://pubmed.ncbi.nlm.nih.gov/42933842/) 2. [ChromoMap: an R package for interactive visualization of multi-omics data and annotation of chromosomes.](https://pubmed.ncbi.nlm.nih.gov/35016614/) 3. [M2Viz: a tool for visualizing genetic or proteomic modifications and variants.](https://pubmed.ncbi.nlm.nih.gov/42129619/) 4. [Exploring the Genomic Landscape of Cancer Patient Cohorts with GenVisR.](https://pubmed.ncbi.nlm.nih.gov/34506690/) 5. [locuszoomr: an R package for visualizing publication-ready regional gene locus plots.](https://pubmed.ncbi.nlm.nih.gov/40099154/) 6. [ggcoverage: an R package to visualize and annotate genome coverage for various NGS data.](https://pubmed.ncbi.nlm.nih.gov/37559015/) 7. [PSpecteR: A User-Friendly and Interactive Application for Visualizing Top-Down and Bottom-Up Proteomics Data in R.](https://pubmed.ncbi.nlm.nih.gov/33661636/) 8. [Synergistic role of molecular imaging and genomics in thyroid cancer management: from diagnosis to personalized treatment.](https://pubmed.ncbi.nlm.nih.gov/42806342/) 9. [ChroKit: a Shiny-based framework for interactive analysis, visualization and integration of genomic data.](https://pubmed.ncbi.nlm.nih.gov/37144464/) 10. [shinyChromosome: An R/Shiny Application for Interactive Creation of Non-circular Plots of Whole Genomes.](https://pubmed.ncbi.nlm.nih.gov/31931182/) 11. [XVCF: Exquisite visualization of VCF data from genomic experiments.](https://pubmed.ncbi.nlm.nih.gov/42323052/)