@@ -1,6 +1,6 @@

 Package: limma

-Version: 3.31.7

-Date: 2016-12-14

+Version: 3.31.8

+Date: 2017-01-08

 Title: Linear Models for Microarray Data

 Description: Data analysis, linear models and differential expression for microarray data.

 Author: Gordon Smyth [cre,aut], Yifang Hu [ctb], Matthew Ritchie [ctb], Jeremy Silver [ctb], James Wettenhall [ctb], Davis McCarthy [ctb], Di Wu [ctb], Wei Shi [ctb], Belinda Phipson [ctb], Aaron Lun [ctb], Natalie Thorne [ctb], Alicia Oshlack [ctb], Carolyn de Graaf [ctb], Yunshun Chen [ctb], Mette Langaas [ctb], Egil Ferkingstad [ctb], Marcus Davy [ctb], Francois Pepin [ctb], Dongseok Choi [ctb]

@@ -59,6 +59,8 @@ S3method(cbind,MAList)

 S3method(cbind,RGList)

 S3method(cbind,EList)

 S3method(cbind,EListRaw)

+S3method(decideTests,default)

+S3method(decideTests,MArrayLM)

 S3method(detectionPValues,default)

 S3method(detectionPValues,EListRaw)

 S3method(dim,MAList)

@@ -4,13 +4,14 @@ setClass("TestResults",representation("matrix"))

 summary.TestResults <- function(object,...)

 #	Gordon Smyth

-#	26 Feb 2004.  Last modified 31 Jan 2005.

+#	Created 26 Feb 2004.  Last modified 6 Jan 2017.

 {

-#	apply(object,2,table)

-	tab <- array(0,c(3,ncol(object)),dimnames=list(c("-1","0","1"),colnames(object)))

-	tab[1,] <- colSums(object== -1,na.rm=TRUE)

-	tab[2,] <- colSums(object== 0,na.rm=TRUE)

-	tab[3,] <- colSums(object== 1,na.rm=TRUE)

+	Levels <- attr(object,"levels")

+	if(is.null(Levels)) Levels <- c(-1L,0L,1L)

+	nlevels <- length(Levels)

+	tab <- matrix(0L,nlevels,ncol(object))

+	dimnames(tab) <- list(as.character(Levels),colnames(object))

+	for (i in 1:nlevels) tab[i,] <- colSums(object==Levels[i],na.rm=TRUE)

 	class(tab) <- "table"

 	tab

 }

@@ -20,12 +21,84 @@ setMethod("show","TestResults",function(object) {

 	printHead([email protected])

 })

-decideTests <- function(object,method="separate",adjust.method="BH",p.value=0.05,lfc=0)

+decideTests <- function(object,...) UseMethod("decideTests")

+

+decideTests.default <- function(object,method="separate",adjust.method="BH",p.value=0.05,lfc=0,coefficients=NULL,cor.matrix=NULL,tstat=NULL,df=Inf,genewise.p.value=NULL,...)

+#	Accept or reject hypothesis tests across genes and contrasts

+#	Gordon Smyth

+#	17 Aug 2004. Last modified 8 Jan 2017.

+{

+	method <- match.arg(method,c("separate","global","hierarchical","nestedF"))

+	if(method=="nestedF") stop("nestedF adjust method requires an MArrayLM object",call.=FALSE)

+

+	adjust.method <- match.arg(adjust.method,c("none","bonferroni","holm","BH","fdr","BY"))

+	if(adjust.method=="fdr") adjust.method <- "BH"

+

+	p <- as.matrix(object)

+	if(any(p>1) || any(p<0)) stop("object doesn't appear to be a matrix of p-values")

+

+	switch(method,

+

+	  separate={

+		for (i in 1:ncol(p)) p[,i] <- p.adjust(p[,i],method=adjust.method)

+

+	},global={

+		p[] <- p.adjust(p[],method=adjust.method)

+

+	},hierarchical={

+		if(is.null(genewise.p.value)) {

+#			Apply Simes' method by rows to get genewise p-values

+			genewise.p.value <- rep_len(1,nrow(p))

+			ngenes <- nrow(p)

+			ncontrasts <- ncol(p)

+			Simes.multiplier <- ncontrasts/(1:ncontrasts)

+			for (g in 1:ngenes) {

+				op <- sort(p[g,],na.last=TRUE)

+				genewise.p.value[g] <- min(op*Simes.multiplier,na.rm=TRUE)

+			}

+		}

+#		Adjust genewise p-values

+		DEgene <- p.adjust(genewise.p.value,method=adjust.method) <= p.value

+#		Adjust row-wise p-values

+		p[!DEgene,] <- 1

+		gDE <- which(DEgene)

+		for (g in gDE) p[g,] <- p.adjust(p[g,],method=adjust.method)

+#		Adjust p-value cutoff for number of DE genes

+		nDE <- length(gDE)

+		a <- switch(adjust.method,

+			none=1,

+			bonferroni=1/ngenes,

+			holm=1/(ngenes-nDE+1),

+			BH=nDE/ngenes,

+			BY=nDE/ngenes/sum(1/(1:ngenes))

+		)

+		p.value <- a*p.value

+	},nestedF={

+		stop("nestedF adjust method requires an MArrayLM object",call.=FALSE)

+	})

+

+	isDE <- array(0L,dim(p),dimnames=dimnames(p))

+	isDE[p <= p.value] <- 1L

+	if(is.null(coefficients)) coefficients <- tstat

+	if(is.null(coefficients)) {

+		attr(isDE,"levels") <- c(0L,1L)

+	} else {

+		attr(isDE,"levels") <- c(-1L,0L,1L)

+		coefficients <- as.matrix(coefficients)

+		if( !all(dim(coefficients)==dim(p)) ) stop("dim(object) disagrees with dim(coefficients)")

+		i <- coefficients<0

+		isDE[i] <- -isDE[i]

+		if(lfc>0) isDE[ abs(coefficients)<lfc ] <- 0L

+	}

+

+	new("TestResults",isDE)

+}

+

+decideTests.MArrayLM <- function(object,method="separate",adjust.method="BH",p.value=0.05,lfc=0,...)

 #	Accept or reject hypothesis tests across genes and contrasts

 #	Gordon Smyth

-#	17 Aug 2004. Last modified 13 August 2010.

+#	17 Aug 2004. Last modified 8 Jan 2017.

 {

-	if(!is(object,"MArrayLM")) stop("Need MArrayLM object")

 	if(is.null(object$p.value)) object <- eBayes(object)

 	method <- match.arg(method,c("separate","global","hierarchical","nestedF"))

 	adjust.method <- match.arg(adjust.method,c("none","bonferroni","holm","BH","fdr","BY"))

@@ -1,3 +1,8 @@

+ 8 Jan 2016: limma 3.31.8

+

+- decideTests() is now an S3 generic function with a default method

+  and a method for MArrayLM objects.

+

 14 Dec 2016: limma 3.31.7

 - Bug fix for contrastAsCoef() when there is more than one contrast.

@@ -1,42 +1,55 @@

 \name{decideTests}

 \alias{decideTests}

+\alias{decideTests.default}

+\alias{decideTests.MArrayLM}

 \title{Multiple Testing Across Genes and Contrasts}

 \description{

-Classify a series of related t-statistics as up, down or not significant.

-A number of different multiple testing schemes are offered which adjust for multiple testing down the genes as well as across contrasts for each gene.

+Identify which genes are significantly differentially expressed for each contrast from a fit object containing p-values and test statistics.

+A number of different multiple testing strategies are offered that adjust for multiple testing down the genes as well as across contrasts for each gene.

 }

 \usage{

-decideTests(object,method="separate",adjust.method="BH",p.value=0.05,lfc=0)

+\method{decideTests}{MArrayLM}(object, method = "separate", adjust.method = "BH", p.value = 0.05, lfc = 0, \dots)

+\method{decideTests}{default}(object, method = "separate", adjust.method = "BH", p.value = 0.05, lfc = 0,

+           coefficients = NULL, cor.matrix = NULL, tstat = NULL, df = Inf, genewise.p.value = NULL, \dots)

 }

 \arguments{

-  \item{object}{\code{MArrayLM} object output from \code{eBayes} or \code{treat} from which the t-statistics may be extracted.}

-  \item{method}{character string specify how probes and contrasts are to be combined in the multiple testing strategy.  Choices are \code{"separate"}, \code{"global"}, \code{"hierarchical"}, \code{"nestedF"} or any partial string.}

+  \item{object}{a numeric matrix of p-values or an \code{MArrayLM} object from which p-values and t-statistics can be extracted.}

+  \item{method}{character string specifying how genes and contrasts are to be combined in the multiple testing scheme.  Choices are \code{"separate"}, \code{"global"}, \code{"hierarchical"} or \code{"nestedF"}.}

   \item{adjust.method}{character string specifying p-value adjustment method.  Possible values are \code{"none"}, \code{"BH"}, \code{"fdr"} (equivalent to \code{"BH"}), \code{"BY"} and \code{"holm"}. See \code{\link[stats]{p.adjust}} for details.}

-  \item{p.value}{numeric value between 0 and 1 giving the desired size of the test}

-  \item{lfc}{minimum log2-fold-change required}

+  \item{p.value}{numeric value between 0 and 1 giving the required family-wise error rate or false discovery rate.}

+  \item{lfc}{numeric, minimum absolute log2-fold-change required.}

+  \item{coefficients}{numeric matrix of coefficients or log2-fold-changes. Of same dimensions as \code{object}.}

+  \item{cor.matrix}{correlation matrix of coefficients. Square matrix of dimension \code{ncol(object)}.}

+  \item{tstat}{numeric matrix of t-statistics. Of same dimensions as \code{object}.}

+  \item{df}{numeric vector of length \code{nrow(object)} giving degrees of freedom for the t-statistics.}

+  \item{genewise.p.value}{numeric vector of length \code{nrow(object)} containing summary gene-level p-values for use with \code{method="hierarchical"}.}

+  \item{\dots}{other arguments are not used.}

 }

 \value{

 An object of class \code{\link[=TestResults-class]{TestResults}}.

-This is essentially a numeric matrix with elements \code{-1}, \code{0} or \code{1} depending on whether each t-statistic is classified as significantly negative, not significant or significantly positive respectively.

+This is essentially a numeric matrix with elements \code{-1}, \code{0} or \code{1} depending on whether each t-statistic is classified as significantly negative, not significant or significantly positive.

 If \code{lfc>0} then contrasts are judged significant only when the log2-fold change is at least this large in absolute value.

 For example, one might choose \code{lfc=log2(1.5)} to restrict to 50\% changes or \code{lfc=1} for 2-fold changes.

 In this case, contrasts must satisfy both the p-value and the fold-change cutoff to be judged significant.

 }

 \details{

-These functions implement multiple testing procedures for determining whether each statistic in a matrix of t-statistics should be considered significantly different from zero.

-Rows of \code{tstat} correspond to genes and columns to coefficients or contrasts.

+This function can be applied to a matrix of p-values but is more often applied to an \code{MArrayLM} fit object produced by \code{eBayes} or \code{treat}.

+In either case, rows of \code{object} correspond to genes and columns to coefficients or contrasts.

-The setting \code{method="separate"} is equivalent to using \code{topTable} separately for each coefficient in the linear model fit, and will give the same lists of probes if \code{adjust.method} is the same.

+This function applies a multiple testing procedure and a significance level cutoff to the statistics contained in \code{object}.

+It implements a number of multiple testing procedures for determining whether each statistic should be considered significantly different from zero.

+

+The setting \code{method="separate"} is equivalent to using \code{topTable} separately for each coefficient in the linear model fit, and will identify the same probes as significantly differentially expressed if \code{adjust.method} is the same.

 \code{method="global"} will treat the entire matrix of t-statistics as a single vector of unrelated tests.

 \code{method="hierarchical"} adjusts down genes and then across contrasts.

 \code{method="nestedF"} adjusts down genes and then uses \code{classifyTestsF} to classify contrasts as significant or not for the selected genes.

 Please see the limma User's Guide for a discussion of the statistical properties of these methods.

 }

 \note{

-Although this function enables users to set p-value and lfc cutoffs simultaneously, this is not generally recommended.

-If the fold changes and p-values are not highly correlated, then the use of a fold change cutoff can increase the false discovery rate above the nominal level.

-Users wanting to use fold change thresholding are recommended to use \code{treat} instead of \code{eBayes}, and to leave \code{lfc} at the default value when using \code{decideTests}.

+Although this function enables users to set p-value and lfc cutoffs simultaneously, this combination criterion not usually recommended.

+Unless the fold changes and p-values are very highly correlated, the addition of a fold change cutoff can increase the family-wise error rate or false discovery rate above the nominal level.

+Users wanting to use fold change thresholding are recommended to use \code{treat} instead of \code{eBayes} and to leave \code{lfc} at the default value when using \code{decideTests}.

 }

 \seealso{

 An overview of multiple testing functions is given in \link{08.Tests}.