volcanoFilter: Filter Statistical Testing Results in Volcano-Plot Like Fashion This function allows filtering statistical testing results combined with M-values (log2 fold-change) and other filtering criteria. All suitable values can be extracted from objects created from package wrProteo (and limma) may get used automatically. The outcome can be used for Volcano-plots or exporting tables.

Description

Filter Statistical Testing Results in Volcano-Plot Like Fashion

This function allows filtering statistical testing results combined with M-values (log2 fold-change) and other filtering criteria. All suitable values can be extracted from objects created from package wrProteo (and limma) may get used automatically. The outcome can be used for Volcano-plots or exporting tables.

Usage

volcanoFilter(
  Mvalue,
  pValue = NULL,
  useComp = 1,
  filtFin = NULL,
  FCthrs = NULL,
  FdrList = NULL,
  FdrThrs = NULL,
  FdrType = NULL,
  signifOnly = TRUE,
  annotColumn = c("SpecType", "GeneName", "EntryName", "Accession", "Species", "Contam"),
  silent = FALSE,
  debug = FALSE,
  callFrom = NULL
)

Value

This function returns a matrix (or in some instances a data.frame) combining (at least) the columns 'FDRvalue', 'Mvalue', 'pValue', 'filtFin' and 'retain'

Arguments

Mvalue: (numeric, list or of class 'MArrayLM') vector of M-values (log2 fold-change) or output from testRobustToNAimputation() from package wrProteo
pValue: (numeric) statistical testing results, only used in case argument Mvalue is only a numeric vector
useComp: (integer or character) in case argument Mvalue contains output from testRobustToNAimputation() this argument allows choosing a given pair-wise comparison
filtFin: (logical or matrix) optional vector to provide/include results from other additional filtering (columns should maych columns of pValue if multiple questions addressed in data); if argument Mvalue is list or class 'MArrayLM' this argument will be only used if respective information not present from Mvalue
FCthrs: (numeric) threshold for M-values (as log2(fold-change)), defaults to 1
FdrList: (vector, matrix or data.frame) additional statistical testing results for multiple testing correction, used for apply FdrThr; if argument Mvalue is list or class 'MArrayLM' this argument will be only used if respective information not present from Mvalue
FdrThrs: (numeric) threshold for filtering FdrList, defaults to 0.05
FdrType: (character) choose which multiple correction testing shoulbe used for filtering (only if argument Mvalue is list from wrProteo or class 'MArrayLM' )
signifOnly: (logical) decide if only filtered data or complete table should be returned
annotColumn: (character) additional elements from $annot to extract too if Mvalue is list (from wrProteo) or class 'MArrayLM')
silent: (logical) suppress messages
debug: (logical) additional messages for debugging
callFrom: (character) allow easier tracking of messages produced

Details

This function offers support for combined filtering along a significance-threshold (flexible choice of type of multiple testing correction) combined with M-values (log2 fold-change) and other filtering results (already present in objects from package wrProteo). Even though basic filtering can be performed using separated vectors (see example below), the main advantage relies on automatically recognizing the structure of results from testRobustToNAimputation() from package wrProteo.

In case of using with separate vectors the original p-values may be provided without or with multiple-testing corrected values (argument FdrList. If no multiple-testing correctio is provided it will be calculated using the Benjamini-Hochberg formula from p.adjust.

Note : M-value data is assumed to be log2-transformed ratios !

Examples

Run this code

set.seed(2025); means1 <- matrix(rnorm(2*95) +seq(1,3, length.out=2*95), 
  ncol=2, byrow=TRUE, dimnames=list(NULL, LETTERS[3:2]))
means1 <- rbind(means1, cbind((3:7)/2, c(6:8, -2:-3)))
rownames(means1) <- paste0("li_",sprintf(paste0("%03d"), 1:100))
Mval0 <- means1[,1] - means1[,2]
Mval1 <- matrix(means1[,1] - means1[,2], ncol=1, dimnames=list(rownames(means1), "C-B"))
set.seed(2026); pVal0 <- c(runif(95, max=0.9), (4:8)^(-4:-8))
FdrVal1 <- matrix(p.adjust(pVal0, method="BH"), ncol=1, dimnames=list(rownames(means1), "C-B"))
pVal1 <- matrix(pVal0, ncol=1, dimnames=list(rownames(means1), "C-B")) 

## with separate entries ...
filt1 <- volcanoFilter(Mvalue=Mval1, pValue=pVal1)        # separate values
tail(signif(filt1, 3))

## separate entries, retrieve all data for Volcano-Plot
filt2 <- volcanoFilter(Mvalue=Mval1, pValue=pVal1, signifOnly=FALSE)        # separate values
tail(signif(filt2, 3))
plot(filt2[,2], -1*log10(filt2[,3]), col=c("grey","red")[1+filt2[,5]], pch=16, main="Volcano-Plot")

## simulate basic/minimal object from wrProteo
Mobj3 <- list(means=means1, BH=FdrVal1, p.value=pVal1)
filt3 <- volcanoFilter(Mobj3)
tail(signif(filt3, 3))