plotgardener meta functions enhance the plotgardener user experience by providing simple methods to display various genomic assembly data, simplify plotgardener code, and construct plotgardener objects. Functions in this category include:

  • genomes and defaultPackages

Simple functions to display the strings of available default genomic builds and the genomic annotation packages associated with these builds in plotgardener functions.

genomes()
#> bosTau8
#> bosTau9
#> canFam3
#> ce6
#> ce11
#> danRer10
#> danRer11
#> dm3
#> dm6
#> galGal4
#> galGal5
#> galGal6
#> hg18
#> hg19
#> hg38
#> mm9
#> mm10
#> rheMac3
#> rheMac8
#> rheMac10
#> panTro5
#> panTro6
#> rn4
#> rn5
#> rn6
#> sacCer2
#> sacCer3
#> susScr3
#> susScr11
defaultPackages("hg19")
#> 'data.frame':    1 obs. of  6 variables:
#>  $ Genome        : chr "hg19"
#>  $ TxDb          : chr "TxDb.Hsapiens.UCSC.hg19.knownGene"
#>  $ OrgDb         : chr "org.Hs.eg.db"
#>  $ gene.id.column: chr "ENTREZID"
#>  $ display.column: chr "SYMBOL"
#>  $ BSgenome      : chr "BSgenome.Hsapiens.UCSC.hg19"
  • assembly

A constructor to make custom combinations of genomic annotation packages for use in plotgardener functions through the assembly parameter.

  • pgParams

A constructor to capture sets of parameters to be shared across multiple function calls. pgParams objects can hold any argument from any plotgardener function. Most often, pgParams objects are used to store a common genomic region and common x-placement coordinate information. For a detailed example using the pgParams object, refer to the vignette Plotting Multi-omic Data.

  • colorby and mapColors

The colorby constructor allows us to color the data elements in plotgardener plots by various data features. These features can be a numerical range, like some kind of score value, or categorical values, like positive or negative strand. The colorby object is constructed by specifying the name of the data column to color by, an optional color palette function, and an optional range for numerical values. If not specified, plotgardener will use the RColorBrewer “YlGnBl” palette for mapping numerical data and the “Pairs” palette for qualitative data.

For example, if we revist the BED plot above, IMR90_ChIP_CTCF_reads has an additional strand column for each BED element:

data("IMR90_ChIP_CTCF_reads")
head(IMR90_ChIP_CTCF_reads)
#>          chrom    start      end strand
#> 15554862 chr21 28000052 28000088      -
#> 15554863 chr21 28000092 28000128      -
#> 15554864 chr21 28000162 28000198      -
#> 15554865 chr21 28000251 28000287      +
#> 15554866 chr21 28000335 28000371      -
#> 15554867 chr21 28000500 28000536      +

Thus, we can use the colorby constructor to color BED elements by positive or negative strand. The strand column will be converted to a factor with a - level and + level. These values will be mapped to our input palette:

set.seed(nrow(IMR90_ChIP_CTCF_reads))
plotRanges(
    data = IMR90_ChIP_CTCF_reads,
    chrom = "chr21", chromstart = 29073000, chromend = 29074000,
    assembly = "hg19",
    order = "random",
    fill = colorby("strand", palette = 
                       colorRampPalette(c("#7ecdbb", "#37a7db"))),
    x = 0.5, y = 0.25, width = 6.5, height = 4.25,
    just = c("left", "top"), default.units = "inches"
)

To further control the order of color mapping, we can set our categorical colorby column as a factor with our own order of levels before plotting:

data("IMR90_ChIP_CTCF_reads")
IMR90_ChIP_CTCF_reads$strand <- factor(IMR90_ChIP_CTCF_reads$strand, levels = c("+", "-"))
head(IMR90_ChIP_CTCF_reads$strand)
#> [1] - - - + - +
#> Levels: + -

Now we’ve set the + level as our first level, so our palette will map colors in the opposite order from before:

In this example, we will color BEDPE arches by a range of numerical values we will add as a length column:

data("IMR90_DNAloops_pairs")
IMR90_DNAloops_pairs$length <- (IMR90_DNAloops_pairs$start2 - IMR90_DNAloops_pairs$start1) / 1000
head(IMR90_DNAloops_pairs$length)
#> [1]   65 1960 2100  850 1200 1485

Now we can set fill as a colorby object to color the BEDPE length column by:

bedpePlot <- plotPairsArches(
    data = IMR90_DNAloops_pairs,
    chrom = "chr21", chromstart = 27900000, chromend = 30700000,
    assembly = "hg19",
    fill = colorby("length", 
                   palette = colorRampPalette(c("dodgerblue2", "firebrick2"))),
    linecolor = "fill",
    archHeight = IMR90_DNAloops_pairs$length / max(IMR90_DNAloops_pairs$length),
    alpha = 1,
    x = 0.25, y = 0.25, width = 7, height = 1.5,
    just = c("left", "top"),
    default.units = "inches"
)

And now since we have numbers mapped to colors, we can use annoHeatmapLegend() with our arches object to add a legend for the colorby we performed:

annoHeatmapLegend(
    plot = bedpePlot, fontcolor = "black",
    x = 7.0, y = 0.25,
    width = 0.10, height = 1, fontsize = 10
)

If users wish to map values to a color palette before passing them into a plotgardener function, they can use mapColors:

colors <- mapColors(vector = IMR90_DNAloops_pairs$length,
             palette = colorRampPalette(c("dodgerblue2", "firebrick2")))

bedpePlot <- plotPairsArches(
    data = IMR90_DNAloops_pairs,
    chrom = "chr21", chromstart = 27900000, chromend = 30700000,
    assembly = "hg19",
    fill = colors,
    linecolor = "fill",
    archHeight = heights, alpha = 1,
    x = 0.25, y = 0.25, width = 7, height = 1.5,
    just = c("left", "top"),
    default.units = "inches"
)

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] grid      stats     graphics  grDevices utils     datasets  methods  
#> [8] base     
#> 
#> other attached packages:
#> [1] plotgardenerData_1.2.0 plotgardener_1.4.1    
#> 
#> loaded via a namespace (and not attached):
#>  [1] MatrixGenerics_1.8.1        Biobase_2.56.0             
#>  [3] sass_0.4.2                  jsonlite_1.8.0             
#>  [5] bslib_0.4.0                 assertthat_0.2.1           
#>  [7] highr_0.9                   stats4_4.2.0               
#>  [9] yulab.utils_0.0.5           GenomeInfoDbData_1.2.8     
#> [11] Rsamtools_2.12.0            yaml_2.3.6                 
#> [13] pillar_1.8.1                lattice_0.20-45            
#> [15] glue_1.6.2                  digest_0.6.30              
#> [17] GenomicRanges_1.48.0        RColorBrewer_1.1-3         
#> [19] XVector_0.36.0              colorspace_2.0-3           
#> [21] htmltools_0.5.3             Matrix_1.4-1               
#> [23] strawr_0.0.9                XML_3.99-0.12              
#> [25] pkgconfig_2.0.3             zlibbioc_1.42.0            
#> [27] purrr_0.3.5                 scales_1.2.1               
#> [29] ggplotify_0.1.0             BiocParallel_1.30.4        
#> [31] tibble_3.1.8                generics_0.1.3             
#> [33] IRanges_2.30.1              ggplot2_3.3.6              
#> [35] cachem_1.0.6                SummarizedExperiment_1.26.1
#> [37] BiocGenerics_0.42.0         cli_3.4.1                  
#> [39] magrittr_2.0.3              crayon_1.5.2               
#> [41] memoise_2.0.1               evaluate_0.15              
#> [43] fs_1.5.2                    fansi_1.0.3                
#> [45] textshaping_0.3.6           tools_4.2.0                
#> [47] data.table_1.14.4           BiocIO_1.6.0               
#> [49] lifecycle_1.0.3             matrixStats_0.62.0         
#> [51] stringr_1.4.0               plyranges_1.16.0           
#> [53] S4Vectors_0.34.0            munsell_0.5.0              
#> [55] DelayedArray_0.22.0         Biostrings_2.64.1          
#> [57] compiler_4.2.0              pkgdown_2.0.6              
#> [59] jquerylib_0.1.4             GenomeInfoDb_1.32.4        
#> [61] gridGraphics_0.5-1          systemfonts_1.0.4          
#> [63] rlang_1.0.6                 RCurl_1.98-1.9             
#> [65] rstudioapi_0.13             rjson_0.2.21               
#> [67] bitops_1.0-7                rmarkdown_2.14             
#> [69] restfulr_0.0.15             gtable_0.3.1               
#> [71] codetools_0.2-18            DBI_1.1.3                  
#> [73] curl_4.3.3                  R6_2.5.1                   
#> [75] GenomicAlignments_1.32.1    knitr_1.39                 
#> [77] dplyr_1.0.10                rtracklayer_1.56.1         
#> [79] fastmap_1.1.0               utf8_1.2.2                 
#> [81] rprojroot_2.0.3             ragg_1.2.2                 
#> [83] desc_1.4.1                  stringi_1.7.6              
#> [85] parallel_4.2.0              Rcpp_1.0.9                 
#> [87] vctrs_0.5.0                 tidyselect_1.2.0           
#> [89] xfun_0.31