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

knitr::opts_chunk$set(
    fig.align = "center",
    fig.width = 3,
    fig.height = 3,
    collapse = TRUE,
    warning = FALSE,
    message = FALSE
)
library(grid)
library(plotgardener)
library(plotgardenerData)

Overview

```{=html}

`plotgardener` is a coordinate-based, genomic visualization package for R. Using
`grid` graphics, `plotgardener` empowers users to programmatically and flexibly
generate multi-panel figures. Tailored for genomics for a variety of genomic
assemblies, `plotgardener` allows users to visualize large, complex genomic
datasets while providing exquisite control over the arrangement of plots.

`plotgardener` functions can be grouped into the following categories:

- **Page layout functions:**

Functions for creating `plotgardener` page layouts, drawing, showing, and hiding
guides, as well as placing plots on the page. See [The plotgardener
Page](https://phanstiellab.github.io/plotgardener/articles/guides/plotgardener_page.html)

- **Reading functions:**

Functions for quickly reading in large biological datasets. See [Reading Data
for plotgardener](https://phanstiellab.github.io/plotgardener/articles/guides/reading_data_for_plotgardener.html)

- **Plotting functions:**

Contains genomic plotting functions, functions for placing `ggplots` and `base`
plots, as well as functions for drawing simple shapes. See [Plotting Multi-omic
Data](https://phanstiellab.github.io/plotgardener/articles/guides/plotting_multiomic_data.html)

- **Annotation functions:**

Enables users to add annotations to their plots, such as legends, axes, and
scales. See [Plot Annotations](https://phanstiellab.github.io/plotgardener/articles/guides/annotations.html)

- **Meta functions:**

Functions that display `plotgardener` properties or operate on other
`plotgardener` functions, or constructors for `plotgardener` objects. See
[plotgardener Meta Functions](https://phanstiellab.github.io/plotgardener/articles/guides/plotgardener_meta_functions.html)

This vignette provides a quick start guide for utilizing `plotgardener`. For
in-depth demonstrations of `plotgardener`'s key features, see the additional
articles. For detailed usage of each function, see the function-specific
reference examples with `?function()` (e.g. `?plotPairs()`).

All the data included in this vignette can be found in the supplementary package
`plotgardenerData`.

# Quick plotting

`plotgardener` plotting functions contain 4 types of arguments:

1. Data reading argument (`data`)

2. Genomic locus arguments (`chrom`, `chromstart`, `chromend`, `assembly`)

3. Placement arguments (`x`, `y`, `width`, `height`, `just`, `default.units`,
...) that define where each plot resides on a `page`

4. Attribute arguments that affect the data being plotted or the style of the
plot (`norm`, `fill`, `fontcolor`, ...) that vary between functions

The quickest way to plot data is to omit the placement arguments. This will
generate a `plotgardener` plot that fills up the entire graphics window and
cannot be annotated. **These plots are only meant to be used for quick**
**genomic data inspection and not as final `plotgardener` plots.** The only
arguments that are required are the data arguments and locus arguments. The
examples below show how to quickly plot different types of genomic data with
plot defaults and included data types. To use your own data, replace the `data`
argument with either a path to the file or an R object as described above.

## Hi-C matrices

```r
## Load plotgardener
library(plotgardener)

## Load example Hi-C data
library(plotgardenerData)
data("IMR90_HiC_10kb")

## Quick plot Hi-C data
plotHicSquare(
data = IMR90_HiC_10kb,
chrom = "chr21", chromstart = 28000000, chromend = 30300000,
assembly = "hg19"
)

Signal tracks

## Load plotgardener
library(plotgardener)

## Load example signal data
library(plotgardenerData)
data("IMR90_ChIP_H3K27ac_signal")

## Quick plot signal data
plotSignal(
    data = IMR90_ChIP_H3K27ac_signal,
    chrom = "chr21", chromstart = 28000000, chromend = 30300000,
    assembly = "hg19"
)

Gene tracks

## Load plotgardener
library(plotgardener)

## Load hg19 genomic annotation packages
library(TxDb.Hsapiens.UCSC.hg19.knownGene)
library(org.Hs.eg.db)

## Quick plot genes
plotGenes(
    assembly = "hg19",
    chrom = "chr21", chromstart = 28000000, chromend = 30300000
)

GWAS Manhattan plots

## Load plotgardener
library(plotgardener)

## Load hg19 genomic annotation packages
library(TxDb.Hsapiens.UCSC.hg19.knownGene)

## Load example GWAS data
library(plotgardenerData)
data("hg19_insulin_GWAS")

## Quick plot GWAS data
plotManhattan(
    data = hg19_insulin_GWAS, 
    assembly = "hg19",
    fill = c("steel blue", "grey"),
    ymax = 1.1, cex = 0.20
)

Plotting and annotating on the `plotgardener` page

To build complex, multi-panel plotgardener figures with annotations, we must:

Create a plotgardener coordinate page with pageCreate().

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

Provide values for the placement arguments (x, y, width, height, just, default.units) in plotting functions and save the output of the plotting function.

data("IMR90_HiC_10kb")
hicPlot <- plotHicSquare(
    data = IMR90_HiC_10kb,
    chrom = "chr21", chromstart = 28000000, chromend = 30300000,
    assembly = "hg19",
    x = 0.25, y = 0.25, width = 2.5, height = 2.5, default.units = "inches"
)

pageCreate(width = 3.25, height = 3.25, default.units = "inches")
data("IMR90_HiC_10kb")
hicPlot <- plotHicSquare(
    data = IMR90_HiC_10kb,
    chrom = "chr21", chromstart = 28000000, chromend = 30300000,
    assembly = "hg19",
    x = 0.25, y = 0.25, width = 2.5, height = 2.5, default.units = "inches"
)

Annotate plotgardener plot objects by passing them into the plot argument of annotation functions.

annoHeatmapLegend(
    plot = hicPlot,
    x = 2.85, y = 0.25, width = 0.1, height = 1.25, default.units = "inches"
)

annoGenomeLabel(
    plot = hicPlot,
    x = 0.25, y = 2.75, width = 2.5, height = 0.25, default.units = "inches"
)

pageCreate(width = 3.25, height = 3.25, default.units = "inches")
data("IMR90_HiC_10kb")
hicPlot <- plotHicSquare(
    data = IMR90_HiC_10kb,
    chrom = "chr21", chromstart = 28000000, chromend = 30300000,
    assembly = "hg19",
    x = 0.25, y = 0.25, width = 2.5, height = 2.5, default.units = "inches"
)
annoHeatmapLegend(
    plot = hicPlot,
    x = 2.85, y = 0.25, width = 0.1, height = 1.25, default.units = "inches"
)

annoGenomeLabel(
    plot = hicPlot,
    x = 0.25, y = 2.75, width = 2.5, height = 0.25, default.units = "inches"
)

For more information about how to place plots and annotations on a plotgardener page, check out the section Working with plot objects.

Exporting plots

When a plotgardener plot is ready to be saved and exported, we can first remove all page guides that were made with pageCreate():

pageGuideHide()

pageCreate(
    width = 3.25, height = 3.25, default.units = "inches",
    xgrid = 0, ygrid = 0, showGuides = FALSE
)
data("IMR90_HiC_10kb")
hicPlot <- plotHicSquare(
    data = IMR90_HiC_10kb,
    chrom = "chr21", chromstart = 28000000, chromend = 30300000,
    assembly = "hg19",
    x = 0.25, y = 0.25, width = 2.5, height = 2.5, default.units = "inches"
)
annoHeatmapLegend(
    plot = hicPlot,
    x = 2.85, y = 0.25, width = 0.1, height = 1.25, default.units = "inches"
)

annoGenomeLabel(
    plot = hicPlot,
    x = 0.25, y = 2.75, width = 2.5, height = 0.25, default.units = "inches"
)

We can then either use the Export toggle in the RStudio plot panel, or save the plot within our R code as follows:

pdf(width = 3.25, height = 3.25)

pageCreate(width = 3.25, height = 3.25, default.units = "inches")
data("IMR90_HiC_10kb")
hicPlot <- plotHicSquare(
    data = IMR90_HiC_10kb,
    chrom = "chr21", chromstart = 28000000, chromend = 30300000,
    assembly = "hg19",
    x = 0.25, y = 0.25, width = 2.5, height = 2.5, default.units = "inches"
)
annoHeatmapLegend(
    plot = hicPlot,
    x = 2.85, y = 0.25, width = 0.1, height = 1.25, default.units = "inches"
)

annoGenomeLabel(
    plot = hicPlot,
    x = 0.25, y = 2.75, width = 2.5, height = 0.25, default.units = "inches"
)
pageGuideHide()

dev.off()

Please note that due to the implementation of grid removal functions, using pageGuideHide within a pdf call will result in the rendering of a separate, new page with the plot guides removed. To avoid this artifact, hide guides in the pageCreate function call with showGuides = FALSE.

For more detailed usage and examples, please refer to the other available vignettes.

Future Directions

We still have many ideas to add for a second version of plotgardener including, but not limited to: grammar of graphics style plot arguments and plot building, templates, themes, and multi-plotting functions. If you have suggestions for ways we can improve plotgardener, please let us know!