plotgardener is modular and separates plotting and
annotating into two different categories of functions. To specify which
plot to annotate within an annotation function, each annotation function
has a plot parameter that accepts plotgardener
plot objects. This will facilitate in inheriting genomic region and plot
location information. In this article we will go through some of the
major types of annotations used to create accurate and informative
plotgardener plots.
All the data included in this article can be found in the
supplementary package plotgardenerData.
Genome labels
Genome labels are some of the most important annotations for giving
context to the genomic region of data. annoGenomeLabel()
can add genome labels with various customizations.
Genome labels can be shown at three different basepair scales (Mb,
Kb, and bp) depending on the size of the region and the desired accuracy
of the start and end labels. In the genomic region
chr21:28000000-30300000 we can use a Mb scale:
data("IMR90_HiC_10kb")
pageCreate(
width = 3, height = 3.25, default.units = "inches",
showGuides = FALSE, xgrid = 0, ygrid = 0
)
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"
)
annoGenomeLabel(
plot = hicPlot, scale = "Mb",
x = 0.25, y = 2.76
)
If we use a more specific genomic region like
chr21:28255554-29354665, the Mb scale will be rounded and
indicated with an approximation sign:
#> Warning: Start label is rounded.
#> Warning: End label is rounded.
Thus, it makes more sense to use the bp scale for ultimate accuracy:
data("IMR90_HiC_10kb")
pageCreate(
width = 3, height = 3.25, default.units = "inches",
showGuides = FALSE, xgrid = 0, ygrid = 0
)
hicPlot <- plotHicSquare(
data = IMR90_HiC_10kb,
chrom = "chr21", chromstart = 28255554, chromend = 29354665,
assembly = "hg19",
x = 0.25, y = 0.25, width = 2.5, height = 2.5, default.units = "inches"
)
annoGenomeLabel(
plot = hicPlot, scale = "bp",
x = 0.25, y = 2.76
)
If our genomic region is small enough, annoGenomeLabel()
can also be used to display the nucleotide sequence of that region.
Similar to IGV, annoGenomeLabel() will first represent
nucleotides as colored boxes:
At even finer scales, annoGenomeLabel() will then
represent nucleotides with colored letters:
In the specific case of square Hi-C plots (hicSquare
objects), annoGenomeLabel() can annotate the genome label
along the y-axis:
data("IMR90_HiC_10kb")
pageCreate(
width = 3.25, height = 3, default.units = "inches",
showGuides = FALSE, xgrid = 0, ygrid = 0
)
hicPlot <- plotHicSquare(
data = IMR90_HiC_10kb,
chrom = "chr21", chromstart = 28000000, chromend = 30300000,
assembly = "hg19",
x = 0.5, y = 0.25, width = 2.5, height = 2.5, default.units = "inches"
)
annoGenomeLabel(
plot = hicPlot, scale = "Mb",
axis = "y",
x = 0.5, y = 0.25,
just = c("right", "top")
)
Plot axes
In addition to genomic axes, it is also common to annotate standard x
and y-axes for measures of scale. This functionality is provided by the
annoXaxis() and annoYaxis() functions. For
example, a Manhattan plot requires a y-axis to indicate the range of
p-values:
library("TxDb.Hsapiens.UCSC.hg19.knownGene")
data("hg19_insulin_GWAS")
pageCreate(
width = 7.5, height = 2.75, default.units = "inches",
showGuides = FALSE, xgrid = 0, ygrid = 0
)
manhattanPlot <- plotManhattan(
data = hg19_insulin_GWAS, assembly = "hg19",
fill = c("grey", "#37a7db"),
sigLine = TRUE,
col = "grey", lty = 2, range = c(0, 14),
x = 0.5, y = 0.25, width = 6.5, height = 2,
just = c("left", "top"),
default.units = "inches"
)
annoGenomeLabel(
plot = manhattanPlot, x = 0.5, y = 2.25, fontsize = 8,
just = c("left", "top"), default.units = "inches"
)
plotText(
label = "Chromosome", fontsize = 8,
x = 3.75, y = 2.45, just = "center", default.units = "inches"
)
## Annotate y-axis
annoYaxis(
plot = manhattanPlot, at = c(0, 2, 4, 6, 8, 10, 12, 14),
axisLine = TRUE, fontsize = 8
)
## Plot y-axis label
plotText(
label = "-log10(p-value)", x = 0.15, y = 1.25, rot = 90,
fontsize = 8, fontface = "bold", just = "center",
default.units = "inches"
)
annoXaxis() and annoYaxis() have similar
usages and customizations.
Heatmap legends
Heatmap-style plots with numbers translated to a palette of colors
require a specific type of legend. This legend can be plotted with
annoHeatmapLegend() in both vertical and horizontal
orientations. Genomic plots that typically require this annotation are
Hi-C plots made with plotHicRectangle(),
plotHicSquare(), or plotHicTriangle().
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",
x = 0.25, width = 2.75, just = c("left", "top"), default.units = "inches"
)
hicPlot <- plotHicSquare(
data = IMR90_HiC_10kb, params = params,
zrange = c(0, 70), resolution = 10000,
y = 0.25, height = 2.75
)
## Annotate Hi-C heatmap legend
annoHeatmapLegend(
plot = hicPlot, fontsize = 7,
orientation = "v",
x = 0.125, y = 0.25,
width = 0.07, height = 0.5, just = c("left", "top"),
default.units = "inches"
)
annoHeatmapLegend(
plot = hicPlot, fontsize = 7,
orientation = "h",
x = 3, y = 3.055,
width = 0.5, height = 0.07, just = c("right", "top"),
default.units = "inches"
)
Hi-C pixels and domains
It is possible to annotate the pixels on a Hi-C plot with provided BEDPE data. Pixels can be annotated with boxes, circles, or squares.
data("IMR90_HiC_10kb")
data("IMR90_DNAloops_pairs")
pageCreate(
width = 3.25, height = 3.24, default.units = "inches",
showGuides = FALSE, xgrid = 0, ygrid = 0
)
hicPlot <- plotHicSquare(
data = IMR90_HiC_10kb, resolution = 10000, zrange = c(0, 70),
chrom = "chr21", chromstart = 28000000, chromend = 30300000,
assembly = "hg19",
x = 0.25, y = 0.25, width = 2.75, height = 2.75,
just = c("left", "top"),
default.units = "inches"
)
## Annotate pixels
pixels <- annoPixels(
plot = hicPlot, data = IMR90_DNAloops_pairs, type = "box",
half = "top"
)
If we want to annotate one pixel of interest, we can subset our BEDPE
data and annoPixels() will only annotate the specified
pixels:
data("IMR90_HiC_10kb")
data("IMR90_DNAloops_pairs")
## Subset BEDPE data
IMR90_DNAloops_pairs <- IMR90_DNAloops_pairs[which(IMR90_DNAloops_pairs$start1 == 28220000 &
IMR90_DNAloops_pairs$start2 == 29070000), ]
pageCreate(
width = 3.25, height = 3.24, default.units = "inches",
showGuides = FALSE, xgrid = 0, ygrid = 0
)
hicPlot <- plotHicSquare(
data = IMR90_HiC_10kb, resolution = 10000, zrange = c(0, 70),
chrom = "chr21", chromstart = 28000000, chromend = 30300000,
x = 0.25, y = 0.25, width = 2.75, height = 2.75,
just = c("left", "top"),
default.units = "inches"
)
## Annotate pixel
pixels <- annoPixels(
plot = hicPlot, data = IMR90_DNAloops_pairs, type = "arrow",
half = "bottom", shift = 12
)
For genomic ranges of domain data, we can annotate Hi-C domains with
annoDomains(). For example, if we want to annotate the
following domains
domains <- GRanges("chr21",
ranges = IRanges(
start = c(28210000, 29085000, 29430000, 29700000),
end = c(29085000, 29430000, 29700000, 30125000)
)
)in this Hi-C plot:
We would use a similar workflow to how we annotated Hi-C pixels:
pageCreate(
width = 3.25, height = 3.24, default.units = "inches",
showGuides = FALSE, xgrid = 0, ygrid = 0
)
hicPlot <- plotHicSquare(
data = IMR90_HiC_10kb, resolution = 10000, zrange = c(0, 70),
chrom = "chr21", chromstart = 28000000, chromend = 30300000,
x = 0.25, y = 0.25, width = 2.75, height = 2.75,
just = c("left", "top"),
default.units = "inches"
)
## Annotate domains
domainAnno <- annoDomains(
plot = hicPlot, data = domains,
half = "bottom", linecolor = "red"
)
annoGenomeLabel(
plot = hicPlot,
x = 0.25, y = 3.01
)
We can either annotate single domains or multiple domains at once
depending on the data input.
Genomic region highlights and zooms
The last category of annotations that is often used in plotting genomic data is highlighting and zooming. Many figures benefit from providing a broader context of data and then highlighting a smaller genomic region to show data at a finer scale. In this example, we will plot an ideogram and highlight and zoom in on a genomic region of interest to see the signal track data in that region.
First we can plot our ideogram:
library(AnnotationHub)
library(TxDb.Hsapiens.UCSC.hg19.knownGene)
pageCreate(
width = 6.25, height = 2.25, default.units = "inches",
showGuides = FALSE, xgrid = 0, ygrid = 0
)
ideogramPlot <- plotIdeogram(
chrom = "chr21", assembly = "hg19",
orientation = "h",
x = 0.25, y = 0.5, width = 5.75, height = 0.3, just = "left"
)
We can then use annoHighlight() to highlight our genomic
region of interest (chr21:28000000-30300000) with a box of
our desired height:
region <- pgParams(chrom = "chr21", chromstart = 28000000, chromend = 30300000)
annoHighlight(
plot = ideogramPlot, params = region,
fill = "red",
y = 0.25, height = 0.5, just = c("left", "top"), default.units = "inches"
)
To make it clearer that we are zooming in on a genomic region, we can
then use annoZoomLines() to add zoom lines from the genomic
region we highlighted:
annoZoomLines(
plot = ideogramPlot, params = region,
y0 = 0.75, x1 = c(0.25, 6), y1 = 1.25, default.units = "inches"
)
Finally, we can add our zoomed-in signal track data within the zoom lines:
Session Info
sessionInfo()
#> R version 4.3.2 (2023-10-31)
#> Platform: x86_64-apple-darwin20 (64-bit)
#> Running under: macOS Sonoma 14.2.1
#>
#> Matrix products: default
#> BLAS: /Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/lib/libRblas.0.dylib
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/lib/libRlapack.dylib; LAPACK version 3.11.0
#>
#> locale:
#> [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
#>
#> time zone: America/New_York
#> tzcode source: internal
#>
#> attached base packages:
#> [1] stats4 grid stats graphics grDevices utils datasets
#> [8] methods base
#>
#> other attached packages:
#> [1] AnnotationHub_3.10.0
#> [2] BiocFileCache_2.10.1
#> [3] dbplyr_2.5.0
#> [4] BSgenome.Hsapiens.UCSC.hg19_1.4.3
#> [5] BSgenome_1.70.2
#> [6] rtracklayer_1.62.0
#> [7] BiocIO_1.12.0
#> [8] Biostrings_2.70.3
#> [9] XVector_0.42.0
#> [10] org.Hs.eg.db_3.18.0
#> [11] TxDb.Hsapiens.UCSC.hg19.knownGene_3.2.2
#> [12] GenomicFeatures_1.54.4
#> [13] AnnotationDbi_1.64.1
#> [14] Biobase_2.62.0
#> [15] plotgardenerData_1.8.0
#> [16] GenomicRanges_1.54.1
#> [17] GenomeInfoDb_1.38.8
#> [18] IRanges_2.36.0
#> [19] S4Vectors_0.40.2
#> [20] BiocGenerics_0.48.1
#> [21] plotgardener_1.8.2
#>
#> loaded via a namespace (and not attached):
#> [1] RColorBrewer_1.1-3 strawr_0.0.91
#> [3] rstudioapi_0.16.0 jsonlite_1.8.8
#> [5] magrittr_2.0.3 rmarkdown_2.26
#> [7] fs_1.6.3 zlibbioc_1.48.2
#> [9] ragg_1.3.0 vctrs_0.6.5
#> [11] memoise_2.0.1 Rsamtools_2.18.0
#> [13] RCurl_1.98-1.14 htmltools_0.5.8
#> [15] S4Arrays_1.2.1 progress_1.2.3
#> [17] curl_5.2.1 SparseArray_1.2.4
#> [19] gridGraphics_0.5-1 sass_0.4.9
#> [21] bslib_0.7.0 desc_1.4.3
#> [23] cachem_1.0.8 GenomicAlignments_1.38.2
#> [25] mime_0.12 lifecycle_1.0.4
#> [27] pkgconfig_2.0.3 Matrix_1.6-5
#> [29] R6_2.5.1 fastmap_1.1.1
#> [31] GenomeInfoDbData_1.2.11 MatrixGenerics_1.14.0
#> [33] shiny_1.8.1 digest_0.6.35
#> [35] colorspace_2.1-0 textshaping_0.3.7
#> [37] RSQLite_2.3.5 filelock_1.0.3
#> [39] fansi_1.0.6 httr_1.4.7
#> [41] abind_1.4-5 compiler_4.3.2
#> [43] bit64_4.0.5 withr_3.0.0
#> [45] BiocParallel_1.36.0 DBI_1.2.2
#> [47] highr_0.10 biomaRt_2.58.2
#> [49] rappdirs_0.3.3 DelayedArray_0.28.0
#> [51] rjson_0.2.21 tools_4.3.2
#> [53] interactiveDisplayBase_1.40.0 httpuv_1.6.15
#> [55] glue_1.7.0 restfulr_0.0.15
#> [57] promises_1.2.1 generics_0.1.3
#> [59] gtable_0.3.4 data.table_1.15.2
#> [61] hms_1.1.3 xml2_1.3.6
#> [63] utf8_1.2.4 BiocVersion_3.18.1
#> [65] pillar_1.9.0 stringr_1.5.1
#> [67] yulab.utils_0.1.4 later_1.3.2
#> [69] dplyr_1.1.4 lattice_0.22-6
#> [71] bit_4.0.5 tidyselect_1.2.1
#> [73] knitr_1.45 SummarizedExperiment_1.32.0
#> [75] xfun_0.43 matrixStats_1.2.0
#> [77] stringi_1.8.3 yaml_2.3.8
#> [79] evaluate_0.23 codetools_0.2-19
#> [81] tibble_3.2.1 BiocManager_1.30.22
#> [83] ggplotify_0.1.2 cli_3.6.2
#> [85] xtable_1.8-4 systemfonts_1.0.6
#> [87] munsell_0.5.0 jquerylib_0.1.4
#> [89] Rcpp_1.0.12 png_0.1-8
#> [91] XML_3.99-0.16.1 parallel_4.3.2
#> [93] pkgdown_2.0.7 ggplot2_3.5.0
#> [95] blob_1.2.4 prettyunits_1.2.0
#> [97] plyranges_1.22.0 bitops_1.0-7
#> [99] scales_1.3.0 purrr_1.0.2
#> [101] crayon_1.5.2 rlang_1.1.3
#> [103] KEGGREST_1.42.0