gggenomes: a grammar of graphics for comparative genomics

ggplot2 for genomes

gggenomes is described as a versatile graphics package for comparative genomics that extends the popular R visualisation package ggplot2 by adding dedicated plot functions for genes, syntenic regions and similar things, plus verbs to manipulate the plot, for example to zoom quickly into gene neighbourhoods.

The relationship to ggplot2 is the point. The package is not a competing plotting system, it is an extension of one, and the vocabulary is ggplot2's vocabulary with genome specific layers added. That means the scales, the themes, the facets and the composition rules are the ones you already know, and a genome figure is assembled the same way as any other ggplot2 figure.

The subject matter is comparative genomics, which means the figures are the ones where several genomes are lined up and their shared and rearranged regions are drawn between them. A synteny map is the archetypal example, and it is the one the README uses to introduce the package.

The package is published on CRAN with a project site and a documentation site built with pkgdown, and the repository carries the usual R package structure with the source, the manual pages, the tests and the vignettes.

The motivating example: six viral genomes

The README leads with a realistic use case rather than a toy, and it is the one that explains why the package exists.

The example compares the genomic architecture of six viral genomes, initially described in work by Hackl and colleagues on endogenous virophages in a marine heterotrophic flagellate, and it combines data and annotations from different sources into one plot.

The code shows what that means in practice.

library(gggenomes)

# to inspect the example data shipped with gggenomes
data(package="gggenomes")

gggenomes(
  genes = emale_genes, seqs = emale_seqs, links = emale_ava,
  feats = list(emale_tirs, ngaros=emale_ngaros, gc=emale_gc)) |> 
  add_sublinks(emale_prot_ava) |>
  sync() + # synchronize genome directions based on links
  geom_feat(position="identity", size=6) +
  geom_seq() +
  geom_link(data=links(2)) +
  geom_bin_label() +
  geom_gene(aes(fill=name)) +
  geom_gene_tag(aes(label=name), nudge_y=0.1, check_overlap = TRUE) +
  geom_feat(data=feats(ngaros), alpha=.3, size=10, position="identity") +

Two things are visible there that matter for understanding the design.

The first is that several data sets are passed at once: genes, sequences, links between them, and a list of feature sets including transposable elements and GC content. They are not merged into one table. They stay separate and the plot layers draw from each.

The second is the mixture of two syntaxes. The pipe operator is used for the verbs that manipulate the plot object, such as adding sub-links and synchronising, and the plus operator is used for the layers that add to the plot. That split is not arbitrary, and the README explains it in the concept section: the verbs act on the data and its layout, while the layers act on the drawing.

The concept: multiple tidy tables over one layout

The motivation section is the clearest statement of the philosophy.

Visualisation is a cornerstone of both exploratory analysis and science communication, but bioinformatics workflows tend to generate a plethora of data products often in adventurous formats, which makes them hard to integrate and co-visualise. Instead of trying to cater to all these different formats explicitly, gggenomes embraces the tidyverse inspired credo in two lines: any data set can be transformed into one or a few tidy data tables, and any data set in a tidy data table can be easily and elegantly visualised.

So the format problem is not solved by the package, it is relocated. You still have to get your annotations into tidy tables, but once they are there, they can be plotted together.

Under the hood, the README explains the mechanism. gggenomes uses a light-weight track system to accommodate a mix of related data sets, essentially implementing ggplot2 with multiple tidy tables instead of just one.

The tables are tied together through a global genome layout that is automatically computed from the input, and that layout defines the positions of the genomic sequences, the chromosomes or contigs, and their associated features in the plot. The synchronise verb is the visible part of this, and the README comments it as synchronising genome directions based on links, which is the operation that decides which sequence is drawn pointing which way.

That automatic layout is the feature that makes the package pleasant and the thing to watch. Because the layout is computed rather than declared, a figure can combine four annotation sources without you having to reconcile their coordinate systems by hand, and the risk moves from the drawing code to the layout computation.

Verbs, layers and zooming

The API divides into the verbs that manipulate the plot and the layers that draw it, and the example shows both.

The verbs appear at the start, piped into the plot object. Adding sub-links extends the link set with a further annotation of links between sequences. Synchronising is the layout operation described above.

The layers are the geom functions, and each corresponds to a type of genomic feature. The feat layer draws feature sets, with options for position and size. The seq layer draws the sequences themselves. The link layer draws the connections between them, and it takes a data argument so that a subset of links can be drawn. The bin label layer labels the link bins. The gene layer draws genes with a fill mapping. The gene tag layer labels them, with a nudge and an overlap check so the labels stay readable. The feat note layer annotates features with text. And the wiggle layer draws a quantitative track, used in the example for GC content with a line type mapping and a fill colour.

The zoom verb is the one the README highlights, because it is the feature with no ggplot2 equivalent. Genomes are large and a figure has to show both the whole picture and a small neighbourhood, so being able to zoom into a gene neighbourhood and redraw is what makes the package usable for real analysis rather than for a poster figure.

The README also points to a long-form article describing the full evolution of the example plot from a mere set of contigs, including the bioinformatics analysis workflow, which is the closest thing to a tutorial the project has.

Installation and the optional tree package

gggenomes is available as a stable release on CRAN from version 1.0.1, and the latest developmental versions are available on GitHub.

# Install from CRAN
install.packages("gggenomes") 

# optionally install ggtree to plot genomes next to trees
# https://bioconductor.org/packages/release/bioc/html/ggtree.html
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("ggtree")

# Install latest developmental version from github
devtools::install_github("thackl/gggenomes")

The optional part is worth noting, because it is a common pattern in this ecosystem. Plotting a genome next to a phylogenetic tree is a standard figure in comparative genomics, and the tree is drawn by a separate package, so gggenomes can either depend on it or work alongside it. The installation snippet shows the collaborative approach: the tree package comes from Bioconductor and is installed through the Bioconductor manager rather than from CRAN, and the code checks for the manager first and installs it if it is missing.

That snippet is also a good illustration of the ecosystem gggenomes lives in. CRAN for the package itself, Bioconductor for the neighbouring analysis tools, and GitHub for the development version. The R package manager for developers installs from GitHub, which is what you want when you are testing a change or reproducing a result that used the development branch.

Inspiration, releases and the state of the project

The README names three packages that gggenomes draws inspiration from, and they are the right ones to look at if you want to understand the design.

The first is gggenes, by David Wilkins, which showed how genes could be drawn with ggplot2. The second is ggtree, by Guangchuang Yu, which is the tree drawing package that the installation instructions pair with it. The third is ggraph, by Thomas Lin Pedersen, which brought the grammar of graphics approach to network data and which is the closest in spirit, since a synteny map is a graph laid out along a genome.

The releases are v1.2.0 from 2026-09-24 and v1.1.3 from 2026-08-24, and the last push was on 2026-10-05. So the package is on a 1.x line with a steady cadence of patch and minor releases, and it is available from CRAN as well as from GitHub.

The repository layout is the standard R package one with a couple of additions. There is the source directory, the manual pages, the vignettes, the shipped example data in a data directory, the tests, and a pkgdown configuration for the documentation site. There is also an exec directory, which in R packages usually holds scripts run during the build, and a CRAN submission marker and cran comments file, which are the artefacts of a package that is being submitted to CRAN.

Three checks before you use it. That your annotation sources can be turned into tidy tables, because that work is the price of the package. That the automatically computed layout matches the contig order and orientation you want for the figure, since the synchronise verb changes what you see. And whether you need the optional tree package, which is an extra dependency from a different repository and not something the core package requires.

Editorial conclusion

gggenomes suits a comparative genomist who already works in the tidyverse and is tired of assembling genome figures from several data formats by hand, because the package holds the annotation tables side by side over one layout and gives you the geom functions that a genome figure needs. It is the wrong choice if your data is not in a form you can make tidy, since that transformation work is yours and the package does not do it for you, and the wrong choice if you need publication figures with a house style that the fixed geoms do not cover. Verify first that your annotation sources can be expressed as tidy tables, that the layout the package computes matches the contig order you want, and whether you need the optional tree package for figures that pair a genome with a phylogeny.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. thackl/gggenomes on GitHub