In PhanstielLab/BentoBox: Coordinate-Based Genomic Visualization Package for R

knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    fig.height = 5,
    fig.width = 6,
    fig.align = "center"
)
library(plotgardener)
library(grid)
library(plotgardenerData)

plotgardener was developed to give users unparalleled control in plotting and arranging multiple figures entirely within the R plotting environment. This functionality is motivated by the following design principles:

Coordinate-based plot placement

A coordinate-based plotting system provides users with exquisite control over plot sizes and arrangements through a user-defined page and common units of measurement. This system makes the plotgardener plotting process intuitive and absolute, meaning that plots cannot be squished and stretched based on their relative sizes and placements. Users can create a page in their preferred size and unit of measurement:

pageCreate(width = 3, height = 3, default.units = "inches")

and then make and precisely arrange plots within this defined landscape. If users want the top, left corner of their plot to be 0.5 inches down from the top of this page and 0.5 inches from the left:

pageCreate(width = 3, height = 3, default.units = "inches")
plotSegments(x0 = 0.5, y0 = 0, x1 = 0.5, y1 = 0.5, 
                arrow = arrow(angle = 30, 
                            length = unit(0.1, "inches"), 
                            ends = "last", type = "closed"), 
                fill = "black")
plotSegments(x0 = 0, y0 = 0.5, x1 = 0.5, y1 = 0.5, 
                arrow = arrow(angle = 30, 
                            length = unit(0.1, "inches"), 
                            ends = "last", type = "closed"),
                fill = "black")
plotText(label = "0.5 in", x = 0.6, y = 0.25, just = "left")
plotText(label = "0.5 in", x = 0.25, y = 0.6, just = "top")

and users want their plot be 2 inches wide and 1 inch tall:

pageCreate(width = 3, height = 3, default.units = "inches")
plotSegments(x0 = 0.5, y0 = 0, x1 = 0.5, y1 = 0.5, 
                arrow = arrow(angle = 30, 
                            length = unit(0.1, "inches"), 
                            ends = "last", type = "closed"), 
                fill = "black")
plotSegments(x0 = 0, y0 = 0.5, x1 = 0.5, y1 = 0.5, 
                arrow = arrow(angle = 30, 
                            length = unit(0.1, "inches"), 
                            ends = "last", type = "closed"), 
                fill = "black")
plotSegments(x0 = 0.5, y0 = 0.5, x1 = 2.5, y1 = 0.5, fill = "black", 
                arrow = arrow(angle = 30, 
                            length = unit(0.1, "inches"), 
                            ends = "both", type = "closed"))
plotSegments(x0 = 0.5, y0 = 0.5, x1 = 0.5, y1 = 1.5, fill = "black", 
                arrow = arrow(angle = 30, 
                            length = unit(0.1, "inches"), 
                            ends = "both", type = "closed"))
plotText(label = "2 in", x = 1.5, y = 0.4, just = "bottom")
plotText(label = "1 in", x = 0.4, y = 1, just = "right")

plotgardener can make the plot with these exact parameters:

## Create plotgardener page
pageCreate(width = 3, height = 3, default.units = "inches")

## Load signal data
data("IMR90_ChIP_H3K27ac_signal")

## Plot and place signal data with precise measurements
signalPlot <- plotSignal(
    data = IMR90_ChIP_H3K27ac_signal,
    chrom = "chr21", chromstart = 28000000, chromend = 30300000,
    x = 0.5, y = 0.5, width = 2, height = 1,
    just = c("left", "top"), default.units = "inches"
)

This exact plot sizing and placement is particularly important and useful for standardized and accurate data comparisons along the x and y-axes.

Containerized, edge-to-edge visualizations

With the stacked nature of genomic plots, it is critical that aligned plots correspond to the same genomic regions to ensure figure accuracy. By separating data plotting from plot annotations, data fills defined plot coordinates and dimensions from edge to edge and precisely preserves the mapping between the data and its user-defined container. For example, if a user creates a 2 inch-wide gene track and wants that plot to represent the genomic region chr8:1000000-2000000, this genomic region will exactly span the 2 inch width:

library(TxDb.Hsapiens.UCSC.hg19.knownGene)
library(org.Hs.eg.db)

## Create plotgardener page
pageCreate(width = 3, height = 2, default.units = "inches")

## Define genomic region with `pgParams`
genomicRegion <- pgParams(chrom = "chr8", 
                        chromstart = 1000000, chromend = 2000000,
                        assembly = "hg19")

## Plot genes with background color highlighting size
genesPlot <- plotGenes(
    params = genomicRegion, bg = "#f6f6f6",
    x = 0.5, y = 0.5, width = 2, height = 1,
    just = c("left", "top"), default.units = "inches"
)

## Annotate genome label
annoGenomeLabel(
    plot = genesPlot, scale = "Mb",
    x = 0.5, y = 1.5,
    just = c("left", "top"), default.units = "inches"
)

When it's time to stack various data types along the same genomic region, users can be confident in accurately aligning containers of the same width:

## Load data
library(plotgardenerData)
data("IMR90_HiC_10kb")
data("IMR90_DNAloops_pairs")
data("IMR90_ChIP_H3K27ac_signal")

## Define genomic region and widths of all plots
params <- pgParams(
    chrom = "chr21", chromstart = 28000000, chromend = 30300000,
    assembly = "hg19",
    x = unit(0.5, "inches"), width = unit(2, "inches")
)

## Create plotgardener page
pageCreate(width = 3, height = 4, default.units = "inches")

## Plot Hi-C data in region
hicPlot <- plotHicSquare(
    data = IMR90_HiC_10kb,
    params = params,
    y = 0.5, height = 2,
    just = c("left", "top"), default.units = "inches"
)


## Plot and align DNA loops in region
bedpeLoops <- plotPairsArches(
    data = IMR90_DNAloops_pairs,
    params = params, fill = "black", linecolor = "black",
    y = 2.6, height = 0.45,
    just = c("left", "top"), default.units = "inches"
)

## Plot and align signal track in region
signalPlot <- plotSignal(
    data = IMR90_ChIP_H3K27ac_signal,
    params = params,
    y = 3.1, height = 0.45,
    just = c("left", "top"), default.units = "inches"
)

## Annotate genome label
annoGenomeLabel(
    plot = signalPlot,
    params = params, scale = "Mb",
    y = 3.57, just = c("left", "top"), default.units = "inches"
)

Programmatic and reproducible multi-panel figures

Data visualization is most rigorous and accurate when it is reproducible. Although many visualizations are initially designed with code, final customizations and arrangements of figures are typically made with third party graphic design software and cannot be easily replicated. plotgardener makes this entire process programmatic, from raw data input to finalized, complex visualization. This means that if users define the same data:

library(TxDb.Hsapiens.UCSC.hg19.knownGene)
library(org.Hs.eg.db)
library(ggplot2)
data(mtcars)
library(plotgardenerData)
data("IMR90_HiC_10kb")
head(IMR90_HiC_10kb)

and the same plotgardener code:

## Create a plotgardener page
pageCreate(width = 7, height = 3.5, default.units = "inches")

## Define genomic region with `params`
params <- pgParams(chrom = "chr21", 
                    chromstart = 28000000, chromend = 30300000,
                    assembly = "hg19")

## Plot Hi-C data
hicPlot <- plotHicTriangle(
    data = IMR90_HiC_10kb,
    params = params,
    x = 0.5, y = 0.5, width = 3, height = 1.5,
    just = c("left", "top"), default.units = "inches"
)

## Add color scale annotation
annoHeatmapLegend(
    plot = hicPlot,
    x = 3.5, y = 0.5, width = 0.12, height = 1,
    just = c("right", "top"), default.units = "inches"
)

## Plot gene track in same genomic region
genesPlot <- plotGenes(
    params = params,
    x = 0.5, y = 2.25, width = 3, height = 0.5,
    just = c("left", "top"), default.units = "inches"
)

## Label genomic region
annoGenomeLabel(
    plot = genesPlot,
    x = 0.5, y = 2.8, just = c("left", "top"), default.units = "inches"
)

## Create and place mtcars boxplot
boxPlot <- ggplot(mtcars) +
    geom_boxplot(aes(gear, disp, group = gear))
plotGG(
    plot = boxPlot,
    x = 4, y = 0.5, width = 2.5, height = 2,
    just = c("left", "top"), default.units = "inches"
)

## Label panels
plotText(
    label = "A", fontsize = 16, fontface = "bold",
    x = 0.75, y = 0.5, just = "center", default.units = "inches"
)
plotText(
    label = "B", fontsize = 16, fontface = "bold",
    x = 3.75, y = 0.5, just = "center", default.units = "inches"
)

## Hide page guides
pageGuideHide()

they will generate the exact same multi-panel visualization:

## Create a plotgardener page
pageCreate(
    width = 7, height = 3.5, default.units = "inches",
    xgrid = 0, ygrid = 0, showGuides = FALSE
)

## Define genomic region with `params`
params <- pgParams(chrom = "chr21", 
                    chromstart = 28000000, chromend = 30300000,
                    assembly = "hg19")

## Plot Hi-C data
hicPlot <- plotHicTriangle(
    data = IMR90_HiC_10kb,
    params = params,
    x = 0.5, y = 0.5, width = 3, height = 1.5,
    just = c("left", "top"), default.units = "inches"
)

## Add color scale annotation
annoHeatmapLegend(
    plot = hicPlot,
    x = 3.5, y = 0.5, width = 0.12, height = 1,
    just = c("right", "top"), default.units = "inches"
)

## Plot gene track in same genomic region
genesPlot <- plotGenes(
    params = params,
    x = 0.5, y = 2.25, width = 3, height = 0.5,
    just = c("left", "top"), default.units = "inches"
)

## Label genomic region
annoGenomeLabel(
    plot = genesPlot,
    x = 0.5, y = 2.8, just = c("left", "top"), default.units = "inches"
)

## Create and place mtcars boxplot
boxPlot <- ggplot(mtcars) +
    geom_boxplot(aes(gear, disp, group = gear))
plotGG(
    plot = boxPlot,
    x = 4, y = 0.5, width = 2.5, height = 2,
    just = c("left", "top"), default.units = "inches"
)

## Label panels
plotText(
    label = "A", fontsize = 16, fontface = "bold",
    x = 0.75, y = 0.5, just = "center", default.units = "inches"
)
plotText(
    label = "B", fontsize = 16, fontface = "bold",
    x = 3.75, y = 0.5, just = "center", default.units = "inches"
)

Not only does this make visualizations entirely reproducible with code, but it also makes it easy to change data ranges and aesthetics with simple pieces of code:

## Change colors while maintaining plot layout
hicPlot <- plotHicTriangle(
    data = IMR90_HiC_10kb,
    params = params,
    palette = colorRampPalette(c("white", "steel blue")),
    x = 0.5, y = 0.5, width = 3, height = 1.5,
    just = c("left", "top"), default.units = "inches"
)

genesPlot <- plotGenes(
    params = params,
    fill = c("grey", "grey"), fontcolor = c("black", "black"),
    x = 0.5, y = 2.25, width = 3, height = 0.5,
    just = c("left", "top"), default.units = "inches"
)

## Create a plotgardener page
pageCreate(
    width = 7, height = 3.5, default.units = "inches",
    xgrid = 0, ygrid = 0, showGuides = FALSE
)

## Define genomic region with `pgParams`
params <- pgParams(chrom = "chr21", 
                    chromstart = 28000000, chromend = 30300000,
                    assembly = "hg19")

## Plot Hi-C data
hicPlot <- plotHicTriangle(
    data = IMR90_HiC_10kb,
    params = params,
    palette = colorRampPalette(c("white", "steel blue")),
    x = 0.5, y = 0.5, width = 3, height = 1.5,
    just = c("left", "top"), default.units = "inches"
)

## Add color scale annotation
annoHeatmapLegend(
    plot = hicPlot,
    x = 3.5, y = 0.5, width = 0.12, height = 1,
    just = c("right", "top"), default.units = "inches"
)

## Plot gene track in same genomic region
genesPlot <- plotGenes(
    params = params,
    fill = c("grey", "grey"), fontcolor = c("black", "black"),
    x = 0.5, y = 2.25, width = 3, height = 0.5,
    just = c("left", "top"), default.units = "inches"
)

## Label genomic region
annoGenomeLabel(
    plot = genesPlot,
    x = 0.5, y = 2.8, just = c("left", "top"), default.units = "inches"
)

## Create and place mtcars boxplot
boxPlot <- ggplot(mtcars) +
    geom_boxplot(aes(gear, disp, group = gear))
plotGG(
    plot = boxPlot,
    x = 4, y = 0.5, width = 2.5, height = 2,
    just = c("left", "top"), default.units = "inches"
)

## Label panels
plotText(
    label = "A", fontsize = 16, fontface = "bold",
    x = 0.75, y = 0.5, just = "center", default.units = "inches"
)
plotText(
    label = "B", fontsize = 16, fontface = "bold",
    x = 3.75, y = 0.5, just = "center", default.units = "inches"
)

Utilizing `grid` graphics `viewports`

plotgardener achieves its functionality through grid graphics viewports, or defined graphical regions. A plotgardener page is defined by one large viewport with specified dimensions and units. Subsequent plots each have their own viewport that are placed on the larger page viewport. These viewports give users the power to specify the size and placement of each plot's container and clip data to precise axis measurements.