---
title: Plot Aesthetics
output: rmarkdown::html_vignette
vignette: >
    %\VignetteIndexEntry{Plot Aesthetics}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    fig.align = "center",
    message = FALSE,
    warning = FALSE
)
library(plotgardener)
library(grid)
library(plotgardenerData)
```

`plotgardener` plots are extremely customizable in appearance. In this article 
we will outline some of the major aesthetic customizations, including general 
features and specific plot type customizations.

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

# `gpar` and common plot customizations

The most common types of customizations are inherited from `grid` `gpar` 
options. If a function accepts `...`, this usually refers to `gpar` options 
that are not explicity listed as parameters in the function documentation. 
General valid parameters include:

+------------------:+:--------------------------------------------------------+
| **alpha**         | Alpha channel for transparency (number between 0 and 1).|
+-------------------+---------------------------------------------------------+
| **fill**          | Fill color.                                             |
+-------------------+---------------------------------------------------------+
|  **linecolor**    | Line color.                                             |
+-------------------+---------------------------------------------------------+
| **lty**           | Line type. (0=blank, 1=solid, 2=dashed, 3=dotted,       |
|                   | 4=dotdash, 5=longdash, 6=twodash).                      |
+-------------------+---------------------------------------------------------+
| **lwd**           | Line width.                                             |
+-------------------+---------------------------------------------------------+
| **lineend**       | Line end style (round, butt, square).                   |
+-------------------+---------------------------------------------------------+
| **linejoin**      | Line join style (round, mitre, bevel).                  |
+-------------------+---------------------------------------------------------+
| **linemitre**     | Line mitre limit (number greater than 1).               |
+-------------------+---------------------------------------------------------+
| **fontsize**      | The size of text, in points.                            |
+-------------------+---------------------------------------------------------+
| **fontcolor**     | Text color.                                             |
+-------------------+---------------------------------------------------------+
| **fontface**      | The font face (plain, bold, italic, bold.italic,        |
|                   | oblique).                                               |
+-------------------+---------------------------------------------------------+
| **fontfamily**    | The font family.                                        |
+-------------------+---------------------------------------------------------+
| **cex**           | Scaling multiplier applied to symbols.                  |
+-------------------+---------------------------------------------------------+
| **pch**           | Plotting character, or symbol (integer codes range      |
|                   | from 0 to 25).                                          |
+-------------------+---------------------------------------------------------+

Additional fonts for the `fontfamily` argument can be imported with the 
packages `extrafont` and `showtext`. This makes it possible to incorporate 
special fonts like Times New Roman, Arial, etc. into `plotgardener` figures.

# Backgrounds and baselines

By default, `plotgardener` plots have transparent backgrounds when placed on a 
`page`. In many functions, this background color can be changed with the 
parameter `bg`.

```{r eval=FALSE, echo=TRUE}
plotGenes(
    chrom = "chr8", chromstart = 1000000, chromend = 2000000,
    assembly = "hg19",
    bg = "#f6f6f6",
    x = 0.5, y = 0.5, width = 2, height = 1, just = c("left", "top"),
    default.units = "inches"
)
```


```{r aes_01, eval=TRUE, echo=FALSE, message=FALSE, fig.width=5, fig.height=3}
library(TxDb.Hsapiens.UCSC.hg19.knownGene)
library(org.Hs.eg.db)
pageCreate(
    width = 3, height = 2, default.units = "inches",
    showGuides = FALSE, xgrid = 0, ygrid = 0
)
genomicRegion <- pgParams(
    chrom = "chr8",
    chromstart = 1000000, chromend = 2000000,
    assembly = "hg19"
)
genesPlot <- plotGenes(
    params = genomicRegion, bg = "#f6f6f6",
    x = 0.5, y = 0.5, width = 2, height = 1,
    just = c("left", "top"), default.units = "inches"
)
```
This makes it easy to clearly see the precise dimensional boundaries of 
`plotgardener` plots.

Some plots also benefit from baselines to quickly show where y = 0. This can 
aid in data interpretation and guide plot annotation placement. Baselines can
be plotted in selective plots with `baseline = TRUE`.

```{r eval=FALSE, echo=TRUE}
plotRanges(
    data = IMR90_ChIP_CTCF_reads,
    chrom = "chr21", chromstart = 29073000, chromend = 29074000,
    assembly = "hg19",
    fill = c("#7ecdbb", "#37a7db"),
    baseline = TRUE, baseline.color = "black",
    x = 0.5, y = 0.25, width = 6.5, height = 4.25,
    just = c("left", "top"), default.units = "inches"
)
```

```{r aes_02, echo=FALSE, fig.height=6, fig.width=9.5}
data("IMR90_ChIP_CTCF_reads")
pageCreate(
    width = 7.5, height = 5, default.units = "inches",
    showGuides = FALSE, xgrid = 0, ygrid = 0
)

pileupPlot <- plotRanges(
    data = IMR90_ChIP_CTCF_reads,
    chrom = "chr21", chromstart = 29073000, chromend = 29074000,
    assembly = "hg19",
    fill = c("#7ecdbb", "#37a7db"),
    x = 0.5, y = 0.25, width = 6.5, height = 4.25,
    baseline = TRUE, baseline.color = "black",
    just = c("left", "top"), default.units = "inches"
)
```

# Gene and transcript plot aesthetics

`plotgardener` provides many useful features specific for enhancing gene and 
transcript visualizations:

## Labels

Since `plotgardener` utilizes `TxDb` objects, `orgDb` objects, and internal 
citation information, `plotgardener` has access to numerous gene and transcript 
identifiers and can customize annotation labels in a variety of ways. 

By default, `plotgardener` will rank gene labels according to citation number to 
prevent label overcrowding. However, we can provide our own list of 
prioritized genes to label in a plot. For example, if we plot the hg19 genes 
in the region `chr2:1000000-20000000`, our plot will show these labels:

```{r aes_07, eval=TRUE, echo=TRUE, message=FALSE, fig.width=5, fig.height=1.5}
pageCreate(
    width = 5, height = 1.25,
    showGuides = FALSE, xgrid = 0, ygrid = 0
)
genePlot <- plotGenes(
    chrom = "chr2", chromstart = 1000000, chromend = 20000000,
    assembly = "hg19",
    x = 0.25, y = 0.25, width = 4.75, height = 1
)
```
Looking in the `genes` object, we can see that there were numerous genes 
that were not labeled.

```{r eval=TRUE, echo=TRUE}
genePlot$genes
```

If we were particularly interested in MIR3125, we could include this in 
the `geneOrder` parameter to prioritize its labeling:
```{r aes_08, echo=TRUE, fig.height=1.5, fig.width=5, message=FALSE}
pageCreate(
    width = 5, height = 1.25,
    showGuides = FALSE, xgrid = 0, ygrid = 0
)
genePlot <- plotGenes(
    chrom = "chr2", chromstart = 1000000, chromend = 20000000,
    assembly = "hg19",
    geneOrder = c("MIR3125"),
    x = 0.25, y = 0.25, width = 4.75, height = 1
)
```

Label IDs used in transcript plots can be customized through `assembly()` 
objects, and transcript label formatting can be changed through the `labels` 
parameter. For example, if we wish to display both transcript names and their 
associated gene names, we can set `labels = "both"`:

```{r aes_10, echo=TRUE, fig.height=6, fig.width=7}
pageCreate(
    width = 6, height = 5,
    showGuides = FALSE, xgrid = 0, ygrid = 0
)
transcriptPlot <- plotTranscripts(
    chrom = "chr2", chromstart = 1000000, chromend = 20000000,
    assembly = "hg19",
    labels = "both",
    x = 0.25, y = 0.25, width = 5.5, height = 4.5
)
```

## Highlighting genes by color

In addition to changing `fill` and `fontcolor` to change the colors of all 
genes in a plot, specific gene structures and their labels can be highlighted
in a different color with `geneHighlights`. If we revisit the `genes` plot
above, we can highlight RRM2 by creating a `data.frame` with "RRM2" in the 
first column and its highlight color in the second column:

```{r eval=TRUE, echo=TRUE, message=FALSE}
geneHighlights <- data.frame("geneName" = "RRM2", "color" = "steel blue")
```

We can then pass this into our `plotGenes()` call:

```{r aes_11, eval=TRUE, echo=TRUE, message=FALSE, fig.width=5, fig.height=1.5}
pageCreate(
    width = 5, height = 1.25,
    showGuides = FALSE, xgrid = 0, ygrid = 0
)
genePlot <- plotGenes(
    chrom = "chr2", chromstart = 1000000, chromend = 20000000,
    assembly = "hg19",
    geneHighlights = geneHighlights, geneBackground = "grey",
    x = 0.25, y = 0.25, width = 4.75, height = 1
)
```

Since `geneHighlights` is a `data.frame`, we can highlight multiple genes 
in different colors at once. For example, let's now highlight RRM2 in 
"steel blue" and PXDN in "red":

```{r aes_12, eval=TRUE, echo=TRUE, message=FALSE, fig.width=5, fig.height=1.5}
geneHighlights <- data.frame(
    "geneName" = c("RRM2", "PXDN"),
    "color" = c("steel blue", "red")
)

pageCreate(
    width = 5, height = 1.25,
    showGuides = FALSE, xgrid = 0, ygrid = 0
)
genePlot <- plotGenes(
    chrom = "chr2", chromstart = 1000000, chromend = 20000000,
    assembly = "hg19",
    geneHighlights = geneHighlights, geneBackground = "grey",
    x = 0.25, y = 0.25, width = 4.75, height = 1
)
```

## Highlighting transcripts by color

Similar to highlighting specific genes by colors, specific transcripts can
also be highlighted with `transcriptHighlights`. We can do this by either 
specifying transcripts by name or transcripts by their genes. Let's plot the 
transcripts of the gene track above and label the transcripts of LPIN1 and 
CMPK2:

```{r aes_13, eval=TRUE, echo=TRUE, message=FALSE, fig.width=7, fig.height=8}
transcriptHighlights <- data.frame(
    "gene" = c("LPIN1", "CMPK2"),
    "color" = c("steel blue", "red")
)

pageCreate(
    width = 6, height = 7,
    showGuides = FALSE
)
transcriptPlot <- plotTranscripts(
    chrom = "chr2", chromstart = 1000000, chromend = 20000000,
    assembly = "hg19",
    transcriptHighlights = transcriptHighlights,
    colorbyStrand = FALSE, fill = "grey",
    x = 0.25, y = 0.25, width = 5.5, height = 4.5
)
```

We can now see all transcripts of CMPK2 are colored in red and 
all transcripts of LPIN1 are colored in steel blue. If we knew the precise names
of these transcripts, we could also specify them for transcript highlighting
with the following `data.frame`:

```r
transcriptHighlights <- data.frame(
    "transcript" = c("uc010yjo.2", "uc002rbt.4", "uc010yjn.3", "uc002rbs.4",
                    "uc010yjm.3","uc010exi.1", "uc031rno.1", "uc010ewv.4",
                    "uc002qyo.4", "uc010yis.2", "uc002qyn.2"),
    "color" = c("steel blue", "steel blue", "steel blue", "steel blue",
                "steel blue", "steel blue", "red", "red", "red", "red", "red")
)
```

## Customizing transcripts by strand

To distinguish which strand a transcript belongs to, `plotTranscripts()` 
colors transcripts by strand with the parameter `colorbyStrand`. The first 
value in `fill` colors positive strand transcripts and the second `fill`
value colors negative strand transcripts. To further organize transcripts by 
strand, we can use `strandSplit` to separate transcript elements into groups 
of positive and negative strands:

```{r aes_14, echo=TRUE, fig.height=6, fig.width=7}
pageCreate(
    width = 6, height = 5,
    showGuides = FALSE, xgrid = 0, ygrid = 0
)
transcriptPlot <- plotTranscripts(
    chrom = "chr2", chromstart = 1000000, chromend = 20000000,
    assembly = "hg19",
    strandSplit = TRUE,
    x = 0.25, y = 0.25, width = 5.5, height = 4.5
)
```

Now all our positive strand transcripts are grouped together above the 
group of negative strand transcripts.

# Hi-C plot customizations

`plotgardener` includes many types of customizations for Hi-C plots. `plotgardener` 
provides 3 different Hi-C plotting functions based on the desired plot shape:

- `plotHicSquare()`: Plots a square, symmetrical Hi-C plot with genomic 
coordinates along both the x- and y-axes.
    
- `plotHicTriangle()`: Plots a triangular Hi-C plot where the genome 
region falls along the base of the triangle.
    
- `plotHicRectangle()`: Plots a triangular Hi-C plot with additional data 
filling the surrounding regions to form a rectangle.

```{r aes_15, echo=FALSE, fig.height=3.9, fig.width=9.75, message=FALSE}
data("IMR90_HiC_10kb")

pageCreate(
    width = 7.1, height = 2.25, default.units = "inches",
    showGuides = FALSE, xgrid = 0, ygrid = 0
)
params <- pgParams(
    chrom = "chr21", chromstart = 28950000, chromend = 29800000,
    assembly = "hg19", resolution = 10000
)

hicPlot_square <- plotHicSquare(
    data = IMR90_HiC_10kb, params = params,
    zrange = c(0, 70),
    x = 0.25, y = 0.25,
    width = 1.6, height = 1.6
)
annoGenomeLabel(
    plot = hicPlot_square, fontsize = 8,
    x = 0.25, y = 1.9, scale = "Kb"
)
annoGenomeLabel(
    plot = hicPlot_square, axis = "y", fontsize = 8,
    x = 0.20, y = 0.25, scale = "Kb",
    just = c("right", "top")
)
hicPlot_triangle <- plotHicTriangle(
    data = IMR90_HiC_10kb, params = params,
    zrange = c(0, 70),
    x = 2.1, y = 1.85,
    width = 2.25, height = 2,
    just = c("left", "bottom")
)
annoGenomeLabel(
    plot = hicPlot_triangle, fontsize = 8,
    x = 2.1, y = 1.9, scale = "Kb"
)
hicPlot_rectangle <- plotHicRectangle(
    data = IMR90_HiC_10kb, params = params,
    zrange = c(0, 70),
    x = 4.6, y = 1.85,
    width = 2.25, height = 1.125,
    just = c("left", "bottom")
)
annoGenomeLabel(
    plot = hicPlot_rectangle, fontsize = 8,
    x = 4.6, y = 1.9, scale = "Kb"
)
```  

All Hi-C plot types can use different color palettes, and colors can be 
linearly or log-scaled with the `colorTrans` parameter.  

`hicSquare` plots can be further customized to include two datasets in 
one plot. Instead of plotting both symmetrical halves of the plot, we can set 
one dataset as `half = "top"` and the other dataset as `half = "bottom"`:

```{r aes_16, echo=TRUE, fig.height=4.25, fig.width=5.25, message=FALSE}
data("GM12878_HiC_10kb")
data("IMR90_HiC_10kb")

pageCreate(
    width = 3.25, height = 3.25, default.units = "inches",
    showGuides = FALSE, xgrid = 0, ygrid = 0
)
params <- pgParams(
    chrom = "chr21", chromstart = 28000000, chromend = 30300000,
    assembly = "hg19", resolution = 10000,
    x = 0.25, width = 2.75, just = c("left", "top"), default.units = "inches"
)


hicPlot_top <- plotHicSquare(
    data = GM12878_HiC_10kb, params = params,
    zrange = c(0, 200),
    half = "top",
    y = 0.25, height = 2.75
)
hicPlot_bottom <- plotHicSquare(
    data = IMR90_HiC_10kb, params = params,
    zrange = c(0, 70),
    half = "bottom",
    y = 0.25, height = 2.75
)
```

# Session Info
```{r}
sessionInfo()
```
