---
title: Introduction to plotgardener
author: "Nicole Kramer, Eric S. Davis, Craig Wenger, Sarah Parker, \
Erika Deoudes, Michael Love, Douglas H. Phanstiel"
output:
rmarkdown::html_vignette:
md_extensions: +grid_tables
vignette: >
%\VignetteIndexEntry{Introduction to plotgardener}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include = FALSE}
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
<img src="../man/figures/pg-hex-text.png" align="right" width="140px"
style="padding-left:20px; background-color:white; border-color: transparent" />
`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](plotgardener_page.html)
- **Reading functions:**
Functions for quickly reading in large biological datasets.
See [Reading Data for plotgardener](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](plotting_multiomic_data.html)
- **Annotation functions:**
Enables users to add annotations to their plots, such as legends,
axes, and scales.
See [Plot Annotations](annotations.html)
- **Meta functions:**
Functions that display `plotgardener` properties or operate on other
`plotgardener` functions, or constructors for `plotgardener` objects.
See [plotgardener Meta Functions](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 hic_quickplot, eval=TRUE, echo=TRUE, message=FALSE}
## 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
```{r signal_quickplot, eval=TRUE, echo=TRUE, message=FALSE}
## 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
```{r gene_quickplot, eval=TRUE, echo=TRUE, message=FALSE}
## 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
```{r gwas_quickplot, eval=TRUE, echo=TRUE, message=FALSE}
## 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:
1. Create a `plotgardener` coordinate page with `pageCreate()`.
```{r quickpage, echo=TRUE, fig.height=4, fig.width=4, message=FALSE}
pageCreate(width = 3.25, height = 3.25, default.units = "inches")
```
2. Provide values for the placement arguments (`x`, `y`, `width`, `height`,
`just`, `default.units`) in plotting functions and save the output of the
plotting function.
```{r eval=FALSE, echo=TRUE, message=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"
)
```
```{r quickpageHic, echo=FALSE, fig.height=4, fig.width=4, message=FALSE}
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"
)
```
3. Annotate `plotgardener` plot objects by passing them into the `plot`
argument of annotation functions.
```{r eval=FALSE, echo=TRUE, message=FALSE}
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"
)
```
```{r quickpageAnno, echo=FALSE, fig.height=4, fig.width=4, message=FALSE}
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](introduction_to_plotgardener.html#working-with-plot-objects-1).
# 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()`:
```{r eval=FALSE, echo=TRUE, message=FALSE}
pageGuideHide()
```
```{r quickpageHide, echo=FALSE, fig.height=4, fig.width=4, message=FALSE}
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:
```{r eval=FALSE, echo=TRUE, message=FALSE}
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()
```
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!
# Session Info
```{r}
sessionInfo()
```