Update to version 0.99.5

DESCRIPTION

@@ -1,15 +1,19 @@
 Package: EnhancedVolcano
 Type: Package
 Title: Publication-ready volcano plots with enhanced colouring and labeling
-Version: 0.99.4
+Version: 0.99.5
 Author: Kevin Blighe
 Maintainer: Kevin Blighe <kevin@clinicalbioinformatics.co.uk>
 Description: Volcano plots represent a useful way to visualise the results of differential expression analyses. Here, we present a highly-configurable function that produces publication-ready volcano plots. EnhancedVolcano will attempt to fit as many transcript names in the plot window as possible, thus avoiding 'clogging' up the plot with labels that could not otherwise have been read.
 License: GPL-3
-Imports:
+Depends:
+    R (>= 3.5.0),
     ggplot2,
-    ggrepel,
+    ggrepel
+Imports:
 Suggests:
+    RUnit,
+    BiocGenerics,
     knitr,
     DESeq2,
     pasilla,

EnhancedVolcano.Rmd

@@ -0,0 +1,357 @@
+---
+title: "Publication-ready volcano plots with enhanced colouring and labeling"
+author: "Kevin Blighe"
+date: "`r Sys.Date()`"
+package: "`r packageVersion('EnhancedVolcano')`"
+output:
+    rmarkdown::html_document:
+        highlight: pygments
+        toc: true
+        toc_float: true
+            collapsed: true
+            smooth_scroll: true
+        toc_depth: 2
+        fig_width: 5
+bibliography: library.bib
+vignette: >
+    %\VignetteIndexEntry{Publication-ready volcano plots with enhanced colouring and labeling}
+    %\VignetteEngine{knitr::rmarkdown}
+    %\VignetteEncoding{UTF-8}
+    %\usepackage[utf8]{inputenc}
+---
+
+# Introduction
+
+Volcano plots represent a useful way to visualise the results of differential
+expression analyses. Here, we present a highly-configurable function that
+produces publication-ready volcano plots [@EnhancedVolcano]. EnhancedVolcano
+will attempt to fit as many transcript names in the plot window as possible,
+thus avoiding 'clogging' up the plot with labels that could not otherwise
+have been read.
+
+
+```{r, echo=FALSE}
+
+    library(knitr)
+    opts_chunk$set(tidy = TRUE, message = FALSE, warning = FALSE)
+
+```
+
+# Installation
+
+## Download the package from Bioconductor.
+
+```{r getPackage, eval=FALSE}
+
+    if (!requireNamespace("BiocManager", quietly = TRUE))
+        install.packages("BiocManager")
+
+    BiocManager::install("EnhancedVolcano")
+
+```
+
+## Load the package into R session.
+
+```{r Load, message=FALSE}
+
+    library(EnhancedVolcano)
+
+```
+
+## Note: to install the development version, run:
+
+```{r getPackageDevel, eval=FALSE}
+
+    devtools::install_github("kevinblighe/EnhancedVolcano")
+
+```
+
+# Example data
+
+## Quick start
+
+Following data generated by tutorial of [RNA-seq workflow: gene-level exploratory analysis and differential expression](http://master.bioconductor.org/packages/release/workflows/vignettes/rnaseqGene/inst/doc/rnaseqGene.html):
+
+
+Load airway data:
+
+```{r}
+
+    source("https://bioconductor.org/biocLite.R")
+    biocLite("airway")
+    library(airway)
+
+    library(magrittr)
+
+    data("airway")
+    airway$dex %<>% relevel("untrt")
+
+```
+
+Conduct differential expression using DESeq2:
+
+```{r}
+
+    library("DESeq2")
+    dds <- DESeqDataSet(airway, design = ~ cell + dex)
+    dds <- DESeq(dds, betaPrior=FALSE)
+
+    res1 <- results(dds,
+        contrast = c("dex","trt","untrt"))
+    res1 <- lfcShrink(dds,
+        contrast = c("dex","trt","untrt"), res=res1)
+
+    res2 <- results(dds,
+        contrast = c("cell", "N061011", "N61311"))
+    res2 <- lfcShrink(dds,
+        contrast = c("cell", "N061011", "N61311"), res=res2)
+
+```
+
+### Example 1: plot the most basic volcano plot:
+
+```{r ex1, fig.height = 8, fig.width = 6, fig.cap = "Example 1: plot the most basic volcano plot"}
+
+    EnhancedVolcano(res1,
+        lab = rownames(res1),
+        x = "log2FoldChange",
+        y = "pvalue")
+```
+
+## Advanced features
+
+Virtually all things that you can imaginw are configurable with EnhancedVolcano, which allows you to quickly produce publication-ready volcano plots.
+
+### Example 2: modify cut-offs for log2FC and pvalue; add title; adjust point and label size:
+
+```{r ex2, fig.height = 8, fig.width = 6, fig.cap = "Example 2: modify cut-offs for log2FC and pvalue; add title; adjust point and label size"}
+
+    EnhancedVolcano(res2,
+        lab = rownames(res2),
+        x = "log2FoldChange",
+        y = "pvalue",
+        pCutoff = 10e-12,
+        FCcutoff = 1.5,
+        transcriptPointSize = 1.5,
+        transcriptLabSize = 3.0,
+        title = "N061011 versus N61311")
+
+```
+
+### Example 3: adjust colour and alpha for point shading:
+
+```{r ex3, fig.height = 8, fig.width = 6, fig.cap = "Example 3: adjust colour and alpha for point shading"}
+
+    EnhancedVolcano(res2,
+        lab = rownames(res2),
+        x = "log2FoldChange",
+        y = "pvalue",
+        pCutoff = 10e-12,
+        FCcutoff = 1.5,
+        transcriptPointSize = 1.5,
+        transcriptLabSize = 3.0,
+        title = "N061011 versus N61311",
+        col=c("black", "black", "black", "red3"),
+        colAlpha = 1)
+
+```
+
+### Example 4: adjust axis limits:
+
+```{r ex4, fig.height = 8, fig.width = 6, fig.cap = "Example 4: adjust axis limits"}
+
+    EnhancedVolcano(res2,
+        lab = rownames(res2),
+        x = "log2FoldChange",
+        y = "pvalue",
+        pCutoff = 10e-12,
+        FCcutoff = 1.5,
+        transcriptPointSize = 1.5,
+        transcriptLabSize = 3.0,
+        title = "N061011 versus N61311",
+        colAlpha = 1,
+        xlim = c(-8, 8),
+        ylim = c(0, -log10(10e-32)))
+
+```
+
+### Example 5: adjust cut-off lines:
+
+```{r ex5, fig.height = 8, fig.width = 6, fig.cap = "Example 5: adjust cut-off lines"}
+
+    EnhancedVolcano(res2,
+        lab = rownames(res2),
+        x = "log2FoldChange",
+        y = "pvalue",
+        pCutoff = 10e-12,
+        FCcutoff = 1.5,
+        transcriptPointSize = 1.5,
+        transcriptLabSize = 3.0,
+        title = "N061011 versus N61311",
+        colAlpha = 1,
+        xlim = c(-8, 8),
+        ylim = c(0, -log10(10e-32)),
+        cutoffLineType = "twodash",
+        cutoffLineCol = "red3",
+        cutoffLineWidth = 1.5)
+
+```
+
+### Example 6: adjust legend position, size, and text:
+
+```{r ex6, fig.height = 8, fig.width = 9, fig.cap = "Example 6: adjust legend position, size, and text"}
+
+    EnhancedVolcano(res2,
+        lab = rownames(res2),
+        x = "log2FoldChange",
+        y = "pvalue",
+        pCutoff = 10e-12,
+        FCcutoff = 1.5,
+        transcriptPointSize = 1.5,
+        transcriptLabSize = 3.0,
+        colAlpha = 1,
+        cutoffLineType = "twodash",
+        cutoffLineCol = "red4",
+        cutoffLineWidth = 1.0,
+        legend=c("NS","Log (base 2) fold-change","P value",
+            "P value & Log (base 2) fold-change"),
+        legendPosition = "right",
+        legendLabSize = 14,
+        legendIconSize = 5.0)
+
+```
+
+### Example 7: plot adjusted p-values:
+
+```{r ex7, fig.height = 8, fig.width = 6, fig.cap = "Example 7: plot adjusted p-values"}
+
+    EnhancedVolcano(res2,
+        lab = rownames(res2),
+        x = "log2FoldChange",
+        y = "padj",
+        xlab = bquote(~Log[2]~ "fold change"),
+        ylab = bquote(~-Log[10]~adjusted~italic(P)),
+        pCutoff = 0.0001,
+        FCcutoff = 1.0,
+        xlim=c(-6,6),
+        transcriptLabSize = 3.0,
+        colAlpha = 1,
+        legend=c("NS","Log2 FC","Adjusted p-value",
+            "Adjusted p-value & Log2 FC"),
+        legendPosition = "bottom",
+        legendLabSize = 10,
+        legendIconSize = 3.0)
+
+```
+
+### Example 8: fit more labels by adding connectors:
+
+```{r ex8, fig.height = 8, fig.width = 6.5, fig.cap = "Example 8: fit more labels by adding connectors"}
+
+    EnhancedVolcano(res2,
+        lab = rownames(res2),
+        x = "log2FoldChange",
+        y = "padj",
+        xlab = bquote(~Log[2]~ "fold change"),
+        ylab = bquote(~-Log[10]~adjusted~italic(P)),
+        pCutoff = 0.0001,
+        FCcutoff = 2.0,
+        xlim = c(-6,6),
+        transcriptLabSize = 3.0,
+        colAlpha = 1,
+        legend=c("NS","Log2 FC","Adjusted p-value",
+            "Adjusted p-value & Log2 FC"),
+        legendPosition = "bottom",
+        legendLabSize = 10,
+        legendIconSize = 3.0,
+        DrawConnectors = TRUE,
+        widthConnectors = 0.5,
+        colConnectors = "black")
+
+```
+
+### Example 9: only label key transcripts:
+
+```{r ex9, fig.height = 8, fig.width = 6, fig.cap = "Example 9: only label key transcripts"}
+
+    EnhancedVolcano(res2,
+        lab = rownames(res2),
+        x = "log2FoldChange",
+        y = "padj",
+        selectLab = c("ENSG00000106565","ENSG00000187758"),
+        xlab = bquote(~Log[2]~ "fold change"),
+        ylab = bquote(~-Log[10]~adjusted~italic(P)),
+        pCutoff = 0.0001,
+        FCcutoff = 2.0,
+        xlim = c(-6,6),
+        transcriptLabSize = 5.0,
+        colAlpha = 1,
+        legend=c("NS","Log2 FC","Adjusted p-value",
+            "Adjusted p-value & Log2 FC"),
+        legendPosition = "bottom",
+        legendLabSize = 10,
+        legendIconSize = 3.0)
+
+```
+
+### Example 10: plot multiple volcanos on the same page:
+
+```{r ex10, fig.height = 8, fig.width = 11, fig.cap = "Example 10: plot multiple volcanos on the same page"}
+
+    p1 <- EnhancedVolcano(res1,
+        lab = rownames(res1),
+        x = "log2FoldChange",
+        y = "pvalue",
+        pCutoff = 10e-24,
+        FCcutoff = 2.0,
+        transcriptLabSize = 2.0,
+        colAlpha = 1,
+        legendPosition = "bottom",
+        legendLabSize = 10,
+        legendIconSize = 3.0)
+
+    p2 <- EnhancedVolcano(res2,
+        lab = rownames(res2),
+        x = "log2FoldChange",
+        y = "padj",
+        selectLab = c("ENSG00000106565","ENSG00000187758"),
+        xlab = bquote(~Log[2]~ "fold change"),
+        ylab = bquote(~-Log[10]~adjusted~italic(P)),
+        pCutoff = 0.0001,
+        FCcutoff = 2.0,
+        xlim = c(-6,6),
+        transcriptLabSize = 5.0,
+        colAlpha = 1,
+        legend=c("NS","Log2 FC","Adjusted p-value",
+            "Adjusted p-value & Log2 FC"),
+        legendPosition = "bottom",
+        legendLabSize = 10,
+        legendIconSize = 3.0)
+
+
+    library(gridExtra)
+    library(grid)
+    grid.arrange(p1, p2, ncol=2, top="EnhancedVolcano")
+    grid.rect(gp=gpar(fill=NA))
+
+```
+
+
+# Acknowledgments
+
+The development of *EnhancedVolcano* has benefited from contributions and suggestions from:
+
+Sharmila Rana,
+[Myles Lewis](https://www.qmul.ac.uk/whri/people/academic-staff/items/lewismyles.html)
+
+# Session info
+
+```{r}
+
+sessionInfo()
+
+```
+
+# References
+
+[@EnhancedVolcano]

NAMESPACE

@@ -1,3 +1,6 @@
 export("EnhancedVolcano")
 
+import(ggplot2)
+import(ggrepel)
+
 importFrom(ggplot2, ggplot)