---
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

```{=html}
<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](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 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](https://phanstiellab.github.io/plotgardener/articles/guides/plotgardener_page.html#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()`:

```{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()
```

**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!

# Session Info

```{r}
sessionInfo()
```