Introduction to plotgardener
Overview
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
- Reading functions:
Functions for quickly reading in large biological datasets. See Reading Data for plotgardener
- 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
- Annotation functions:
Enables users to add annotations to their plots, such as legends, axes, and scales. See Plot Annotations
- Meta functions:
Functions that display plotgardener properties or
operate on other plotgardener functions, or constructors
for plotgardener objects. See plotgardener
Meta Functions
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:
Data reading argument (
data)Genomic locus arguments (
chrom,chromstart,chromend,assembly)Placement arguments (
x,y,width,height,just,default.units, …) that define where each plot resides on apageAttribute 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
## 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
## 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
## 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
## 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:
- Create a
plotgardenercoordinate page withpageCreate().
- Provide values for the placement arguments (
x,y,width,height,just,default.units) in plotting functions and save the output of the plotting function.
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"
)
- Annotate
plotgardenerplot objects by passing them into theplotargument of annotation functions.
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.
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():
We can then either use the Export toggle in the RStudio plot panel, or save the plot within our R code as follows:
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
sessionInfo()
## R version 4.4.2 (2024-10-31)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.1 LTS
##
## Matrix products: default
## BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so; LAPACK version 3.12.0
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_US.UTF-8 LC_COLLATE=C
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## time zone: Etc/UTC
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats4 grid stats graphics grDevices utils datasets
## [8] methods base
##
## other attached packages:
## [1] org.Hs.eg.db_3.20.0
## [2] TxDb.Hsapiens.UCSC.hg19.knownGene_3.2.2
## [3] GenomicFeatures_1.59.1
## [4] AnnotationDbi_1.69.0
## [5] Biobase_2.67.0
## [6] GenomicRanges_1.59.1
## [7] GenomeInfoDb_1.43.1
## [8] IRanges_2.41.1
## [9] S4Vectors_0.45.2
## [10] BiocGenerics_0.53.3
## [11] generics_0.1.3
## [12] plotgardenerData_1.12.0
## [13] plotgardener_1.13.0
## [14] rmarkdown_2.29
##
## loaded via a namespace (and not attached):
## [1] tidyselect_1.2.1 blob_1.2.4
## [3] dplyr_1.1.4 Biostrings_2.75.1
## [5] bitops_1.0-9 fastmap_1.2.0
## [7] RCurl_1.98-1.16 GenomicAlignments_1.43.0
## [9] XML_3.99-0.17 digest_0.6.37
## [11] lifecycle_1.0.4 plyranges_1.27.0
## [13] KEGGREST_1.47.0 RSQLite_2.3.8
## [15] magrittr_2.0.3 compiler_4.4.2
## [17] rlang_1.1.4 sass_0.4.9
## [19] tools_4.4.2 utf8_1.2.4
## [21] yaml_2.3.10 data.table_1.16.2
## [23] rtracklayer_1.67.0 knitr_1.49
## [25] S4Arrays_1.7.1 bit_4.5.0
## [27] curl_6.0.1 DelayedArray_0.33.2
## [29] RColorBrewer_1.1-3 abind_1.4-8
## [31] BiocParallel_1.41.0 withr_3.0.2
## [33] purrr_1.0.2 sys_3.4.3
## [35] fansi_1.0.6 colorspace_2.1-1
## [37] Rhdf5lib_1.29.0 ggplot2_3.5.1
## [39] scales_1.3.0 SummarizedExperiment_1.37.0
## [41] cli_3.6.3 crayon_1.5.3
## [43] httr_1.4.7 rjson_0.2.23
## [45] DBI_1.2.3 cachem_1.1.0
## [47] rhdf5_2.51.0 zlibbioc_1.52.0
## [49] parallel_4.4.2 ggplotify_0.1.2
## [51] XVector_0.47.0 restfulr_0.0.15
## [53] matrixStats_1.4.1 yulab.utils_0.1.8
## [55] vctrs_0.6.5 Matrix_1.7-1
## [57] jsonlite_1.8.9 gridGraphics_0.5-1
## [59] bit64_4.5.2 maketools_1.3.1
## [61] strawr_0.0.92 jquerylib_0.1.4
## [63] glue_1.8.0 codetools_0.2-20
## [65] gtable_0.3.6 BiocIO_1.17.0
## [67] UCSC.utils_1.3.0 munsell_0.5.1
## [69] tibble_3.2.1 pillar_1.9.0
## [71] htmltools_0.5.8.1 rhdf5filters_1.19.0
## [73] GenomeInfoDbData_1.2.13 R6_2.5.1
## [75] evaluate_1.0.1 lattice_0.22-6
## [77] png_0.1-8 Rsamtools_2.23.0
## [79] memoise_2.0.1 bslib_0.8.0
## [81] Rcpp_1.0.13-1 SparseArray_1.7.2
## [83] xfun_0.49 fs_1.6.5
## [85] MatrixGenerics_1.19.0 buildtools_1.0.0
## [87] pkgconfig_2.0.3