manhattanly_full.Rmd

---
title: "Interactive Q-Q and Manhattan Plots Using Plotly.js"
author: "Sahir Bhatnagar"
date: "`r Sys.Date()`"
output:
  html_document:
    number_sections: yes
    toc: true
    code_folding: show
editor_options: 
  chunk_output_type: console
---
<!--
%\VignetteEngine{knitr::rmarkdown}
%\VignetteIndexEntry{Interactive Q-Q and Manhattan Plots Using Plotly.js}
-->

```{r setup, include=FALSE, echo=TRUE, message=FALSE}
# library(plotly)
#library(manhattanly)
library(knitr)
options(rmarkdown.html_vignette.check_title = FALSE)
knitr::opts_chunk$set(echo = TRUE, 
                      eval=TRUE,
                      tidy = FALSE, 
                      cache = FALSE, 
                      warning = FALSE,
                      message = FALSE,
                      dpi = 60)
                      #comment = "#>")
#knitr::opts_knit$set(eval.after = 'fig.cap')
```

**Author**: [Sahir Bhatnagar](https://sahirbhatnagar.com/) (sahir.bhatnagar@gmail.com)


**Notes**:

* This vignette was built with `R markdown` and `knitr`. The source code for this vignette can be found [here](https://github.com/sahirbhatnagar/manhattanly/blob/master/vignettes/web_only/manhattanly_full.Rmd).

* In the interactive manhattan, qq and volcano plots below, we only use a subset (random sample of SNPs on chromosomes 4 to 7) of the `HapMap` data included in this package. This is to reduce the size of the compiled vignette.

<br>

# Introduction

[Manhattan](https://en.wikipedia.org/wiki/Manhattan_plot), [Q-Q](https://en.wikipedia.org/wiki/Q%E2%80%93Q_plot) and [volcano](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC154570/) plots are popular graphical methods for visualizing results from high-dimensional data analysis such as a (epi)genome wide asssociation study (GWAS or EWAS), in which p-values, Z-scores, test statistics are plotted on a scatter plot against their genomic position. Manhattan plots are used for visualizing
potential regions of interest in the genome that are associated with a phenotype. Q-Q plots tell us about the distributional assumptions of the observed test statistics. Volcano plots are the negative log10 p-values plotted against their effect size, odds ratio or log fold-change. They are used to identify clinically meaningful markers in genomic experiments, i.e., markers that are statistically significant and have an effect size greater than some threshold. 

Interactive manhattan, Q-Q and volcano plots allow the inspection of specific value (e.g. rs number or gene name) by hovering the mouse over a point, as well as zooming into a region of the genome (e.g. a chromosome) by dragging a rectangle around the relevant area.

This pacakge creates interactive Q-Q, manhattan and volcano plots that are usable from the R console, the [`RStudio`](https://www.rstudio.com/) viewer pane, [`R Markdown`](https://rmarkdown.rstudio.com/) documents, in [`Dash`](https://plotly.com/dash/) apps,   [`Shiny`](https://shiny.rstudio.com/) apps, embeddable in websites and can be exported as `.png` files. By hovering the mouse over a point, you can see annotation information such as the SNP identifier and GENE name. You can also drag a rectangle to
zoom in on a region of interest and then export the image as a `.png` file.

This work is based on the [`qqman`](https://github.com/stephenturner/qqman) R package and the [`plotly.js`](https://plotly.com/)
engine. It produces similar manhattan and Q-Q plots as the `qqman::manhattan` and `qqman::qq` functions; the main difference here is being able to interact with the plot, including extra annotation information and seamless integration with HTML.

<br><br>

# Installation

You can install `manhattanly` from CRAN:

```R
install.packages("manhattanly")
```


Alternatively, you can install the development version of `manhattanly` from [GitHub](https://github.com/sahirbhatnagar/manhattanly) with:

```R
if (!require("pacman")) install.packages("pacman")
pacman::p_load_gh("sahirbhatnagar/manhattanly")
```

<br><br>

# Quick Start

## Manhattan plot

The `manhattanly` package ships with an example dataset called `HapMap`. See `help(HapMap)` for more details about how this dataset was created. Here is what the `HapMap` dataset looks like:

```{r, message=TRUE, eval=TRUE}
# load the manhattanly library
library(manhattanly)
set.seed(12345)
HapMap.subset <- subset(HapMap, CHR %in% 4:7)
# for highlighting SNPs of interest
significantSNP <- sample(HapMap.subset$SNP, 20)
head(HapMap.subset)
dim(HapMap.subset)
```

The required columns to create a manhattan plot are the chromosome, base-pair position and p-value. By default, the `manhattanly` function assumes these columns are named `CHR`, `BP` and `P` (but these can be specified by the user if they are different)

Create an interactive manhattan plot using one command:
```{r, eval=TRUE}
manhattanly(HapMap.subset, snp = "SNP", gene = "GENE")
```

The arguments `snp = "SNP"` and `gene = "GENE"` specify that we want to add snp and gene information to each point. This information is found in the columns names `"SNP"` and `"GENE"` in the `HapMap` dataset. See `help(manhattanly)` for a full list of options.

## Q-Q plot

Similarly, we can create an interactive Q-Q plot using one command (See `help(qqly)` for a full list of options):

```{r}
qqly(HapMap.subset, snp = "SNP", gene = "GENE")
```

You can then save the plot as a `.png` file by clicking on the camera icon in the toolbar (which appears when you hover your mouse over it). 

## Volcano plot

You can also make a volcano plot which by default, highlights the points greater than the default `genomewideline` and `effect_size_line` arguments:

```{r, eval=TRUE}
volcanoly(HapMap.subset, snp = "SNP", gene = "GENE", effect_size = "EFFECTSIZE")
```

<br>


## Highlighting SNPs of Interest

We can also highlight SNPs of interest using the `highlight` argument. This package comes with a list of SNPs of interest called `significantSNP` (see `help(significantSNP)` for more details). To highlight these SNPs we simply pass this vector to the `highlight` argument (note that these SNPs need to be present in the `"SNP"` column of your data). We omit the plot here due to size constraints of the package on CRAN:

```{r, eval = TRUE}
manhattanly(HapMap.subset, snp = "SNP", gene = "GENE", highlight = significantSNP)
```


## More annotations

You can add up to 4 annotations. In the following manhattan plot we add the snp, gene, the distance to the nearest gene and the effect size. The same annotations can also be added to Q-Q and volcano plots:

```{r, eval = FALSE}
manhattanly(HapMap.subset, snp = "SNP", gene = "GENE",
            annotation1 = "DISTANCE", annotation2 = "EFFECTSIZE",
            highlight = significantSNP)
```


<br>


## Adding Text Annotations to the Plot

The annotations in the previous plots only appear when we hover the mouse over the point. Once we have identified a SNP, or a few SNPs of interest we want to explicitly show the annotation information and save the plot. The output of the `manhattanly` function is an object which can be further manipulated using the `%>%` operator from the `magrittr` package:

```{r}
library(magrittr)

p <- manhattanly(HapMap.subset, snp = "SNP", gene = "GENE",
            annotation1 = "DISTANCE", annotation2 = "EFFECTSIZE",
            highlight = significantSNP)

# get the x and y coordinates from the pre-processed data
plotData <- manhattanr(HapMap.subset, snp = "SNP", gene = "GENE")[["data"]]

# annotate the smallest p-value
annotate <- plotData[which.min(plotData$P),]

# x and y coordinates of SNP with smallest p-value
xc <- annotate$pos
yc <- annotate$logp

p %>% plotly::layout(annotations = list(
  list(x = xc, y = yc,
       text = paste0(annotate$SNP,"<br>","GENE: ",annotate$GENE),
       font = list(family = "serif", size = 10))))

```


You can then save the plot as a `.png` file by clicking on the camera icon in the toolbar (which appears when you hover your mouse over it). 


<br>


## Sharing your Plots 

By default, plotly for R runs locally in your web browser or in the R Studio viewer. It would be useful to be able to easily share these plot with for example, your collaborators or supervisor, especially in the during the exploratory data analysis stage of your project.

You can publish your charts to the web with [plotly's web service](https://plotly.com/) in three steps.

### Step 1: Signup for a free plotly account

Create a free plotly account [here](https://plotly.com/). A plotly account is required to publish charts online. It's free to get started, and you control the privacy of your charts.


### Step 2: Save your authentication credentials

Find your authentication API keys in your online settings. Set them in your R session with:

```{r, eval=FALSE, echo=TRUE}
Sys.setenv("plotly_username"="your_plotly_username")
Sys.setenv("plotly_api_key"="your_api_key")
```


### Step 3: Publish your graphs to plotly with `plotly::api_create()`

```{r, eval=FALSE}
library(plotly)
# p is the interactive manhattan plot we saved earlier
plotly::api_create(p, filename = "r-docs/manhattan", world_readable=TRUE)
```

* `filename` sets the name of the file inside your online plotly account.
* `world_readable` sets the privacy of your chart. If `TRUE`, the graph is publically viewable, if `FALSE`, only you can view it.


<br><br>

# Dynamic Documents with `knitr` and `R Markdown`

[`R Markdown`](https://rmarkdown.rstudio.com/) is a an `R` software package that allows the creation of dynamic documents, i.e., embed `R` code with text to create fully reproducible reports. Furthermore it allows easy creation of `HTML` reports without knowing how to code in `HTML` (such as this vignette). This means you can embed interactive manhattan, qq and volcano plots in `HTML` reports using the `manhattanly` package. For example, to embed the above manhattan plot I included the following code chunk in the `.Rmd` document:

<pre><code>```{r}
library(plotly)
manhattanly(subset(HapMap, CHR %in% 4:7), snp = "SNP", gene = "GENE")
```</code></pre>


# Details

## Data Pre-Processing

The `manhattanly` package splits up the data pre-processing from the rendering of the plot object (inspired by the [`heatmaply`](https://github.com/talgalili/heatmaply) package. These are done by the `manhattanr`, `qqr` and `volcanor` functions:

```{r}
# create an object of class `manhattanr`
manhattanrObject <- manhattanr(HapMap)

# whats in there
str(manhattanrObject)

# the data used for plotting is a data.frame
# this data.frame can be used with any graphics function such as in base R
# you do not need to use plotly
head(manhattanrObject[["data"]])
is.data.frame(manhattanrObject[["data"]])
```

This `manhattanrObject` which is of class `manhattanr` can also be passed to the `manhattanly` function:

```{r, eval=TRUE}
manhattanly(manhattanrObject)
```


## More annotations

We can specify more annotations in the data using the `snp`, `gene`, `annotation1` and `annotation2` arguments:

```{r}
# create an object of class `manhattanr`
manhattanrObject <- manhattanr(HapMap, snp = "SNP", gene = "GENE",
            annotation1 = "DISTANCE", annotation2 = "EFFECTSIZE")

# the annotation columns are now part of the data.frame
head(manhattanrObject[["data"]])
is.data.frame(manhattanrObject[["data"]])
```

## Q-Q plots

Similarly the data used for the Q-Q plot can be created using the `qqr` function:

```{r}
qqrObject <- qqr(HapMap)
str(qqrObject)
head(qqrObject[["data"]])
```

This `qqrObject` which is of class `qqr` can also be passed to the `qqly` function (we omit the plot here for the sake of size of the rendered vignette):

```{r, eval=TRUE}
qqly(qqrObject)
```


## Volcano plots

Similarly the data used for the volcanor plot can be created using the `volcanor` function:

```{r}
volcanorObject <- volcanor(HapMap, 
                        p = "P",
                        effect_size = "EFFECTSIZE",
                        snp = "SNP",
                        gene = "GENE")
str(volcanorObject)
head(volcanorObject[["data"]])
```

This can be directly passed to the `volcanoly` function, with additional arguments:

```{r, eval=TRUE}
volcanoly(volcanorObject, effect_size_line = c(-1, 0.5))
```