\HeaderA{esApply}{An apply-like function for ExpressionSet and related structures.}{esApply}
\keyword{models}{esApply}
\keyword{methods}{esApply}
\begin{Description}\relax
\code{esApply} is a wrapper to \code{apply} for use with \code{ExpressionSet}s.
The application of a function to rows of an expression array usually involves
variables in \code{pData}. \code{esApply} uses a special evaluation paradigm
to make this easy. The function \code{FUN} may reference any data in
\code{pData} by name.
\end{Description}
\begin{Usage}
\begin{verbatim}
esApply(X, MARGIN, FUN, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{X}] An instance of class \code{\LinkA{ExpressionSet}{ExpressionSet}}.
\item[\code{MARGIN}] The margin to apply to, either 1 for rows (samples) or
2 for columns (features).
\item[\code{FUN}] Any function 
\item[\code{...}] Additional parameters for \code{FUN}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The \code{pData} from \code{X} is installed in an
environment. This environment is installed as the environment of
\code{FUN}. This will then provide bindings for any symbols in
\code{FUN} that are the same as the names of the \code{pData} of
\code{X}. If \code{FUN} has an environment already it is retained but
placed after the newly created environment. Some variable shadowing
could occur under these circumstances.
\end{Details}
\begin{Value}
The result of \code{with(pData(x), apply(exprs(X), MARGIN, FUN, ...))}.
\end{Value}
\begin{Author}\relax
V.J. Carey <stvjc@channing.harvard.edu>, R. Gentleman
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{apply}{apply}}, \code{\LinkA{ExpressionSet}{ExpressionSet}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data(sample.ExpressionSet)
## sum columns of exprs
res <- esApply(sample.ExpressionSet, 1, sum)

## t-test, spliting samples by 'sex'
f <- function(x) {
    xx <- split(x, sex)
    t.test(xx[[1]], xx[[2]])$p.value
}
res <- esApply(sample.ExpressionSet, 1, f)

## same, but using a variable passed in the function call

f <- function(x, s) {
    xx <- split(x, s)
    mean(xx[[1]]) - mean(xx[[2]])
}
sex <- sample.ExpressionSet[["sex"]]
res <- esApply(sample.ExpressionSet, 1, f, s = sex)

# obtain the p-value of the t-test for sex difference
mytt.demo <- function(y) {
 ys <- split(y, sex)
 t.test(ys[[1]], ys[[2]])$p.value
}
sexPValue <- esApply(sample.ExpressionSet, 1, mytt.demo)

# obtain the p-value of the slope associated with score, adjusting for sex
# (if we were concerned with sign we could save the z statistic instead at coef[3,3]
myreg.demo <- function(y) {
   summary(lm(y ~ sex + score))$coef[3,4]
}
scorePValue <- esApply(sample.ExpressionSet, 1, myreg.demo)

# a resampling method
resamp <- function(ESET) {
 ntiss <- ncol(exprs(ESET))
 newind <- sample(1:ntiss, size = ntiss, replace = TRUE)
 ESET[newind,]
}

# a filter
q3g100filt <- function(eset) {
 apply(exprs(eset), 1, function(x) quantile(x,.75) > 100)
}

# filter after resampling and then apply
set.seed(123)
rest <- esApply({bool <- q3g100filt(resamp(sample.ExpressionSet)); sample.ExpressionSet[bool,]},
                1, mytt.demo)
\end{ExampleCode}
\end{Examples}

