% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/moderTestXgrp.R
\name{moderTestXgrp}
\alias{moderTestXgrp}
\title{Multiple Moderated Pairwise t-tests From limma}
\usage{
moderTestXgrp(
  dat,
  grp,
  useComparison = NULL,
  limmaOutput = TRUE,
  addResults = c("lfdr", "FDR", "Mval", "means"),
  testOrientation = "=",
  sep = NULL,
  silent = FALSE,
  debug = FALSE,
  callFrom = NULL
)
}
\arguments{
\item{dat}{matrix or data.frame with rows for multiple (independent) tests, use ONLY with 2 groups; assumed as log2-data !!!}

\item{grp}{(factor) describes column-relationship of 'dat'   (1st factor is considered as reference -> orientation of M-values !!)}

\item{useComparison}{(numeric, character or matrix) optional way to indicate which pairwise comparisons should be performed :
if \code{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 \code{grp}; may be used (in this case it may be necessary to specify the separator used in argument argument \code{sep} ;
please note, it is important to check that a custom selected separator \code{sep} does not occur inside the groups from \code{grp});
finally, the argument \code{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 \code{grp} or an index relative to the levels of argument \code{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' ).}

\item{limmaOutput}{(logical) return full (or extended) MArrayLM-object from limma or 'FAlSE' for only the (uncorrected) p.values}

\item{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)}

\item{testOrientation}{(character) for one-sided test (">","greater" or "<","less"), NOTE : 2nd grp is considered control/reference, '<' will identify grp1 < grp2}

\item{sep}{(\code{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 \code{grp}}

\item{silent}{(logical) suppress messages}

\item{debug}{(logical) additional messages for debugging}

\item{callFrom}{(character) allow easier tracking of messages produced}
}
\value{
This function returns a limma-type MA-object (which can be handeled like a list), or when problems are encountered \code{NULL}
}
\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 \href{https://bioconductor.org/packages/release/bioc/html/limma.html}{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 .
}
\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 \href{https://bioconductor.org/packages/release/bioc/html/limma.html}{limma} which is used underneith.

By default (\code{useComparison=NULL}), the first of all possible pairwise comparisons will be run.
If you would like to run all comparisons, plase set \code{useComparison="all"}.
Besides, it is also possible to custom choose which comparisons should be run (and which order of sample/reference) via the argument \code{useComparison} using
the character vector '--' as separator for the two groups of samples (referring to argument \code{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 \code{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 \code{useComparison} has limited support : 
This (single character) separator will be internally converted to '--' and in absence of '-' in argument \code{grp}, output will have the initial  (single character) separator '-'.

Concerning the separator used when reporting results for pairwise comparisons :
If argument \code{grp} contains any '-', comparisons of groups will always (!) get reported using '--' as separator to avoid any confusion.
In case \code{useComparison} is a matrix, the reported comparisons will have '-' if \code{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 \code{addResults}).

the output caontains a list-element named \code{setup} summarizing the global setup as captured (names of groups of samples), including the names of the pairwise combinations that were tested.
}
\examples{
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)
}
\seealso{
\code{\link{moderTest2grp}} for simplified single comparisons (with fewer options/flexibility), \code{\link[limma]{lmFit}} and the \code{eBayes}-family of functions in package \href{https://bioconductor.org/packages/release/bioc/html/limma.html}{limma}
}
