ggMAplot: A ggplot wrapper to produce MAplots.

In ATpoint/vizzy: vizzy - functions for data visualization

A ggplot wrapper to produce MAplots.

Description

A ggplot wrapper for MA-plots and Volcanos

Usage

ggMAplot(
  xval,
  yval,
  pval = NULL,
  labels = NULL,
  xval.thresh = NULL,
  yval.thresh = 0,
  pval.thresh = 0.05,
  col.base = "grey50",
  col.up = "firebrick",
  col.down = "darkblue",
  point.size = 2,
  point.alpha = 0.75,
  xlab = NULL,
  ylab = NULL,
  xlim = NULL,
  ylim = NULL,
  Up = "Up",
  Down = "Down",
  NonSig = "NonSig",
  title = waiver(),
  subtitle = waiver(),
  x.ablines = NULL,
  x.ablines.col = "black",
  x.ablines.lty = "dashed",
  y.ablines = NULL,
  y.ablines.col = "black",
  y.ablines.lty = "dashed",
  quantiles.x = c(0, 1),
  quantiles.y = c(1e-04, 0.9999),
  preset = c("maplot", "volcano"),
  no.legend = FALSE,
  legend.position = "bottom",
  legend.addnumbers = TRUE,
  return.data = FALSE
)

Arguments

xval	a vector with values for the x-axis, usually average expression in MAs and log fold-change in Volcanos
yval	a vector with values for the y-axis, usually log fold-change in MAs and -log10(padj) in Volcanos
pval	a vector with pvalues-like values. Points below the pval.thresh will be highlighted with color
labels	a vector of equal length containing per-point labels (e.g. the gene names) which then can be used downstream to label the points, see examples and details
xval.thresh	absolute threshold value for x-axis values to be color-highlighted, see details
yval.thresh	absolute threshold value for y-axis values to be color-highlighted, see details
pval.thresh	threshold for pvalues, see details
col.base	the base color for the data points, will also be used to color non-significant points
col.up	use this color for points classified as "Up", see details
col.down	use this color for points classified as "Down", see details
point.size	size of data points
point.alpha	point opacity
xlab	x-axis label, if NULl then defaults to "baseMean" for MA-plots and "log2FoldChange" for Volcanos
ylab	y-axis label, if NULl then defaults to "log2FoldChange" for MA-plots and "-log10(padj)" for Volcanos
xlim	xaxis limits, by default full data range
ylim	yaxis limits, by default the 0.001th and 0.999th quantile of the data range, see details
Up	legend label for points being "Up"
Down	legend label for points being "Down"
NonSig	legend label for points being "NonSig"
title	main title text
subtitle	subtitle text
x.ablines	a vector with numeric values, will use to draw vertical ablines
x.ablines.col	color of x.ablines
x.ablines.lty	line type of x.ablines
y.ablines	a vector with numeric values, will use to draw horizontal ablines
y.ablines.col	color of y.ablines
y.ablines.lty	line type of y.ablines
quantiles.x	use these quantiles of the xaxis data range to determine automatic axis limits, see details
quantiles.y	use these quantiles of the yaxis data range to determine automatic axis limits, see details
preset	the type of plot, "maplot" by default, or "volcano" to make a volcano plot, see examples
no.legend	logical, whether to remove the legend
legend.position	legend positon, one of left/right/top/bottom
legend.addnumbers	logical, whether to add the number of Up/Down/NonSig genes to the legend
return.data	logical, whether to return the long-form data.frame that was sed for plotting. In this case the output is a list with elements "plot" and "data".

Details

=> towards xval.thresh/yval.threshold/pval.threshold
We assume a typical differential expression results table, so with log fold-changes, average expression values (baseMean) and some kind of p-values. We can trigger color-highlighting of significant genes if a p-value is provided to the function. For MA-plots points below this pval.thresh will then be classified as "Up" if yval > yval.thresh which is usually the fold change in MA-plots, or "Down" if < yval.thresh, or "NonSig" if > pval.thresh. xval.thresh is turned off by default for MA-plots but if a threshold is provided then only points with xval > xval.thresh will be considered for the classification. In preset="volcano" the yval.thresh is ignored as the yaxis is simply -log10(pval), therefore one should use pval.thresh for filtering.

=> towards quantiles.x/y
By default in MA-plot mode the yaxis (fold changes) is automatically scaled to avoid overly wide limits due to outliers. The 0.0001th and 0.9999th quantile of the yvals is used to set the limits. Points beyond these limits will be trimmed back to these exact limits and displayed as trianges rather than dots. The user can set custom quantiles or simply use an explicit xlim or ylim value to manually set axis limits. The automatic axis limit setting can be turned off by setting quantiles.x or quantiles.y t0 c(0,1). If xlim or ylim are provided then any quantile parameters will be overwritten.

=> towards labels
The user can provide a vector of gene names via labels which is then internally added to the ggplot object. That allows to manually label data points e.g. with ggrepel. We do not have an in-built option for labeling points in order to avoid overly many options, and (based on our experience) adding labels to plots with many data points anyway requires custom tweaking to produce a "good-looking" plot. It can be done via e.g. ggrepel::geom_text_repel() without much effort though, see last example. Basically, one uses an ifelse statement that returns the gene name if it is to be plotted or an empty string if not. The label is then added to the data.frame that is passed to ggplot, so one simply has to add "+ geom_label_repel" in order to plot the label. One can then add ggrepel options at will, e.g. nudge_x/y to increase connector length.

Author(s)

Alexander Toenges

Examples

set.seed(1)
dds <- DESeq2::DESeq(DESeq2::makeExampleDESeqDataSet(5000,10))
res <- DESeq2::results(dds) %>% data.frame %>% na.omit
res$baseMean<-log2(res$baseMean+1)
res$padj <- res$pvalue
theme_set(theme_classic(base_size = 12.5))

# a standard MA-plot 
ggMAplot(xval = res$baseMean, yval = res$log2FoldChange, pval = res$padj,
title = "MA-plot", subtitle = "most basic version")

# with an abline at abs(log2(1.5)) and at 0:
ggMAplot(xval = res$baseMean, yval = res$log2FoldChange, pval = res$padj,
y.ablines = c(log2(1.5),-log2(1.5)), title = "MA-plot", subtitle = "with some ablines")

#/ show only from -2 to 2 on the y-axis, points beyond the limits will be printed as triangles:
ggMAplot(xval = res$baseMean, yval = res$log2FoldChange, pval = res$padj,
y.ablines = c(log2(1.5),-log2(1.5)), title = "MA-plot", subtitle = "with ablines and restricted at the y-axis to -2/+2",
ylim=c(-2,2))

# as Volcano:
ggMAplot(xval = res$log2FoldChange, yval = -log10(res$padj), pval = res$padj,
title = "Volcano", subtitle = "most basic version", preset = "volcano")

# Volcano with only abs(logFC) > 2 colored
ggMAplot(xval = res$log2FoldChange, yval = -log10(res$padj), pval = res$padj,
title = "Volcano", subtitle = "with some ablines", preset = "volcano", xval.thresh=2,
x.ablines=c(-2,2))

# Label significant regions, threshold padj<0.001 & abs(log2FoldChange) > log2(2).
# Note that for the \code{labels} option we make a custom vector, same order as for the
# xval/yval/pval vectors, setting those genes we do **not** want to plot as \code{""}.
# It is now on the user to tweak the number of genes to label and to play with \code{max.overlaps}
# in \code{geom_text_repel} until the plot looks satisfying.
library(ggrepel)
ggMAplot(xval = res$log2FoldChange, yval = -log10(res$padj), pval = res$padj,
labels=ifelse(res$padj < 0.001 & abs(res$log2FoldChange) > log2(2), rownames(res), ""),
title = "Volcano", subtitle = "with padj < 0.001 labelled", preset = "volcano", xval.thresh=log2(2)) +
geom_label_repel(show.legend=FALSE, max.overlaps=20, min.segment.length=0, nudge_x=1, nudge_y=-1)

# or only gene number 1, see also https://ggrepel.slowkow.com/articles/examples.html for many options to customize ggrepel:
library(ggrepel)
ggMAplot(xval = res$log2FoldChange, yval = -log10(res$padj), pval = res$padj,
labels=ifelse(rownames(res) == "gene1", rownames(res), ""),
title = "Volcano", subtitle = "with specific genes labelled", preset = "volcano", xval.thresh=log2(2)) +
geom_label_repel(aes(label=labels), show.legend=FALSE, min.segment.length=0, nudge_x=-1)

ATpoint/vizzy documentation built on Dec. 15, 2022, 5:01 p.m.