volcano3D

The volcano3D package enables exploration of probes differentially expressed between three groups. Its main purpose is for the visualisation of differentially expressed genes in a three-dimensional volcano plot. These plots can be converted to interactive visualisations using plotly.

This vignette covers the basic features of the package using a small example data set. To explore more extensive examples and view the interactive radial and volcano plots, see the extended vignette which explores a case study from the PEAC rheumatoid arthritis trial (Pathobiology of Early Arthritis Cohort). The methodology has been published in Lewis, Myles J., et al. Molecular portraits of early rheumatoid arthritis identify clinical and treatment response phenotypes. Cell reports 28.9 (2019): 2455-2470. (DOI: 10.1016/j.celrep.2019.07.091) with an interactive, searchable web tool available at https://peac.hpc.qmul.ac.uk. This was creating as an R Shiny app and deployed to the web using a server.

There are also supplementary vignettes with further information on:

• setting up the input pvalues data frame
• using the volcano3D package to create and deploy a shiny app

Getting Started

Prerequisites

• ggplot2
• ggpubr
• ggrepel
• plotly

Install from CRAN

install.packages("volcano3D")

Install from Github

library(devtools)
install_github("KatrionaGoldmann/volcano3D")

Load the package

library(volcano3D)

Dictionary

Variables used in this vignette:

Examples

This vignette uses a subset of the 500 most highly differentially expressed genes from the PEAC data to explore the package functions. This can be loaded using:

data("example_data")

Which contains:

• syn_example_rld - the log transformed expression data

• syn_example_p - the pvalues data frame containing differential expression statistics about each gene

• syn_example_meta which contains information about each sample.

For more information on how to create such objects see here.

Samples in this cohort fall into three pathotype groups:

kable(table(syn_example_meta$Pathotype), col.names = c("Pathotype", "Count"))

These will be used as the differential expression groups for the three-way analysis.

Creating Polar Coordinates

First, the differential expression can be mapped to polar coordinates using the polar_coords function, which has inputs:

This can be applied to the example data as below:

data("example_data")

syn_polar <- polar_coords(sampledata = syn_example_meta,
                          contrast = "Pathotype",
                          pvalues = syn_example_p,
                          expression = syn_example_rld,
                          p_col_suffix = "pvalue",
                          padj_col_suffix = "padj",
                          fc_col_suffix = "log2FoldChange",
                          multi_group_prefix = "LRT",
                          non_sig_name = "Not Significant",
                          significance_cutoff = 0.01,
                          label_column = NULL,
                          fc_cutoff = 0.1)

This creates an polar class object with slots for: sampledata, contrast, pvalues, multi_group_test, expression, polar and non_sig_name. The pvalues slot should now have at least two statistics for each comparison - pvalue and adjusted pvalue - and an optional logarithmic fold change statistic:

head(syn_polar@pvalues)

The sig column in syn_polar@polar allows us to determine relative differences in expression between groups (in this case pathotypes). The '+' indicates which pathotypes are significantly 'up' compared to others. For example:

• genes labelled 'Lymphoid+' are significantly up in Lymphoid vs Myeloid and Lymphoid vs Fibroid.

• genes up in two pathotypes such as 'Lymphoid+Myeloid+' are up in both Lymphoid and Myeloid, therefore Lymphoid vs Fibroid and Myeloid vs Fibroid are statistically significant.

• genes which show no significant difference between pathotypes are classed according to non_sig_name

This gives us:

setNames(data.frame(table(syn_polar@polar$sig)), c("Significance", "Frequency"))

Volcano Plots

If a fold change column was previously provided, the comparisons between pathotypes can be investigated using the volcano_trio function. This creates ggplot outputs:

syn_plots <- volcano_trio(polar = syn_polar,
                          sig_names = c("not significant","significant",
                                        "not significant","significant"),
                          colours = rep(c("grey60",  "slateblue1"), 2),
                          text_size = 9,
                          marker_size=1,
                          shared_legend_size = 0.9,
                          label_rows = c("SLAMF6", "BOC", "FMOD"),
                          fc_line = FALSE, 
                          share_axes = FALSE)

syn_plots$All

Radial Plots

The differential expression can now be visualised on an interactive radial plot using radial_plotly.

radial_plotly(polar = syn_polar, label_rows = c("SLAMF6", "GREM2", "FMOD"), 
              grid_colour="pink", axis_colour="blue") 

Unfortunately CRAN does not support interactive plotly in the vignette, but these can be viewed on the extended vignette. When interactive, it is possible to identify genes for future interrogation by hovering over certain markers.

Similarly a static ggplot image can be created using radial_ggplot:

radial_ggplot(polar = syn_polar,
              label_rows = c("SLAMF6", "FMOD", "GREM2"),
              marker_size = 2.3,
              legend_size = 10) +
  theme(legend.position = "right")

Boxplots

Any one specific probe can be interrogated using a boxplot to investigate differences between groups:

plot1 <- boxplot_trio(syn_polar,
                      value = "SLAMF6",
                      text_size = 7,
                      test = "polar_padj",
                      my_comparisons=list(c("Lymphoid", "Myeloid"),
                                          c("Lymphoid", "Fibroid")))

plot2 <- boxplot_trio(syn_polar,
                      value = "SLAMF6",
                      box_colours = c("violet", "gold2"),
                      levels_order = c("Lymphoid", "Fibroid"),
                      text_size = 7,
                      test = "polar_padj"
                      )

plot3 <- boxplot_trio(syn_polar,
                      value = "FMOD",
                      text_size = 7,
                      stat_size=2.5,
                      test = "polar_multi_padj",
                      levels_order = c("Lymphoid", "Myeloid", "Fibroid"),
                      box_colours = c("blue", "red", "green3"))

ggarrange(plot1, plot2, plot3, ncol=3)

Three Dimensional Volcano Plots

Lastly, the 3D volcano plot can be used to project differential gene expression onto cylindrical coordinates. Again, CRAN does not support WebGL for the interactive 3D plot, however this can be viewed in the extended vignette.

p <- volcano3D(syn_polar,
               label_rows = c("SLAMF6", "GREM2", "FMOD"),
               label_size = 10,
               xy_aspectratio = 1,
               z_aspectratio = 0.9, 
               plot_height = 700)
p

Saving Plotly Plots

Static Images

There are a few ways to save plotly plots as static images. Firstly plotly offers a download button ( ) in the figure mode bar (appears top right). By default this saves images as png, however it is possible to convert to svg, jpeg or webp using:

p %>% plotly::config(toImageButtonOptions = list(format = "svg"))

Alternatively, if orca command-line utility is installed, this can also be used to save plotly images. To install follow the instructions here.

orca(p, "./volcano_3d_synovium.svg", format = "svg")

Interactive HTML

The full plotly objects can be saved to HTML by converting them to widgets and saving with the htmlwidgets package:

htmlwidgets::saveWidget(as_widget(p), "volcano3D.html")

Citation

volcano3D was developed by the bioinformatics team at the Experimental Medicine & Rheumatology department and Centre for Translational Bioinformatics at Queen Mary University London.

If you use this package please cite as:

citation("volcano3D")

## 
## To cite package 'volcano3D' in publications use:
## 
##   Katriona Goldmann and Myles Lewis (2020). volcano3D: Interactive
##   Plotting of Three-Way Differential Expression Analysis.
##   https://katrionagoldmann.github.io/volcano3D/index.html,
##   https://github.com/KatrionaGoldmann/volcano3D.
## 
## A BibTeX entry for LaTeX users is
## 
##   @Manual{,
##     title = {volcano3D: Interactive Plotting of Three-Way Differential Expression
## Analysis},
##     author = {Katriona Goldmann and Myles Lewis},
##     year = {2020},
##     note = {https://katrionagoldmann.github.io/volcano3D/index.html, https://github.com/KatrionaGoldmann/volcano3D},
##   }

or using:

Lewis, Myles J., et al. Molecular portraits of early rheumatoid arthritis identify clinical and treatment response phenotypes. Cell reports 28.9 (2019): 2455-2470.