---
title: Ideograms and Shapes
output: rmarkdown::html_vignette
vignette: >
    %\VignetteIndexEntry{Ideograms and Shapes}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    fig.align = "center",
    message = FALSE,
    warning = FALSE
)
library(plotgardener)
library(grid)
library(plotgardenerData)
```

Beyond providing functions for plotting and arranging various genomic 
datasets, `plotgardener` also gives users the functionality to plot other elements
within a `plotgardener` page layout:

## Ideograms

In addition to a genomic axis label, it can also be useful to include an 
ideogram representation of a chromosome to give a broader context of the 
location of genomic data. UCSC Giemsa stain cytoband information for various 
genomic assemblies is retrieved from `AnnotationHub` for default assemblies, 
but users can also provide their own Giemsa stain information if they desire.

Ideograms can be plotted both vertically and horizontally:
```{r ideogram_01, echo=TRUE, fig.height=5.25, fig.width=10.35, message=FALSE}
library(AnnotationHub)
library(TxDb.Hsapiens.UCSC.hg19.knownGene)
library(GenomeInfoDb)

## Get sizes of chromosomes to scale their sizes
tx_db <- TxDb.Hsapiens.UCSC.hg19.knownGene
chromSizes <- GenomeInfoDb::seqlengths(tx_db)
maxChromSize <- max(chromSizes)

pageCreate(
    width = 8.35, height = 4.25, default.units = "inches",
    showGuides = FALSE, xgrid = 0, ygrid = 0
)
xCoord <- 0.15
for (chr in c(paste0("chr", seq(1, 22)), "chrX", "chrY")) {
    height <- (4 * chromSizes[[chr]]) / maxChromSize
    plotIdeogram(
        chrom = chr, assembly = "hg19",
        orientation = "v",
        x = xCoord, y = 4,
        width = 0.2, height = height,
        just = "bottom"
    )
    plotText(
        label = gsub("chr", "", chr),
        x = xCoord, y = 4.1, fontsize = 10
    )
    xCoord <- xCoord + 0.35
}
```

```{r ideogram_02, echo=TRUE, fig.height=.5, fig.width=8.25, message=FALSE}
pageCreate(
    width = 6.25, height = 0.5, default.units = "inches",
    showGuides = FALSE, xgrid = 0, ygrid = 0
)

plotIdeogram(
    chrom = "chr1", assembly = "hg19",
    orientation = "h",
    x = 0.25, y = unit(0.25, "npc"), width = 5.75, height = 0.3
)
```

The cytobands can also be hidden if a more minimal ideogram is preferred:

```{r eval=FALSE, echo=TRUE, message=FALSE}
plotIdeogram(
    showBands = FALSE,
    chrom = "chr1", assembly = "hg19",
    orientation = "h",
    x = 0.25, y = unit(0.25, "npc"), width = 5.75, height = 0.3
)
```

```{r ideogram_03, echo=FALSE, fig.height=.5, fig.width=8.25, message=FALSE}
pageCreate(
    width = 6.25, height = 0.5, default.units = "inches",
    showGuides = FALSE, xgrid = 0, ygrid = 0
)

plotIdeogram(
    showBands = FALSE,
    chrom = "chr1", assembly = "hg19",
    orientation = "h",
    x = 0.25, y = unit(0.25, "npc"), width = 5.75, height = 0.3
)
```

To highlight a specific genomic region on an ideogram, see the 
article [Plot Annotations](annotations.html#genomic-region-highlights-and-zooms-1). 

## Images and basic shapes

`plotgardener` also allows users to plot images and basic shapes and elements to 
further enhance and customize plot layouts. The functions `plotCircle()`, 
`plotPolygon()`, `plotRaster()`, `plotRect()`, `plotSegments()`, 
and `plotText()` provide an intuitive way to plot basic `grid` `grobs` 
without requiring any knowledge of `grid` graphics.

For example, we can include `plotgardener`'s Gene the Gnome in our figures!:

```{r shapes, echo=TRUE, fig.height=7, fig.showtext=TRUE, fig.width=6}
library(png)
pg_type <- readPNG(system.file("images",
                        "pg-wordmark.png",
                        package = "plotgardener"))

gene_gnome <- readPNG(system.file("images",    
            "pg-gnome-hole-shadow.png",
            package = "plotgardener" ))

pageCreate(
    width = 5, height = 6, default.units = "inches",
    showGuides = FALSE, xgrid = 0, ygrid = 0
)
plotRaster(
    image = pg_type,
    x = 2.5, y = 0.25, width = 4, height = 1.5, just = "top"
)
plotRaster(
    image = gene_gnome,
    x = 2.5, y = 1, width = 3.5, height = 3.5, just = "top"
)
```

For more detailed usage of basic shape functions, see the function-specific 
reference examples with `?function()` (e.g. `?plotCircle()`).

## Other grob objects

We saw how to add `ggplots` and `ComplexHeatmaps` to `plotgardener` layouts 
in the vignette 
[Incorporating ggplots and other `grid`-based Bioconductor visualizations"](incorporating_ggplots.html) 
with the `plotGG()` function. Beyond customizing the coordinates and dimensions 
of `ggplots` and `grid`-based Bioconductor visualizations, `plotGG()` can also 
be used to incorporate other `grob` and `gtable` objects. Thus, `plotgardener` 
allows us to easily mix and arrange most kinds of plot objects for ultimate 
customization.

## Session Info
```{r}
sessionInfo()
```
