VolcanoPlotW: Volcano-plot (Statistical Test Outcome versus Relative Change)

Description

This type of plot is very common in high-throughput biology, see Volcano-plot. Basically, this plot allows comparing the outcome of a statistical test to the differential of the group means (ie log fold-change),

Usage

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

Arguments

Mvalue

(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

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) choice of one of multiple comparisons 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

ProjNa

(character) custom title

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 or name of list-element

FdrThrs

(numeric) FDR threshold (display as line), default at 0.05, set to NA for omitting

subTxt

(character) custom sub-title

grayIncrem

(logical) if TRUE, display overlay of points 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)

cexLa

(numeric) size of axis-labels, as expansion factor (see also cex in par)

limM

(numeric, length=2) range of axis M-values

limp

(numeric, length=2) range of axis p-values

annotColumn

(character) column names of annotation to be extracted (only if Mvalue is MArrayLM-object containing matrix $annot)

annColor

(character or integer) colors for specific groups of annoatation (only if Mvalue is MArrayLM-object containing matrix $annot)

cexPt

(numeric) size of points, 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)

namesNBest

(integer or character) number of best points (by pValue to display names in figure); if 'passThr' all points passing FDR and FC-filtes will be selected

NbestCol

(character or integer) colors for text-labels of best points

useMar

(numeric,length=4) custom margings (see also par)

returnData

(logical) optional returning data.frame with (ID, Mvalue, pValue, FDRvalue, passFilt)

callFrom

(character) allow easier tracking of message(s) produced

silent

(logical) suppress messages

debug

(logical) additional messages for debugging

Value

MA-plot only

Details

In high-throughput biology data are typically already transformed to log2 and thus, the 'M'-value represents a relative change. Besides, output from statistical testing by moderTest2grp or moderTestXgrp can be directly read to produce Volcano plots for diagnostic reasons. Please note, that plotting a very number of points in transparency (eg >10000) may take several seconds.

Examples

Run this code

# NOT RUN {
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.7
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")

## assume 3 groups with 3 samples each
tRes <- moderTestXgrp(mat, gr3, 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)
 
# }