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

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.

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

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.

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

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:

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.

genePlot$genes

If we were particularly interested in MIR3125, we could include this in the geneOrder parameter to prioritize its labeling:

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

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:

geneHighlights <- data.frame("geneName" = "RRM2", "color" = "steel blue")

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

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

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:

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:

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:

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.

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

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
)