\HeaderA{modelCalcINT}{Fit a model with main effect and first order interaction 
terms for each gene and calculate significance}{modelCalcINT}
\keyword{models}{modelCalcINT}
\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 or first order
interactions. The significance of each term is computed by using a
type II sum of squares.
\end{Description}
\begin{Usage}
\begin{verbatim}
  modelCalcINT(paramData, exprData, param4INT, 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{param4INT}] A character vector specifying the variables for which
first order interactions should be calculated.
\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{modelCalcINT}{modelCalcINT}} 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{modelCalcME}{modelCalcME}}, terms used
in the model may be main effect terms or
first-order interactions. The step-wise process begins by fitting the 
maximal model
to the data, then removes terms using 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.

To increase speed, the model fitting procedure is first performed
using only main effect terms, and first order interactions are only
calculated if the main effect term is thus shown to be significant.

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{modelCalcINT}{modelCalcINT}} 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 main effect only version of this function, see
\code{\LinkA{modelCalcME}{modelCalcME}}. For the main \pkg{Envisage}
method, see \code{\LinkA{envisage}{envisage}}.
\end{SeeAlso}

