VolcanoPlotW: Volcano-Plot (Statistical Test Outcome Versus Relative...

In wrGraph: Graphics in the Context of Analyzing High-Throughput Data

Volcano-Plot (Statistical Test Outcome Versus Relative Change)

Description

This type of plot is very common in high-throughput biology, see Volcano-plot. Basically, Volcano-Plots allows comparing the outcome of a statistical test to the relative change (ie log fold-change, M-value). This version of Volcano-plots supports conveniently results from packages wrMisc and wrProteo.

Usage

VolcanoPlotW(
  Mvalue,
  pValue = NULL,
  useComp = 1,
  filtFin = NULL,
  tit = NULL,
  ProjNa = NULL,
  FCthrs = NULL,
  FdrList = NULL,
  FdrThrs = NULL,
  FdrType = NULL,
  plotAsFdr = FALSE,
  subTxt = NULL,
  grayIncrem = TRUE,
  col = NULL,
  pch = 16,
  compNa = NULL,
  batchFig = FALSE,
  cexMa = 1.8,
  cexPt = NULL,
  cexLa = 1.1,
  cexSub = NULL,
  cexTxLab = 0.7,
  limM = NULL,
  limp = NULL,
  annotColumn = c("SpecType", "GeneName", "EntryName", "Accession", "Species", "Contam"),
  annColor = NULL,
  expFCarrow = FALSE,
  namesNBest = NULL,
  NbestCol = 1,
  colBySpecType = FALSE,
  sortLeg = "descend",
  NaSpecTypeAsContam = TRUE,
  useMar = c(6.2, 4, 4, 2),
  returnData = FALSE,
  callFrom = NULL,
  silent = FALSE,
  debug = FALSE
)

Arguments

Mvalue	(MArrayLM-object, numeric or matrix) data to plot; M-values are typically calculated as difference of log2-abundance values and 'pValue' the mean of log2-abundance values; M-values and p-values may be given as 2 columsn of a matrix, in this case the argument pValue should remain NULL. One may also furnish MArrayLM-objects created by packages wrProteo (CRAN) or limma (Bioconductor).
pValue	(numeric, list or data.frame) if NULL it is assumed that 2nd column of 'Mvalue' contains the p-values to be used
useComp	(integer, length=1) choice of which of multiple comparisons to present in Mvalue (if generated using moderTestXgrp())
filtFin	(matrix or logical) The data may get filtered before plotting: If FALSE no filtering will get applied; if matrix of TRUE/FALSE it will be used as optional custom filter, otherwise (if Mvalue if an MArrayLM-object eg from limma) a default filtering based on the filtFin element will be applied
tit	(character) custom title (has priority over ProjNa)
ProjNa	(character) will be added to automatic title (if custom title tit was not specified)
FCthrs	(numeric) Fold-Change threshold (display as line) give as Fold-change and NOT log2(FC), default at 1.5, set to NA for omitting
FdrList	(numeric) FDR data (only used when no Mvalue is not list or MArray-LMobject)
FdrThrs	(numeric) FDR threshold (display as line), default at 0.05, set to NA for omitting
FdrType	(character) FDR-type to extract if Mvalue is 'MArrayLM'-object (eg produced by from moderTest2grp etc); if NULL it will search for suitable fields/values in this order : 'FDR','BH','lfdr' and 'BY'
plotAsFdr	(logical) rather plot using FDR-values (if available) instead of p-Values
subTxt	(character) custom sub-title
grayIncrem	(logical) if TRUE, display overlay of points (not exceeding thresholds) as increased shades of gray
col	(character) custom color(s) for points of plot (see also par)
pch	(integer) type of symbol(s) to plot (default=16) (see also par)
compNa	(character) names of groups compared
batchFig	(logical) if TRUE figure title and axes legends will be kept shorter for display on fewer splace
cexMa	(numeric) font-size of title, as expansion factor (see also cex in par)
cexPt	(numeric) size of points, as expansion factor (see also cex in par)
cexLa	(numeric) size of axis-labels, as expansion factor (see also cex in par)
cexSub	(numeric) size of subtitle, as expansion factor (see also cex in par)
cexTxLab	(numeric) size of text-labels for points, as expansion factor (see also cex in par)
limM	(numeric, length=2) range of axis M-values
limp	(numeric, length=2) range of axis FDR / p-values
annotColumn	(character) column names of annotation to be extracted (only if Mvalue is MArrayLM-object containing matrix $annot). The first entry (typically 'SpecType') is used for different symbols in figure, the second (typically 'GeneName') is used as prefered text for annotating the best points (if namesNBest allows to do so.)
annColor	(character or integer) colors for specific groups of annotation (only if Mvalue is MArrayLM-object containing matrix $annot)
expFCarrow	(logical, character or numeric) optional adding arrow for expected fold-change; if TRUE the expected ratio will be extracted from numeric concentration-indications from sample-names if numeric an arrow will be drawn (M-value as 1st position, color of 2nd position of vector).
namesNBest	(integer or character) for display of labels to points in figure : if namesNBest='pass', 'passThr' or 'signif' all points passing thresholds will get labels; if namesNBest=5 this number of best points will get labels; if namesNBest="5 each" the best n of significant points on each side will get labels; if the initial object Mvalue contains a list-element called 'annot' the second value of argument annotColumn will be used (of available in 'annot') as text
NbestCol	(character or integer) colors for text-labels of best points, also used for arrow
colBySpecType	(logical) incase arument Mvalue is MArrayLM-object it is possible to use different color-codes for points passing thresholds based on Mvalue$annot[,"SpecType"]; use this with multi-species benchmark tests
sortLeg	(character) sorting of 'SpecType' annotation either ascending ('ascend') or descending ('descend'), no sorting if NULL
NaSpecTypeAsContam	(logical) consider lines/proteins with NA in Mvalue$annot[,"SpecType"] as contaminants (if a 'SpecType' for contaminants already exits)
useMar	(numeric, length=4) custom margings (see also par)
returnData	(logical) optional returning data.frame with (ID, Mvalue, pValue, FDRvalue, passFilt)
callFrom	(character) allows easier tracking of messages produced
silent	(logical) suppress messages
debug	(logical) additional messages for debugging

Details

In high-throughput biology data are typically already transformed to log2 and thus, the 'M'-values (obtained by subtracting two group means, 'Minus') represent a relative change (ie fold-change). Output from statistical testing by moderTestXgrp or from package wrProteo can be directly read to produce Volcano plots. Please note, that plotting a very high number of points (eg >3000) in transparency may take several seconds.

Thresholds for the statistical testing can be set using FdrThrs which will be using FDR-values (or lfdr-values) from MArrayLM-objects or externaly provided FdrList Besides, typically thresholds are set on the M-values, too. Here the threshold from argulent FCthrs will be used. Please note that M-value threshold should be given as _linear scale_, ie FCthrs=1.5 will be shown on the log2-axes at 0.58.

Using the argument plotAsFdr FDR value will be used for plotting instead of p-values. Since selection of 'significant' hits is usually done based on FDR-values, it makes sense to plot them directly instead of inityial p-values. However, FDR values are not fully linear to initial p-values and plateau-phenomena may occur frequently. Thus, resulting plots may appear less spread, so finally drawing p-values (but cutting based on FDR-thersholds) many sometimes result in nicer plots.

The argument returnData=TRUE allows exporting directly all data shown on the plot, plus group-means (if available) filtering-status (if available) and symbol used on figure.

Value

This function simply plots an MA-plot (to the current graphical device), if returnData=TRUE an optional data.frame with (ID, Mvalue, pValue, FDRvalue, passFilt) can be returned

See Also

(for PCA) plotPCAw)

Examples

library(wrMisc)
set.seed(2005); mat <- matrix(round(runif(900),2), ncol=9)
rownames(mat) <- paste0(rep(letters[1:25], each=4), rep(letters[2:26],4))
mat[1:50,4:6] <- mat[1:50,4:6] + rep(c(-1,1)*0.1,25)
mat[3:7,4:9] <- mat[3:7,4:9] + 0.9
mat[11:15,1:6] <- mat[11:15,1:6] - 0.7
## assume 2 groups with 3 samples each
gr3 <- gl(3, 3, labels=c("C","A","B"))
tRes2 <- moderTest2grp(mat[,1:6], gl(2,3), addResults = c("FDR","means"))
# Note: due to the small number of lines only FDR chosen to calculate
VolcanoPlotW(tRes2)
## Add names of points passing custom filters
VolcanoPlotW(tRes2, FCth=1.3, FdrThrs=0.2, namesNBest="passThr")
VolcanoPlotW(tRes2, FCth=1.3, FdrThrs=0.2, namesNBest=3)
VolcanoPlotW(tRes2, FCth=1.3, FdrThrs=0.2, namesNBest="2 each side")

## assume 3 groups with 3 samples each
tRes <- moderTestXgrp(mat, gr3, useComparison="all", addResults = c("FDR","means"))
# Note: due to the small number of lines only FDR chosen to calculate
VolcanoPlotW(tRes)
VolcanoPlotW(tRes, FCth=1.3, FdrThrs=0.2)
VolcanoPlotW(tRes, FCth=1.3, FdrThrs=0.2, useComp=2)

wrGraph documentation built on June 11, 2026, 5:07 p.m.