In sahirbhatnagar/manhattan: Interactive Q-Q and Manhattan Plots Using 'plotly.js'

library(plotly)
#library(manhattanly)
library(knitr)
knitr::opts_chunk$set(echo = TRUE, 
                      tidy = FALSE, 
                      cache = FALSE, 
                      warning = FALSE,
                      message = FALSE)#,
                      # dpi = 60)
                      #comment = "#>")
#knitr::opts_knit$set(eval.after = 'fig.cap')

Author: Sahir Bhatnagar ([e-mail])

Notes:

• This vignette was built with R markdown and knitr. The source code for this vignette can be found here.

---

Introduction

Manhattan, Q-Q and volcano 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 a 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 viewer pane, R Markdown documents, in Shiny 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 by Stephen Turner and the plotly.js 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.

---

---

Installation

You can install manhattanly from CRAN:

install.packages("manhattanly")

Alternatively, you can install the development version of manhattanly from GitHub with:

install.packages("devtools")
devtools::install_github("sahirbhatnagar/manhattanly", build_vignettes = TRUE)

---

---

Quick Start

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:

# load the manhattanly library
library(manhattanly)

head(HapMap)

dim(HapMap)

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:

manhattanly(HapMap, 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.

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

qqly(HapMap, 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).

---

You can also make a volcano plot which by default, highlights the points greater than the default genomewideline and effect_size_line arguments (See help(volcanoly) for a full list of options):

volcanoly(HapMap, snp = "SNP", gene = "GENE")

---

---

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):

manhattanly(HapMap, snp = "SNP", gene = "GENE", highlight = significantSNP)

---

---

More annotations

You can add up to 4 annotations. In the following plot we add the snp, gene, the distance to the nearest gene and the effect size:

manhattanly(HapMap, snp = "SNP", gene = "GENE",
            annotation1 = "DISTANCE", annotation2 = "EFFECTSIZE",
            highlight = significantSNP)

---

---

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:

library(magrittr)

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

# get the x and y coordinates from the pre-processed data
plotData <- manhattanr(HapMap, 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).

---

---

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 in three steps.

---

Step 1: Signup for a free plotly account

Create a free plotly account here. 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:

Sys.setenv("plotly_username"="your_plotly_username")
Sys.setenv("plotly_api_key"="your_api_key")

---

Step 3: Publish your graphs to plotly with plotly_POST

library(plotly)
# p is the interactive manhattan plot we saved earlier
plotly_POST(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.

---

---

Dynamic Documents with knitr and R Markdown

R Markdown 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 and qq 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:

```r
# plotly library needs to be loaded
library(plotly)
manhattanly(HapMap, snp = "SNP", gene = "GENE")
```

---

---

Data Pre-Processing

The manhattanly package splits up the data pre-processing from the rendering of the plot object (inspired by the heatmaply package by Tal Galili). These are done by the manhattanr and qqr and functions:

# 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 (we omit the plot here for the sake of size of the rendered vignette):

manhattanly(manhattanrObject)

---

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

# 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"]])

---

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

qqrObject <- qqr(HapMap)
str(qqrObject)
head(qqrObject[["data"]])

This qqrObject which is of class qqr can also be passed to the qqly function:

qqly(qqrObject)

Volcano Plots

By default, the points greater than the default genomewideline and effect_size_line arguments are highlighted. The defaults are genomewideline = -log10(1e-5) and effect_size_line = c(-1,1). The effect_size_line argument must be a numeric vector of length 2 and the first argument must be smaller than the second. To highlight more points, you simply need to change those thresholds:

volcanoly(HapMap, snp = "SNP", genomewideline = -log10(1e-2), effect_size_line = c(-0.5, 0.5))

Note that in order to highlight points, the volcanoly function requires an identifier for each point given by the snp argument. If the snp argument is left blank, then no highlighting will be done.

---

Set either of the genomewideline and effect_size_line arguments to FALSE to remove that threshold:

volcanoly(HapMap, snp = "SNP",  genomewideline = -log10(1e-2), effect_size_line = FALSE)

---

Instead of automatic highlighting, you can specify the points you want to highlight using the highlight argument:

volcanoly(HapMap, snp = "SNP",  highlight = significantSNP)

---

Finally, to remove highlighting altogether while keeping the threshold lines set highlight = FALSE :

volcanoly(HapMap, snp = "SNP", highlight = FALSE)

The snp argument is stil necessary however.

---

Similar to the manhattanr and qqr functions, there is a volcanor function which is the pre-pocessing step and creates an object of class volcanor:

volcanorObject <- volcanor(HapMap, snp = "SNP")
str(volcanorObject)
head(volcanorObject[["data"]])

---

This volcanorObject which is of class volcanor can also be passed to the volcanoly function:

volcanoly(volcanorObject)

sahirbhatnagar/manhattan documentation built on May 1, 2021, 10 p.m.