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

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

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
#>  [1] "MIR3125"      "RNASEH1-DT"   "LOC100506274" "MIR4757"      "LINC00570"   
#>  [6] "C2orf50"      "SLC66A3"      "SILC1"        "LRATD1"       "DDX1"        
#> [11] "LPIN1"        "ATP6V1C2"     "IAH1"         "TRIB2"        "GRHL1"       
#> [16] "HPCAL1"       "ID2"          "MSGN1"        "GEN1"         NA            
#> [21] "KCNF1"        "KCNS3"        "LOC400940"    "MYCN"         "TRAPPC12"    
#> [26] "CPSF3"        "SNTG2"        "ALLC"         "RPS7"         "RRM2"        
#> [31] "SOX11"        "TPO"          "MYT1L-AS1"    "VSNL1"        "COLEC11"     
#> [36] "KLF11"        "ASAP2"        "TAF1B"        "RSAD2"        "GREB1"       
#> [41] "RNF144A"      "SNORA80B"     "MIR4261"      "MIR4262"      "LINC01304"   
#> [46] "LOC100506474" "NT5C1B-RDH14" "MIR4429"      "PDIA6"        "MYCNOS"      
#> [51] "YWHAQ"        "CMPK2"        "MBOAT2"       "OSR1"         "E2F6"        
#> [56] "CYS1"         "MYT1L"        "NTSR2"        "RNASEH1"      "FLJ33534"    
#> [61] "LINC00298"    "LINC00299"    "GRASLND"      "LINC00487"    "ODC1"        
#> [66] "NBAS"         "ADI1"         "KIDINS220"    "RDH14"        "ADAM17"      
#> [71] "EIPR1"        "LINC01249"    "RAD51AP2"     "PXDN"         "SMC6"        
#> [76] "NOL10"        "CYRIA"        "ITGB1BP1"     "NT5C1B"       "ROCK2"

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
)

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.

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
)

Session Info

sessionInfo()
#> R version 4.2.0 (2022-04-22)
#> Platform: x86_64-apple-darwin17.0 (64-bit)
#> Running under: macOS Big Sur/Monterey 10.16
#> 
#> Matrix products: default
#> BLAS:   /Library/Frameworks/R.framework/Versions/4.2/Resources/lib/libRblas.0.dylib
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.2/Resources/lib/libRlapack.dylib
#> 
#> locale:
#> [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
#> 
#> attached base packages:
#> [1] stats4    grid      stats     graphics  grDevices utils     datasets 
#> [8] methods   base     
#> 
#> other attached packages:
#>  [1] org.Hs.eg.db_3.15.0                    
#>  [2] TxDb.Hsapiens.UCSC.hg19.knownGene_3.2.2
#>  [3] GenomicFeatures_1.48.0                 
#>  [4] AnnotationDbi_1.58.0                   
#>  [5] Biobase_2.56.0                         
#>  [6] GenomicRanges_1.48.0                   
#>  [7] GenomeInfoDb_1.32.0                    
#>  [8] IRanges_2.30.0                         
#>  [9] S4Vectors_0.34.0                       
#> [10] BiocGenerics_0.42.0                    
#> [11] plotgardenerData_1.1.0                 
#> [12] plotgardener_1.2.0                     
#> 
#> loaded via a namespace (and not attached):
#>  [1] bitops_1.0-7                matrixStats_0.62.0         
#>  [3] fs_1.5.2                    bit64_4.0.5                
#>  [5] filelock_1.0.2              progress_1.2.2             
#>  [7] httr_1.4.2                  RColorBrewer_1.1-3         
#>  [9] rprojroot_2.0.3             tools_4.2.0                
#> [11] bslib_0.3.1                 utf8_1.2.2                 
#> [13] R6_2.5.1                    DBI_1.1.2                  
#> [15] colorspace_2.0-3            prettyunits_1.1.1          
#> [17] tidyselect_1.1.2            bit_4.0.4                  
#> [19] curl_4.3.2                  compiler_4.2.0             
#> [21] textshaping_0.3.6           cli_3.3.0                  
#> [23] xml2_1.3.3                  desc_1.4.1                 
#> [25] DelayedArray_0.22.0         rtracklayer_1.56.0         
#> [27] sass_0.4.1                  scales_1.2.0               
#> [29] rappdirs_0.3.3              pkgdown_2.0.3              
#> [31] systemfonts_1.0.4           stringr_1.4.0              
#> [33] digest_0.6.29               Rsamtools_2.12.0           
#> [35] yulab.utils_0.0.4           rmarkdown_2.14             
#> [37] XVector_0.36.0              pkgconfig_2.0.3            
#> [39] htmltools_0.5.2             MatrixGenerics_1.8.0       
#> [41] highr_0.9                   dbplyr_2.1.1               
#> [43] fastmap_1.1.0               rlang_1.0.2                
#> [45] rstudioapi_0.13             RSQLite_2.2.12             
#> [47] gridGraphics_0.5-1          jquerylib_0.1.4            
#> [49] BiocIO_1.6.0                generics_0.1.2             
#> [51] jsonlite_1.8.0              BiocParallel_1.30.0        
#> [53] dplyr_1.0.9                 RCurl_1.98-1.6             
#> [55] magrittr_2.0.3              ggplotify_0.1.0            
#> [57] GenomeInfoDbData_1.2.8      Matrix_1.4-1               
#> [59] Rcpp_1.0.8.3                munsell_0.5.0              
#> [61] fansi_1.0.3                 lifecycle_1.0.1            
#> [63] stringi_1.7.6               yaml_2.3.5                 
#> [65] SummarizedExperiment_1.26.0 zlibbioc_1.42.0            
#> [67] BiocFileCache_2.4.0         blob_1.2.3                 
#> [69] parallel_4.2.0              crayon_1.5.1               
#> [71] lattice_0.20-45             Biostrings_2.64.0          
#> [73] hms_1.1.1                   KEGGREST_1.36.0            
#> [75] knitr_1.39                  pillar_1.7.0               
#> [77] rjson_0.2.21                biomaRt_2.52.0             
#> [79] strawr_0.0.9                XML_3.99-0.9               
#> [81] glue_1.6.2                  evaluate_0.15              
#> [83] data.table_1.14.2           png_0.1-7                  
#> [85] vctrs_0.4.1                 gtable_0.3.0               
#> [87] purrr_0.3.4                 assertthat_0.2.1           
#> [89] cachem_1.0.6                ggplot2_3.3.5              
#> [91] xfun_0.30                   restfulr_0.0.13            
#> [93] ragg_1.2.2                  tibble_3.1.6               
#> [95] GenomicAlignments_1.32.0    plyranges_1.16.0           
#> [97] memoise_2.0.1               ellipsis_0.3.2