\HeaderA{modelCalcME}{Fit a model with main effect terms only for each gene and
calculate significance}{modelCalcME}
\keyword{models}{modelCalcME}
\begin{Description}\relax
This is the main calculation for the package
\pkg{Envisage}. An optimised model, containing terms shown to have
practical importance for explaining variation, is produced using a
step-wise procedure. Terms may be main effect terms only. The
significnace of each term is computed by using a type II sum of
squares.
\end{Description}
\begin{Usage}
\begin{verbatim}
  modelCalcME(paramData, exprData, startingModel, progress) 
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{paramData}] An object of class
\code{\LinkA{phenoData}{phenoData}} containing the
phenotypic information for the experiment.
\item[\code{exprData}] A matrix of expression values for each gene for each
sample. Usually calculated using \code{\LinkA{exprs}{exprs}} on an
object of class
\code{\LinkA{ExpressionSet}{ExpressionSet}}.
\item[\code{startingModel}] An object of class \code{\LinkA{formula}{formula}}
containing the minimal model thta should be used in the step-wise
model fitting process.
\item[\code{progress}] Object of class \code{tclVar} indicating progress
through the genes in the gene list. Used only if \code{widget=TRUE}
for \code{\LinkA{envisage}{envisage}}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The \pkg{Envisage} package contains methods allowing the use of 
linear models (LMs) for analysing significantly changing genes in 
experiments with a variety of sources of variation, be they
experimentally controlled variables such as drug treatment or time, or
non-controlled sources of confounding variation such as phenotypic or
environmental differences. This allows all sources of variation to be
considered when analysing for significant differential expression,
ensuring resulting genes are biologically relevent to the experimental
question. 

The function \code{\LinkA{modelCalcME}{modelCalcME}} performs the main
modelling step for the package \pkg{Envisage}. A stepwise procedure is
used on a per-gene basis to calculate the optimum model for each
gene. In comparison to \code{\LinkA{modelCalcINT}{modelCalcINT}}, terms
used in the model may be main effect terms only. The step-wise
procedure begins by fitting the maximal
model
to the data, then removes terms in a leave-one-out approach based on
the Akaike information criterion (AIC). Specification of a minimal
model allows terms to be 'forced' into the final formula.

The significance of each term in the final model is estimated by using
a Type II sum of squares to compare the model with and without each
term. Also, if fitting the model results in aliased terms (either due
to experimental design, insufficient data, or non-independence of
model terms), this information is also returned.

\code{\LinkA{modelCalcME}{modelCalcME}} is an internal function and is not
designed to be accessed by users.
\end{Details}
\begin{Value}
A list is returned with the following slots:

\begin{ldescription}
\item[\code{pValues}] An object of class \code{data.frame} containing the
p-value from the Type II sum of squares analysis for each model term
for each gene.
\item[\code{failedAnova}] A vector of genes for which the Anova Type II sum of
squares failed, indicating model aliasing.
\item[\code{errorGenes}] A list of the genes that failed and the model terms
for which aliasing was detected.
\end{ldescription}
\end{Value}
\begin{Author}\relax
Sam Robson \email{S.C.Robson@warwick.ac.uk}
\end{Author}
\begin{References}\relax
Robson, S. C., Hunter, E., Bird, H., Turner, H. (2008) 
\emph{Envisage: model-based significance analysis of microarray gene
expression data}, manuscript in preparation
\end{References}
\begin{SeeAlso}\relax
For the interaction version of this function, see
\code{\LinkA{modelCalcINT}{modelCalcINT}}. For the main \pkg{Envisage}
method, see \code{\LinkA{envisage}{envisage}}.
\end{SeeAlso}

