moderTestXgrp: Multiple Moderated Pairwise t-tests From limma

Description

This function runs (selected or all) pairwise combinations of moderated t-tests from package 'limma' on each line of data against. Note: This function requires the package limma from bioconductor. The limma contrast-matrix has to be read by column, the lines in the contrast-matrix containing '+1' will be compared to the '-1' lines, eg grpA-grpB .

Usage

moderTestXgrp(
  dat,
  grp,
  useComparison = NULL,
  limmaOutput = TRUE,
  addResults = c("lfdr", "FDR", "Mval", "means"),
  testOrientation = "=",
  sep = NULL,
  silent = FALSE,
  debug = FALSE,
  callFrom = NULL
)

Value

This function returns a limma-type MA-object (which can be handeled like a list), or when problems are encountered NULL

Arguments

dat: matrix or data.frame with rows for multiple (independent) tests, use ONLY with 2 groups; assumed as log2-data !!!
grp: (factor) describes column-relationship of 'dat' (1st factor is considered as reference -> orientation of M-values !!)
useComparison: (numeric, character or matrix) optional way to indicate which pairwise comparisons should be performed : if useComparison="all" all pairwise comparisons possible will be performed, otherise pairwise comparisons may be chosen using indexes (the ith instance of all possible pairwise comparisons); a character vector citing the concatenated levels of argument grp; may be used (in this case it may be necessary to specify the separator used in argument argument sep ; please note, it is important to check that a custom selected separator sep does not occur inside the groups from grp); finally, the argument useComparison may be or as matrix of 2 columns where each row specifies a different comparison, the matrix mat contain the names of the levels of argument grp or an index relative to the levels of argument grp; In all cases where 2 groups are specified this will be read as 'sample-reference' - thus, the 2nd entity will be taken as reference; Of course this separator should not occur in 'grp' (if present it will be automatically repaced by '__' in 'grp' ).
limmaOutput: (logical) return full (or extended) MArrayLM-object from limma or 'FAlSE' for only the (uncorrected) p.values
addResults: (character) types of results to add besides basic limma-output, data are assumed to be log2 ! (eg "lfdr" using fdrtool-package, "FDR" or "BH" for BH-FDR, "BY" for BY-FDR, "bonferroni" for Bonferroni-correction, "qValue" for lfdr by qvalue, "Mval", "means" or "nonMod" for non-moderated test and he equivaent all (other) multiple testing corrections chosen here)
testOrientation: (character) for one-sided test (">","greater" or "<","less"), NOTE : 2nd grp is considered control/reference, '<' will identify grp1 < grp2
sep: (NULL] or character of length=1) optional custom choice for separator for column-names of pairwise comparisons, otherwise determined as character(-set) not occurring in grp
silent: (logical) suppress messages
debug: (logical) additional messages for debugging
callFrom: (character) allow easier tracking of messages produced

Details

When multiple pairwise comparisons will be run, first a global linear model will be estimated and the particular pairwise comparisons will then be performed using a contrast-matrix. This process is described with the bioconductor package limma which is used underneith.

By default (useComparison=NULL), the first of all possible pairwise comparisons will be run. If you would like to run all comparisons, plase set useComparison="all". Besides, it is also possible to custom choose which comparisons should be run (and which order of sample/reference) via the argument useComparison using the character vector '--' as separator for the two groups of samples (referring to argument grp) to be compared. This will be interpreted as 'sample--reference' (additional space around the separator, if present, will be removed), thus the second element will be used as reference. Furthermore, the argument useComparison may be a matrix of 2 columns (for sample and reference) where each line represents a pairwise comparison that should be run.

As effort for compatibility to previous versions and compatibility to standard writing in limma the group-separator '-' in useComparison has limited support : This (single character) separator will be internally converted to '--' and in absence of '-' in argument grp, output will have the initial (single character) separator '-'.

Concerning the separator used when reporting results for pairwise comparisons : If argument grp contains any '-', comparisons of groups will always (!) get reported using '--' as separator to avoid any confusion. In case useComparison is a matrix, the reported comparisons will have '-' if grp does not contain as well any '-', otherwise '--' will be used (to support compatibility with results from limma).

Please note, that in the output of this function the Benjamini-Hochberg (BH) adjusted p-values are called 'FDR' (see argument addResults).

the output caontains a list-element named setup summarizing the global setup as captured (names of groups of samples), including the names of the pairwise combinations that were tested.

Examples

Run this code

grp3 <- factor(rep(LETTERS[c(3,1,4)],c(2,3,3)))
set.seed(2017); t8 <- matrix(round(rnorm(208*8,10,0.4),2), ncol=8,
  dimnames=list(paste(letters[],rep(1:8,each=26),sep=""), paste0(grp3, c(1:2,1:3,1:3))))
t8[3:6,1:2] <- t8[3:6,1:2] +3                    # augment lines 3:6 (c-f) 
t8[5:8,c(1:2,6:8)] <- t8[5:8,c(1:2,6:8)] -1.5    # lower lines 
t8[6:7,3:5] <- t8[6:7,3:5] +2.2                  # augment lines 
## expect to find C/A in c,d,g, (h)
## expect to find C/D in c,d,e,f
## expect to find A/D in f,g,(h) 
test8 <- moderTestXgrp(t8, grp3) 

## Custom choice of what to compare
test8b <- moderTestXgrp(t8, grp3, useComparison=c("D-A","C-A")) 
head(test8b$FDR)
head(test8b$Mval)

## Custom choice as matrix
comp4 <- matrix(LETTERS[c(4,3,3,1)], ncol=2)
test4 <- moderTestXgrp(t8, grp3, useComparison=comp4)

## Names of pairwise comparisons performed
test4$setup$concat

## One can also use functions from package limma to see more
library(limma)
topTable(test8b, n=5)