\HeaderA{twilight.pval}{A function to compute p-values from expression sets}{twilight.pval}
\keyword{nonparametric}{twilight.pval}
\begin{Description}\relax
The functions implements twosample t, Z and fold change equivalent tests, paired or unpaired, and correlation coefficients. Based on permutations, expected test statistics as given in Tusher et al. (2001) and empirical \eqn{p}{}-values are computed. Additional output are \eqn{q}{}-values computed as given in Storey and Tibshirani (2003). The resulting object is of class \code{twilight} and can be passed to functions \code{twilight} or \code{plot.twilight}.
\end{Description}
\begin{Usage}
\begin{verbatim}
twilight.pval(xin, yin, method = "fc", paired = FALSE, B = 1000, yperm = NULL, balance = FALSE, quant.ci = 0.95, s0=NULL, verbose = TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{xin}] Either an expression set (\code{exprSet}) or a data matrix with rows corresponding to features and columns corresponding to samples. 
\item[\code{yin}] A numerical vector containing class labels. The higher label denotes the case, the lower label the control samples to test case vs. control. For correlation scores, \code{yin} can be any numerical vector of length equal to the number of samples. 
\item[\code{method}] Character string: \code{"fc"} for fold change equivalent test (that is log ratio test), \code{"t"} for t test, and \code{"z"} for Z test. With \code{"pearson"} or \code{"spearman"}, the test statistic is either Pearson's correlation coefficient or Spearman's rank correlation coefficient.
\item[\code{paired}] Logical value. Depends on whether the samples are paired. Ignored if \code{method="pearson"} or \code{method="spearman"}.
\item[\code{B}] Numerical value specifying the number of permutations. 
\item[\code{yperm}] Optional matrix containing in each row a permutation of the class labels in binary format. If \code{yperm} is specified, no other permutation will be done. Ignored if \code{method="pearson"} or \code{method="spearman"}.
\item[\code{balance}] Logical value. Depends on whether balanced or unbalanced permutations should be done. Ignored if \code{method="pearson"} or \code{method="spearman"}.
\item[\code{quant.ci}] Probability value for confidence lines. Lines are symmetric and denote the \code{quant.ci}-quantile of maximal absolute differences between each permutatin and the expected scores. 
\item[\code{s0}] Fudge factor for variance correction in Z test. Takes effect only if \code{method="z"}. If \code{s0=NULL}: Fudge factor is set to median of root pooled variances.
\item[\code{verbose}] Logical value for message printing. 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
See vignette.
\end{Details}
\begin{Value}
Returns a \code{twilight} object consisting of a \code{data.frame} named \code{result} with variables
\begin{ldescription}
\item[\code{observed}] Observed test statistics.
\item[\code{expected}] Mean of order statistics of the permutation statistics.
\item[\code{candidate}] Binary vector. \code{"1"} for observations exceeding the confidence lines.
\item[\code{pvalue}] Twosided test permutation \eqn{p}{}-values.
\item[\code{qvalue}] \eqn{q}{}-values computed as described in Storey and Tibshirani (2003).
\item[\code{index}] Index of the original ordering.
\end{ldescription}

Values are sorted by absolute \code{observed} scores.
\end{Value}
\begin{Note}\relax
Additional output consists of

\Tabular{ll}{
\code{ci.line} & Quantile corresponding to \code{quant.ci}, passed for plotting. \\
\code{pi0} & Estimated prior probability. \\
\code{call} & Character string of function arguments. \\
\code{quant.ci} & Passes \code{quant.ci} for plotting. \\
}

The remaining slots are left free for function \code{twilight}.
\end{Note}
\begin{Author}\relax
Stefanie Scheid \url{http://www.molgen.mpg.de/~scheid}
\end{Author}
\begin{References}\relax
Golub TR, Slonim DK, Tamayo P, Huard C, Gaasenbeek M, Mesirov JP, Coller H, Loh ML, Downing JR, Caligiuri MA, Bloomfield CD and Lander ES (1999): Molecular Classification of Cancer: Class Discovery and Class Prediction by Gene Expression Monitoring, \emph{Science} \bold{286}, 531--537.

Huber W, von Heydebreck A, Sültmann H, Poustka A and Vingron M (2002): Variance stabilization applied to microarray data calibration and to the quantification of differential expression, \emph{Bioinformatics} \bold{18}, suppl. 1, S96--S104.

Scheid S and Spang R (2004): A stochastic downhill search algorithm for estimating the local false discovery rate, \emph{IEEE TCBB} \bold{1(3)}, 98--108.

Storey JD and Tibshirani R (2003): Statistical significance for genomewide studies, \emph{PNAS} \bold{100(16)}, 9440--9445.

Tusher VG, Tibshirani R and Chu G (2001): Significance analysis of mircroarrays applied to the ionizing response, \emph{PNAS} \bold{98(9)}, 5116--5121.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{twilight}{twilight}}, \code{\LinkA{plot.twilight}{plot.twilight}}, \code{\LinkA{twilight.combi}{twilight.combi}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
### Leukemia data set of Golub et al. (1999)
library(golubEsets)
data(golubMerge)

### Variance-stabilizing normalization of Huber et al. (2002)
library(vsn)
golubNorm <- vsn(exprs(golubMerge))

### A vector of class labels.
id <- as.numeric(golubMerge$ALL.AML)

a <- twilight.pval(golubNorm,id)
plot(a,which="scores")
plot(a,which="qvalues")
\end{ExampleCode}
\end{Examples}

