\documentclass[12pt,a4paper]{article}
\title{Description of Envisage}
\author{Sam Robson}
\date{\today}
\pagestyle{headings}
\usepackage{natbib}
\usepackage{graphicx}
\usepackage[pdftex, colorlinks]{hyperref}
\usepackage{C:/Sweave}
\usepackage{fullpage}
\bibpunct{(}{)}{;}{n}{,}{,}
\linespread{1.3}
% \VignetteIndexEntry{Envisage}
\hyphenation{ExpressionSet Envisage}
%%%
%%%
%%%
%%%
%%%
\begin{document}
\maketitle
\tableofcontents

\section{Introduction}
\subsection{Motivation}
The development of high-density microarrays for gene expression analysis has been a breakthrough in functional genomic studies, allowing parallel analyses of the expression of many thousands of genes simultaneously at the transcriptome level. 

Such high-throughput data require suitably advanced methods of statistical hypothesis testing, such as analysis of variance, to ensure that measured changes in gene expression represent true biological events. Noise, due to a combination of technical, environmental, biological and random variation, can become a major problem in any microarray analysis and, whilst this can be reduced somewhat with careful experiment planning and implementation, statistical methods must be used to isolate real changes in gene expression from those occurring by random chance. To increase the power of statistical hypothesis testing techniques, replicate data must be collected~\cite{LEE}.  

It is all but impossible to design an experiment such that the variable(s) under the direct control of the experimenter (`parameter(s)') are the sole sources of variation within the experiment. Unavoidable environmental effects, nuisance variables such as batching effects, and phenotypic differences in \emph{in vivo} experimental samples will effect the response of the gene expression to the parameters of interest. These `covariates' must be considered when testing for significant changes in gene expression for the experiment parameters to ensure the biological relevence of the results. 

\subsection{Envisage}
\textbf{Envisage} (Enable Numerous Variables In Significance Analysis of Gene Expression) is a package developed for the Bioconductor project in R~\cite{Bioconductor} that utilises an automated linear model (LM) selection process to extend ANOVA to a wide range of predictor variables, including experimental parameters (drug treatment, disease state, time point, etc.), phenotypic covariates (gender, age, height, weight, etc.) and nuisance covariates (such as batch effects). This allows the inclusion of a wider range of variables, be they interesting experiment parameters or unavoidable covariates, when testing for significance. 

The inclusion of such confounding variables in the significance tests provides a more accurate representation of the true biology of the system under study. This process would be particularly useful for clinical studies, where the between-sample variation can be very high within each condition due to the difficulties in complete patient matching in a clinical setting.

The \textbf{Envisage} package has been designed to be user friendly, with a simple to use graphical user interface (GUI), described in section \ref{sec:GUI}, for those that don't want to use the command line interface of R. Also, \textbf{Envisage} can be run on an object of class \emph{ExpressionSet} within the R environment, or alternatively can be run directly from the gene expression analysis suite GeneSpring GX\footnote{Agilent Technologies, Santa Clara, CA}. Use of \textbf{Envisage} within Bioconductor is described in \ref{sec:programBC}, and through the GeneSpring GX plug-in external program interface in section \ref{sec:programGS}.


\subsection{The Envisage Modelling Procedure} \label{sec:model}
This section gives a brief overview of the steps involved in the \textbf{Envisage} model selection procedure. The input file for \textbf{Envisage} is an object of class \emph{ExpressionSet}, created within Bioconductor (section \ref{sec:programBC}) or created automatically using the GeneSpring EPI plugin (section \ref{sec:programGS}). This object contains information about probe level signals for the array, details on experimental variables for each sample, and annotation lists that can be used to link probes to their respective gene targets.

The model fitting procedure is a two step operation. First, a model is fit containing only main effect variables. Next, a more complex model is fit based on the first order interactions of variables found to be significant in the first step. This model is selected by first fitting a saturated model containing all available terms, and then removing terms based on the Akaike information criterion. This is essentially a penalised log-likelihood function that determines the benefit of keeping terms in the model with respect to its explanatory power; if the addition of the term has no clear benefit to the fit of the model, it is deemed unnecessary and removed. This two-step method was chosen to reduce run-time at the risk of missing important interaction information. 

A type II ANOVA test is used to test the significance of each of the model terms for each gene. The model for each gene is compared with and without each of the terms, and a p-value is calculated using an F-test statistic. A table of unadjusted p-values is created with genes as rows and all model terms as columns. 

It is recommended that a multiple testing correction procedure such as the Benjamini \& Hochberg false discovery rate~\citep{BH} adjustment be applied to the p-values to correct the matrix of p-values to take the large number of individual statistical test performed into account. Available multiple testing corrections can be found in section \ref{sec:ArgInfo}). Corrected p-values are compared to the specified p-value cutoff to test for significant differential expression. Genes showing a significant ANOVA F-test p-value for a particular term are considered to be changing significantly based on that variable. A list of genes with significant p-values is output to the user for each term as a tab-delimited text files.

For more details on the model selection procedure, please see Robson \emph{et al.}(manuscript in preparation).
%%%
%%%
%%%		Chapter 2: Getting Started
%%%
%%%
\newpage
\section{Getting Started}
The following description of the \textbf{Envisage} package is focused on the analysis of single-channel microarray data such as Affymetrix GeneChips, but the process can easily be extended to two-colour microarray and even other high-throughput data such as mass spectrometry data. The primary input file for the package is an object of class \emph{ExpressionSet}, a class of objects in R for representing microarray data. The object must contain all necessary gene expression information and phenodata (experiment variable information) for each sample, and also annotation information for the genome of interest. Relevant information for MIAME (Minimum Information About a Microarray Experiment) compliance can also be entered~\cite{MIAME}.

\textbf{Envisage} can be run within the R environment using an \emph{ExpressionSet} object created using the appropriate package in Bioconductor (\textbf{affy} for 1-colour data), or the package can be run directly through the Genespring GX analysis suite, which will automatically create the required object from the current Genespring GX experiment interpretation. 

This chapter gives information on setting up the R environment, installing the Bioconductor packages, installing the \textbf{Envisage} package, and creating the required Bioconductor object (both in Bioconductor itself and Genespring GX). Information for running the program itself can be found in section \ref{sec:program}.
%%%
%%%
%%%
\subsection{Getting Envisage Up and Running}
\subsubsection{Installing R and Bioconductor} \label{sec:Bioc}
\textbf{Envisage} is a package available from Bioconductor, a publicly available collection of packages for the statistical programming language R, allowing statistical and graphical methods for analysis of gene expression data. 

The R programming environment can be downloaded from the comprehensive R network archive (\emph{CRAN}) at \url{www.cran.r-project.org}. The current release, R-2.6-0, was released on 2007-10-03. The latest release of Bioconductor (Bioconductor 2.1 -- 2007-10-08) can be found at \url{www.bioconductor.org}. 

The simplest way to set up Bioconductor is to run it from the R environment, using the \emph{biocLite.R} installation script. This will install the basic packages required for gene expression analysis; \textbf{affy, affydata, affyPLM, annaffy, annotate, Biobase, Biostrings, DynDoc, gcrma, genefilter, geneplotter, hgu95av2, limma, marray, matchprobes, multtest, reposTools, ROC, vsn} and \textbf{xtable}.

To do this, open the R environment, and type the following in the command line:

\begin{Schunk}
\begin{Sinput}
> source("http://bioconductor.org/biocLite.R")
> biocLite()
\end{Sinput}
\end{Schunk}

This will establish a connection to the Bioconductor website and initialise installation. To install additional packages, use the package name as an argument in the biocLite.R method. e.g. To install packages \textbf{affy} and \textbf{marray}, type the following in the command line:

\begin{Schunk}
\begin{Sinput}
> biocLite(c("affy", "marray"))
\end{Sinput}
\end{Schunk}

The \emph{getBioC.R} installation script can also be used, which contains a larger number of default packages than the \emph{biocLite.R} script. To install this, follow the above steps, replacing \emph{`biocLite'} with \emph{`getBioC'}:

\begin{Schunk}
\begin{Sinput}
> source("http://bioconductor.org/getBioC.R")
> getBioC()
\end{Sinput}
\end{Schunk}

Once packages have been installed, they must be loaded into the R environment to allow use of the methods contained within the package. This must be done at the start of every session. To do this, use the \texttt{library()} method. e.g. To load package \textbf{affy}, type the following into the command line:

\begin{Schunk}
\begin{Sinput}
> library("affy")
\end{Sinput}
\end{Schunk}

Packages can also be downloaded, installed and loaded from the `\emph{Packages}' tab at the top of the R shell. Selecting `\emph{Install package(s)}' brings up a list of available mirrors for the CRAN depository. Select the most suitable mirror, and a list of available packages is displayed. Simply select the package of interest and choose '\emph{OK}'. The package will be downloaded and installed automatically. Selecting `\emph{Load package\ldots}' brings up a list of packages available to be loaded. Selecting the required package and selecting `\emph{OK}' has the same effect as using the \texttt{library()} function.

Bioconductor packages are well documented, with help files available for all user-level functions. Every package contains at least one \emph{vignette}, an executable document consisting of a collection of code and documentation text, providing information regarding usage of the package. These vignettes can be found in the \emph{doc} subdirectory of an installed package, or can be called from the R command line using the \texttt{openVignette()} method from the Biobase package. To view documentation for package \textbf{affy}, type the following into the command line:

\begin{Schunk}
\begin{Sinput}
> library("Biobase", "affy")
> openVignette(package = "affy")
\end{Sinput}
\end{Schunk}

Help files for particular methods can be called internally within R by using the following methods, replacing `\texttt{affy}' with the name of the required method:

\begin{Schunk}
\begin{Sinput}
> help.start()
> help.search("affy")
> help(affy)
> `?`(affy)
> apropos(affy)
> example(affy)
> demo()
> demo(affy)
\end{Sinput}
\end{Schunk}

\subsubsection{Installing Additional Required Packages in R}
\textbf{Envisage} requires the following additional packages which can be obtained from Bioconductor as previously described:
\begin{description} 
\item [\textbf{multtest}] Multiple testing procedures for controlling the family-wise error rate (FWER) and false discovery rate (FDR) 
\item [\textbf{GeneSpring (OPTIONAL)}] Package for creating \emph{ExpressionSet} object from GeneSpring GX experiment interpretations
\item [\textbf{tcltk}] Package for integration of Tcl/Tk libraries and widgets within the R environment
\item[\textbf{tkWidgets}] Package containing R based widgets from the Tcl/Tk libraries
\end{description} 

\textbf{Envisage} also requires the following additional packages which can be obtained from the comprehensive R archive network (CRAN) by going to the CRAN website at \href{http://www.r-project.org/}{http://www.r-project.org/}, selecting ``\texttt{CRAN}'' under `downloads', and selecting a CRAN mirror site from the ones available. Available packages can be obtained by clicking on ``\texttt{Contributed extension packages}'':
\begin{description}
\item [\textbf{car}] Package accompanying J. Fox, \emph{An R and S-PLUS Companion to Applied Regression} (2002) and contains functions for applied regression, linear models, and generalized linear models, including the method \texttt{Anova()} which allows Type II ANOVA testing.
\end{description}
%%%
%%%
%%%
\subsubsection{Installing Envisage in R}
\textbf{Envisage} is available as a package within Bioconductor and can be installed directly through the R shell from the `\emph{Packages}' tab as described previously in section \ref{sec:Bioc}. Alternatively, the package source files can be obtained from the author's website at \href{http://www2.warwick.ac.uk/fac/sci/moac/currentstudents/2003/sam\_robson/linear\_models/downloads/}{www2.warwick.ac.uk\-/fac\-/sci\-/moac\-/currentstudents\-/2003\-/sam\_robson\-/linear\_models\-/downloads/}. To install the package in R, please do one of the following:

\begin{description}
  \item[UNIX/LINUX] To install the \textbf{Envisage} source file (\texttt{.tar.gz}), first ensure that your \texttt{.../R/bin/} path is included in your PATH environment variable, and type the following into the terminal: ``R CMD INSTALL [full path to source tar.gz file]''. 
  \item[WINDOWS] To install the \textbf{Envisage} binary file on a machine running windows (\texttt{.zip})go to the `\emph{Packages}' tab and select `\emph{Install package(s) from local zip files...}'. Navigate to the destination folder to which the \textbf{Envisage} .zip file has been saved and select it. R will install the package automatically.
\end{description}

 To load the package in R, simply use the \texttt{library()} method:

\begin{Schunk}
\begin{Sinput}
> library(Envisage)
\end{Sinput}
\end{Schunk}
%%%
%%%
%%%
\subsubsection{Installing Tcl/Tk}
The graphical interface for \textbf{Envisage} has been developed using the R based integration of Tcl/Tk developed by Peter Dalgaard in the \textbf{tcltk} package. This package can be installed directly through the R shell from the `\emph{Packages}' tab as described previously in section \ref{sec:Bioc}. The \textbf{Envisage} GUI also uses widgets that are currently only implemented through the \textbf{BWidgets} and \textbf{Iwidgets} Tcl/Tk packages that are currently not supported by \textbf{tcltk}. To allow integration of R with these packages, users must install a current version of Tcl/Tk, such as the ActiveTcl distribution from ActiveState\footnote{\href{http://www.activestate.com}{www.activestate.com}}. The following is a step-by-step guide to installing ActiveTcl and loading the \textbf{BWidgets} and \textbf{Iwidgets}package for use in R:

\begin{enumerate}
\item Download the current distribution of ActiveTcl (release 8.4.16) free from the developer's website at \href{http://www.activestate.com/Products/activetcl/}{www.activestate.com\-/Products\-/activetcl/}.
\item Install ActiveTcl as instructed.
\item \textbf{For Windows}

Go to your computers advanced system settings and select `\emph{Environmental Variables}'. Under \texttt{System Variables}, select `\emph{New...}' to create a new environment variable called \texttt{MY\_TCLTK} with value `\texttt{yes}'.

\textbf{For LINUX}

Create a new global environment variable called \texttt{MY\_TCLTK} with value `\texttt{yes}' by updating your profile file (eg .bash\_profile) by typing the following into the shell:

export MY\_TCLTK = ``yes''

\item Repeat the above to create a new environment variable called \texttt{TCL\_LIBRARY} and set the value to the library path of your installation of ActiveTcl (e.g. ``\texttt{C:/Tcl/lib}'' if you keep the default settings).
\item In R, use the \texttt{addTclPath(path)} method to tell R where to find the ActiveTcl library files, where \texttt{path} is the library path of your installation of ActiveTcl (e.g. ``\texttt{addTclPath(`C:/Tcl/lib')}'' if you keep the default settings).
\end{enumerate} 

You will now be able to use widgets from all packages contained in the full version of Tcl/Tk. 
%%%
%%%
%%%
\subsubsection{(OPTIONAL) Installing GeneSpring-R Integration External Program Interface} \label{sec:GSepi}
A script is available for those using Genespring GX for analysis of their microarray data, which allows use of the \textbf{Envisage} package from within the Genespring GX environment. This script will export the selected experiment interpretation and gene list into an R environment, and use these to create a Bioconductor \emph{ExpressionSet} object. 

Genespring GX uses an External Program Interface (EPI) to allow interaction between the Genespring GX environment and the R environment. A file, \texttt{GS\_R\_in.txt}, is created in the Genespring GX \emph{`Data'} folder, and the batch file \texttt{GS\_exec\_R\_GUI.bat} opens the R environment directly. The function \texttt{GSload.int} in package \textbf{GeneSpring} can be called on the input file \texttt{GS\_R\_in.txt} to load the Genespring GX experiment interpretation as an object of class \texttt{GSint}. This can be converted directly to an object of class \emph{ExpressionSet} using the \textbf{GeneSpring} function \texttt{GSint2BC()}. 

Note: The current \texttt{GSint2BC()} is defunct since it still uses the old \texttt{exprSet} class for Bioconductor objects. The \textbf{Envisage} package contains a modified function, \texttt{GS2BC}, which has been updated to create a Bioconductor object of class \emph{ExpressionSet}.

The R script \texttt{Envisage.R} runs the function \texttt{Envisage()} on the GeneSpring \texttt{ExpressionSet} object. Output genelists are returned in a tab-delimited text format as described in section \ref{sec:output} that can be read into the GeneSpring environment using the `\emph{Load Gene List From File}' and `\emph{Load Gene List With Numbers From File}' JAVA class external plugins. These are included in the Genespring-R integration package, and can be found in the \emph{`External Programs'} folder to the left of the main Genespring GX window).

The following is a step-by-step guide to installing the GeneSpring-R Integration EPI to allow analysis of microarray data using \textbf{Envisage} directly through GeneSpring GX:

\begin{enumerate}
\item Download the \textbf{Genespring-R} integration package \emph{.zip} file from the Agilent website using one of the following links: 

\begin{itemize}
\item For WINDOWS including R program (2.1.0) and BioConductor \& GeneSpring library -- \href{http://www.chem.agilent.com/cag/bsp/SiG/Downloads/zip/gs\_r\_winall.zip}{www.\-chem.\-agilent.\-com\-/cag\-/bsp\-/SiG\-/Down\-loads\-/zip\-/gs\_r\_winall.zip}
\item For WINDOWS NOT including R program or any library -- \href{http://www.chem.agilent.com/cag/bsp/SiG/Downloads/zip/gs\_r\_win.zip}{www.\-chem.\-agilent.\-com\-/cag\-/bsp\-/SiG\-/Downloads\-/zip\-/gs\_r\_win.zip}
\item For UNIX NOT including R program or any library -- \href{http:///www.chem.agilent.com/cag/bsp/SiG/Downloads/zip/gs\_r\_unix.zip}{www.\-chem.\-agilent.\-com\-/cag\-/bsp\-/SiG\-/Downloads\-/zip\-/gs\_r\_unix.zip}
\end{itemize}

\item Unzip the \textbf{Genespring-R} integration package directly in Genespring GX by dragging the \emph{.zip} file into any active Genespring GX window. Follow the setup procedure as instructed. 

\item Download and install the \textbf{GeneSpring} Bioconductor package from the Bioconductor website as described in section \ref{sec:Bioc}.

\item Download the files \texttt{Envisage.programdef} and \texttt{Envisage.R} from the author's website at  \href{http://www2.warwick.ac.uk/fac/sci/moac/currentstudents/2003/sam\_robson/linear\_models/downloads/}{www2.warwick.ac.uk\-/fac\-/sci\-/moac\-/currentstudents\-/2003\-/sam\_robson\-/linear\-\_models\-/downloads/}. The \texttt{Envisage.programdef} file should be added to the \emph{``\ldots/Agilent/\-Genespring GX/\-data/\-Programs''} folder, and the \texttt{Envisage.R} file should be added to the \emph{``\ldots/Agilent/\-Genespring GX/\-data''} folder. Upon loading Genespring GX, the external program \textbf{Envisage} will be available from the \emph{``External Programs''} folder (see figure \ref{fig:GS}).
\end{enumerate}

\begin{figure}
\centerline{
    \includegraphics[width=100mm]{GS.png}
}
\caption{Selecting Envisage from Genespring GX.}
\label{fig:GS}
\end{figure}
%%%
%%%
%%%
\subsection{Requirements}
The following are required for package \textbf{Envisage}:
%%%
%%%
%%%
\begin{itemize}
\item R version 2.6.1 or higher
\item Bioconductor version 1.9 or higher
\item tkWidgets version 1.16.0 or higher
\item R packages \textbf{tcltk, car}
\item Bioconductor packages \textbf{affy, multtest}
\item Bioconductor package \textbf{GeneSpring} (if pre-processing data using Genespring GX)
\item tcl packages \textbf{BWidgets} and \textbf{Iwidgets} (available as part of \href{http://www.activestate.com/products/activetcl/}{ActiveTcl}.)
\end{itemize}
%%%
%%%
%%%
\subsection{Data Pre-Processing}
Pre-processing and sample quality control must be carried out before using \textbf{Envisage} to avoid biasing the modelling procedures. This can be performed in Bioconductor, or within the gene expression analysis suite GeneSpring GX. The modelling procedure uses log-transformed gene expression data. In this way, the additive linear model corresponds to a multiplicative model on the original non-logged expression values. \textbf{Envisage} will automatically adjust the gene expression data if it is not log-transformed, but users are encouraged to perform this step before beginning the procedure.

It is also recommended that in the quality control step, appropriate normalisation steps are used to limit the effects of outlying samples. It is left to the user to decide the level to which this quality control is performed. Quality control of genes should also be carried out across the samples, firstly to limit the number of genes used in the calculation (thus saving on run-time), and secondly to ensure that erroneous genes do not elicit a significant effect. For instance, non-changing genes should be removed from the experiment interpretation to avoid biasing in the multiple testing correction stage.

The \emph{ExpressionSet} class is the basic container of microarray data within Bioconductor and contains the following slots:

\begin{description}
\item[\texttt{phenoData}] Variable information describing the phenotype for a microarray sample (such as age, weight, treatment, etc.). This is stored as an object of class \texttt{AnnotatedDataFrame}, which itself contains two slots; the \texttt{phenoData} slot containing the phenotype data, and the \texttt{varMetaData} slot containing information about the phenotype variables. See \texttt{help(class:AnnotatedDataFrame)} for more details.
\item[\texttt{experimentData}] Experimental information required for MIAME compliance \citep[see][]{MIAME}. See \texttt{help(class:MIAME)} for more details.
\item[\texttt{annotation}] Label associated with experiment annotation.
\item[\texttt{exprs}] A matrix of gene expression values for each sample.
\end{description}

These slots can be filled either directly in Bioconductor, using the \textbf{affy} package for 1-colour data, or the \textbf{marray} package for 2-colour data (for further assistance on data pre-processing in Bioconductor, please see the appropriate package vignette), or by using the GeneSpring-R integration EPI as described previously in section \ref{sec:GSepi}.
%%%
%%%
%%%		Chapter 3: Running Envisage
%%%
%%%
\newpage
\section{Running Envisage} \label{sec:program}
\subsection{Initialisation of Envisage}
\subsubsection{Initialising Envisage from Bioconductor} \label{sec:programBC}
To run \textbf{Envisage} from Bioconductor, follow these steps:

\begin{enumerate}
\item Load the R environment as normal. Create an object of class \emph{ExpressionSet} containing all of your experiment data (for instance, for Affymetrix data use the \texttt{ReadAffy()} function from package \textbf{affy} to load in information from the experiment \texttt{.CEL} files). 
\item Ensure that package \textbf{Envisage} has been correctly installed and load it as described in section \ref{sec:Bioc}.
\item Either load the \textbf{Envisage} GUI by using the function call \texttt{envisage()} with argument \texttt{widget} set to TRUE:


\begin{Schunk}
\begin{Sinput}
> envisage(expData, widget = TRUE)
\end{Sinput}
\end{Schunk}

Or run \texttt{envisage()} through the command line by setting the argument \texttt{widget} to FALSE and providing further arguments as described in section \ref{sec:ArgInfo}. \emph{`expData'} is the name of the experiment \emph{ExpressionSet} object for analysis. Use of the \textbf{Envisage} GUI is described in section \ref{sec:GUI}.

If the GUI is used, the results will be assigned to a global variable `\texttt{results}' so please be sure that this will not overwrite any other objects within the R environment. If using \texttt{envisage()} through the command line, users can assign the results to an object of their choice.
\end{enumerate}
%
%
%
\subsubsection{Initialising Envisage from Genespring} \label{sec:programGS}
To run \textbf{Envisage} from GeneSpring GX, follow these steps:

\begin{enumerate}
\item Ensure that the \textbf{GeneSpring} Bioconductor package has been downloaded and installed as described in section \ref{sec:Bioc}. 
\item Ensure that the \texttt{Envisage.programdef} and \texttt{Envisage.R} files have been downloaded and installed as described in section \ref{sec:GSepi}.
\item Ensure that the Genespring-R integration package has been downloaded and installed as described in section \ref{sec:GSepi}.
\item Load the Genespring GX environment as normal. Ensure that \emph{`Envisage'} is available from the \emph{`External Programs'} folder (figure \ref{fig:GS}).
\item Select your normalised experiment interpretation and curated gene list and ensure that the \emph{`All Samples'} experiment interpretation is selected. Selecting the \emph{`All Samples'} interpretation ensures that samples are not grouped.
\item Finally, select the \emph{Envisage} icon in the \emph{`External Programs'} drop-down menu to the left of the interpretation view window. This will load the \textbf{Envisage} GUI, as described in section \ref{sec:GUI}.
\end{enumerate}

\subsection{Envisage Graphical User Interface} \label{sec:GUI}
\textbf{Envisage} utilises a graphical user interface (GUI) for input of arguments to the \texttt{envisage()} method. This prevents errors in argument input.  

\begin{figure}
\centerline{
    \includegraphics[width=100mm]{EnvisageGUI.png}
}
\caption{The Envisage GUI.}
\label{fig:GUI}
\end{figure}

\subsubsection{Selection of Variables Classes}
The main GUI window (figure \ref{fig:GUI}) lists the experiment interpretation variables, and allows the user to specify which of these to use in the model calculations, and what class of variable they are. The experiment interpretation may contain several variables that contain identical information (for instance, one variable may contain a range of values, and another may contain the averages of those ranges). Any such correlated variables are flagged with star symbols (`*', `**', `***', etc) which should not be confused with similar flags used for significance in ANOVA tables. Only one of these highly correlated variables should be used in the modelling procedure to avoid overfitting of the data, so users should be sure to select \texttt{`None'} for all but at most one variable flagged with the same number of stars. Selecting more than one may result in overfitting of the data and errors in the hypothesis tests.

Users must specify the class of each of the variables to be used in the model by using the variable class radio buttons. By default, \texttt{None} is selected for all variables. Selecting \texttt{None} prevents a variable from being included in the modelling procedure. The two available classes are \texttt{numeric}, for variables where each value has a numerical relevance (e.g. weight, height, etc.), and \texttt{categoric}, for variables that have a small number of specific factor levels (e.g. gender, disease state, etc.). Choosing the correct class for each of the variables is essential for the modelling procedure. Selecting an incorrect class can result in the modelling procedure failing.

The automated model selection process occurs in two steps. The first step optimises a model with only main effect terms to find those variables that have the greatest effect on the data. The second step calculates a model including first order interactions for the variables from the main effect model. However, the user can choose to consider only main effect terms if necessary. This may be done as a preliminary observation to see which variables are of interest, or possibly because the number of samples is low compared to the number of variables of interest, providing few degrees of freedom for the model. 

If the user chooses to look at interaction terms, but there are too many variable terms compared to the number of samples, the user will be prompted to remove some variables from the first order interaction calculations (figure \ref{fig:INTselect}). The number of degrees of freedom for the fitted model is dependent on the number of samples, so the size of the experiment will determine the variables that can be included. If some categoric variables have a particularly large number of levels, it is recommended to remove these from the interaction calculations to avoid over-fitting of the data.

To ensure that variable names do not cause an internal error within R, they may be renamed by the program to ensure compatability. For instance, R does not like objects to have names beginning with a numeric character (e.g. `\texttt{2-Cycle batch}'). If such a name is discovered, it will be prefixed with the letter `\texttt{X}' to prevent errors. Also, any hyphens, slash characters or spaces will be removed and replaced with the character '\texttt{\_}' for the same reason.

\begin{figure}
\centerline{
    \includegraphics[width=50mm]{INTselect.png}
}
\caption{Selection of variables for which to calculate interactions.}
\label{fig:INTselect}
\end{figure}

\subsubsection{Envisage GUI Arguments}
\begin{description}
\item [Multiple Testing Correction] A number of multiple testing correction algorithms are available for use with the \textbf{Envisage} package. They are called through the Bioconductor package \textbf{multtest}. More information can be obtained by reading the \textbf{multtest} package vignette. It is suggested that a multiple testing correction procedure is used due to the large number of genes being analysed. A list of available multiple testing corrections can be found in section \ref{sec:ArgInfo}). A false discovery rate correction is recommended, and the method of Benjamini and Hochberg is selected by default ~\cite{BH}.

\item [Model Terms] The user can choose to model only main effect terms with no interactions. If there are a large number of variables to model compared to the number of samples, this may be a useful preliminary analysis to find the most significant variables which may then be used with interactions. 

\item [Starting Model] If users have some idea of the variables that they would like to see in the per-gene model, they can specify the minimum model to force these terms to be present for all genes. In this way, the effect of variables of interest to the user can be studied whilst allowing for leeway in the selection of further terms for each gene. Variables are identified by a number with the prefix `p'. These identifiers are used to specify the model. For instance, if you want to force variables `p1' and `p2' into the per-gene model, type `p1 + p2' into the appropriate field. The syntax for this field follow the usual standards for model entry, with `+' indicating inclusion of a variable, `:' indicating an interation between two or more variables, and `*' indicating the inclusion of two or more variables and all possible interactions (e.g. ``A*B'' = ``A + B + A:B'').

\item [P-Value Cutoff] The \emph{p-Value Cutoff} defines the significance cutoff for the type II ANOVA tests. A default of 0.05 is used by convention. 

\item [Results folder] Finally, the folder in which to save the output files (described in section \ref{sec:output}) can be specified. A new folder named \emph{EnvisageResults} is created within the specified directory, containing all of the \textbf{Envisage} output files.

\end{description}
%
%
%
\subsection{Envisage Output} \label{sec:output}
Once the modelling procedure is completed, results are output for significantly changing genes for each term within the analysis. If the GUI is used, a new window is created (figure \ref{fig:output}) allowing the user to specify for which of the variables (and subsequent first-order interactions) to output the results. If the output directory \emph{EnvisageResults} contains files from a previous analysis, these will be suffixed with the letters \texttt{\_OLD} to avoid overwriting data.

\begin{figure}
\centerline{
    \includegraphics[width=80mm]{EnvisageOutput.png}
}
\caption{The Envisage output selection GUI.}
\label{fig:output}
\end{figure}

For each model term, the column \emph{`All Changing Genes'} gives the percentage of the genes that show the term as significant in the model. The column \emph{`Significantly Changing Genes'} gives the percentage of all genes that change significantly and also have a corrected p-value less than the specified cutoff range. These values give the user a brief idea as to which of the model terms have a significant effect on the gene expression. 

Tick the boxes for all model terms that you require results for and press \emph{OK} (selecting `\emph{Check All}' will output all significant results). This will save the gene names and corresponding p-values into a tab-delimited text format in the folder \emph{EnvisageResults} in the specified folder. These files are named based on the variable names. Any spaces in the variable names are replaced by `\_' to ensure file name compatability. Due to the convention of specifying the interaction of two variables using a colon (e.g. \texttt{param1:param2}), which is not a valid character for specifying filenames, it is replaced by the characters \emph{`\_INT\_'}.

The \emph{EnvisageResults} folder also contains information regarding genes that show problems in the ANOVA tests. We can see aliasing errors in the ANOVA calculation for interactions due to one of two reasons:

\begin{enumerate}
\item Extrinsic aliasing is due to the structure of the data -- There is no relevant data for a particular interaction group (e.g. there are no diseased patients in a particular age group, so the effects for the interaction \emph{diseased:age} cannot be estimated).
\item Intrinsic aliasing is due to the structure of the data -- Particular effects cannot be separated adequately (e.g. all diseased individuals in a particular age group also have the same blood group. In this case we cannot separate the effects in \emph{diseased:age} and \emph{diseased:blood group}).
\end{enumerate}

Extrinsic aliasing will generally occur due to the use of an unbalanced data set, but will not cause a problem with the significance calculations. Intrinsic aliasing is indicative of correlation between explanatory variables. So the model will fit one variable and then try to fit the same information again with the second variable. This may then pose a problem since the significance results will depend on the order in which the terms are fitted. 

The two files produced, \emph{AliasGenes} and \emph{AliasReport}, give information on the genes showing intrinsic aliasing. \emph{AliasGenes} is a list of the aliased genes in a tab-delimited text file. \emph{AliasReport} gives more detailed information showing exactly which of the variable levels are aliased. This may be useful for users to spot correlation between their variables that may be unexpected. Users may wish to run the program a second time with one of the two aliased variables removed.

If for some reason a gene gives a model for which the ANOVA calculation fails, the name of the gene is output to a file called \emph{FailedAnova}. This file should generally be absent.
%%%
%%%
%%%		Chapter 4: Program Specifications
%%%
%%%
\newpage
\section{Program Specifications}
%
\subsection{User Methods}
The following methods are available for users:
\begin{description}
\item[\textbf{envisage}] This is the main function for the \textbf{Envisage} package. It takes in microarray gene expression data and variable phenodata in the form of a Bioconductor object of class \emph{ExpressionSet}, and returns a list of genes that vary significantly based on the experiment variables and their first-order interactions.

\item[\textbf{GS2BC}] Updated version of the \texttt{GSint2BC()} function from package \textbf{GeneSpring} which converts GeneSpring experiment interpretation data into an object of class \emph{Express\-ionSet} for use with \textbf{Envisage}.
\end{description}
%%%
%%%
%%%
\subsection{envisage() Argument Definition} \label{sec:ArgDef}
The following arguments are required for the user-level function \texttt{envisage()}:
\begin{description}
\item[\textbf{expData}] The data construct, of class \emph{ExpressionSet}, containing all gene expression and phenotypic data for the experiment. 
\item[\textbf{widget}] A logical value specifying whether or not to use the widget based GUI for argument specification. This is set to \texttt{TRUE} by default.
\item[\textbf{MTC}] Multiple testing correction to use for correcting calculated p-values (see section \ref{sec:ArgInfo}).
\item[\textbf{pCutoff}] A number defining the p-value cutoff to be used in significance analysis.  Must be between 0 and 1.
\item[\textbf{useParams}] A character vector that defines which of the experiment variables to use in the model calculation.
\item[\textbf{param4INT}] A character vector that defines the model variables for which interactions should be calculated.
\item[\textbf{paramType}] A character vector specifying the classes (``\emph{numeric}'' or ``\emph{categoric}'') of the variables in the model.
\item[\textbf{fileResults}] A character string defining the folder in which to save the results of the modelling procedure.
\item[\textbf{MEorINT}] A character string defining whether to consider only main effect terms in the model(``\emph{ME}''), or to look at first order interactions(``\emph{INT}'').
\item[\textbf{startModel}] A character string representing the starting model for analysis. Must be of the form ``$x \sim term1 + term2 + term1:term2 + $ \ldots''. Care must be taken to ensure that the model terms match the names of variables specified in \texttt{useParams}.
\end{description}

The following are the default argument terms:

\begin{Schunk}
\begin{Sinput}
> envisage(expData, widget = TRUE, MTC = NULL, pCutoff = NULL, 
+     useParams = NULL, param4INT = NULL, paramType = NULL, fileResults = getwd(), 
+     MEorINT = "INT", startModel = NULL)
\end{Sinput}
\end{Schunk}

The following function call is sufficient if you want to run \textbf{Envisage} using the GUI:

\begin{Schunk}
\begin{Sinput}
> envisage(expData)
\end{Sinput}
\end{Schunk}

\subsection{envisage() Argument Information} \label{sec:ArgInfo}
The following information is necessary when defining the arguments for \texttt{envisage()}:
\begin{description}
\item[\textbf{expData}] Try to ensure that explanatory variables are labelled sensibly. Avoid beginning variable names with a numeric character and using special characters in variable names. \textbf{Envisage} contains several basic internal functions for renaming variables to avoid these problems, but this should be considered by the user. Spaces are acceptable in variable names, but will be replaced by an underscore in output files.
\item[\textbf{widget}] Default is `\texttt{TRUE}'. If set to \texttt{FALSE}, great care must be taken to ensure that other variables are correctly implemented.
\item[\textbf{MTC}] Multiple testing corresction procedures are implemented through the package \textbf{multtest}. Available multiple testing procedures are as follows:
\begin{enumerate}
\item ``\textbf{NA}'' -- No MTC selected
\item ``\textbf{BH}'' -- (Default) Benjamini \& Hochberg step-up false discovery rate (1995)~\cite{BH}
\item ``\textbf{BY}'' -- Benjamini \& Yekutieli step-up false discovery rate (2001)~\cite{BY}
\item ``\textbf{Bonferroni}'' -- Bonferroni single-step family wise error rate
\item ``\textbf{Holm}'' -- Holm step-down family wise error rate (1979)~\cite{Holm}
\item ``\textbf{Hochberg}'' -- Hochberg step-up family wise error rate (1988)~\cite{Hochberg}
\item ``\textbf{SidakSS}'' -- Sidak single-step family wise error rate
\item ``\textbf{SidakSD}'' -- Sidak step-down family wise error rate
\end{enumerate}

\item[\textbf{pCutoff}] Must be between $0$ and $1$. Default is $p=0.05$.
\item[\textbf{useParams}] Users must ensure that no labelling variables are included in the list of variables to use. Users must also ensure that only one of any group of highly correlated variables is used, so be careful to select variables for modelling that represent different aspects of the data. Also be careful to ensure constant naming for all variables. This problem can be avoided by using the \textbf{Envisage} GUI.
\item[\textbf{param4INT}] Be careful to ensure constant naming with variables specified in the \texttt{useParams} argument. This problem can be avoided by using the \textbf{Envisage} GUI.
\item[\textbf{paramType}] Variable class must be one of ``numeric'' or ``categoric''. Users must be sure that the order of the variable classes is correct to ensure that variables are assigned the correct class. Assigning the wrong class to a variable can have a dramatic impact on the modelling procedure. This problem can be avoided by using the \textbf{Envisage} GUI.
\item[\textbf{fileResults}] Default is the working directory for R. Be sure to choose a directory that can be accessed.
\item[\textbf{MEorINT}] Default is ``\texttt{INT}''. 
\item[\textbf{startModel}] This argument allows the user to specify a minimum model for use in the modelling procedure to force terms into the selected model. This model must be specified as a character string of the form ``$x \sim term1 + term2 + term1:term2 + $ \ldots'', which will be converted internally to an object of class formula. Care must be taken to ensure that the model terms match the names of variables specified in \texttt{useParams}.
\end{description}
%%%
%%%
%%%
\subsection{Non-User Methods}
The following methods are called by the user-level function \texttt{envisage()}, and should not be directly called by the user:
\begin{description}
\item[\textbf{envisage.data}] This function takes the experiment data and extracts all relevant information (gene names, variable names, gene expression levels, etc) and assigns them to individual objects in R for future use. This function also ensures that the gene expression data is logged, so \texttt{envisage()} can take both logged and non-logged data as its argument.

\item[\textbf{alias.glmNA}] This function directly extends the function \texttt{alias()} to objects of class \texttt{glmNA}. Class \texttt{glmNA} directly extend the classes \texttt{lm} and \texttt{glm} to objects that show aliasing in the modeling procedure. This allows the use of the type II ANOVA function.

\item[\textbf{coef.glmNA}] This function directly extends the function \texttt{coef()} to objects of class \texttt{glmNA}. Class \texttt{glmNA} directly extend the classes \texttt{lm} and \texttt{glm} to objects that show aliasing in the modeling procedure. This allows the use of the type II ANOVA function.

\item[\textbf{corParams}] This function flags highly correlated variables that may model the same information in the model. Parameters showing a correlation greater than 0.98 are flagged.

\item[\textbf{labelParams}] This function removes any labelling variables (variables whereby each sample has a unique value) from the experiment interpretation.

\item[\textbf{modelCalcME}] This function uses a stepwise method to fit a linear model for each gene based on main effect variables. 

\item[\textbf{modelCalcINT}] This function takes the main effect model of \texttt{modelCalcME} and uses only the significant terms to fit a linear model including first-order interaction terms in a stepwise process for each gene. A type II ANOVA calculation is used to calculate significance p-values for each model term based on an F-statistic.

\item[\textbf{mulTestCor}] This function corrects the p-values for the type II ANOVA based on the specified multiple testing correction.

\item[\textbf{result.output}] This function compares the significance p-values for each gene and variable with the specified p-value cutoff. If a gene has a p-value within the limit for a particular variable or interaction, then that gene is added to a gene list for the variable. These gene lists are output to a folder specified by the user. 

\item[\textbf{INTlevels}] This function calculates the number of levels for each main effect and first-order interaction term in the linear model. This is used to check model degrees of freedom against available degrees of freedom.

\item[\textbf{modelEntry}] This function allows users to specify a minimum model for the model selection process.  

\end{description}
%%
%%
%%
\subsection{S3 Classes}
The following classes are defined in the package \textbf{Envisage}:
\begin{description}
\item[\textbf{class-glmNA}] Class \texttt{glmNA} directly extend the classes \texttt{lm} and \texttt{glm} to objects that show aliasing in the linear model.
\end{description}
%%%
%%%
%%%
%%%
%%%
%%%		Chapter 5: Example Envisage session
%%%
%%%
\newpage
\section{An Example Envisage Session} \label{sec:example}
We now demonstrate an example session using an example data set, \texttt{SkinvsPancreas}, available as part of the \textbf{Envisage} package. The example data set is an object of class \emph{ExpressionSet} made up of gene expression levels for 50 probes over 48 individual Affymetrix MOE430 Plus 2 mouse GeneChips. This is a subset of a larger data set for which a large number of experiment variables were recorded (Robson et al., In Preparation). The experiment design is multi-factorial, with 3 main explanatory variables; tissue type (2 levels - skin and pancreas), time point after activation of the Myc protein (4 levels - 4, 8, 16 and 32 hours) and status of the Myc transgene (2 levels - Myc ON or Myc OFF). Three batching variables correspond to batching of samples at the tissue extraction stage, RNA extraction stage and the microarray hybridisation stage. Further experiment information, such as RNA quality and yield, was collected providing a total of 12 variables. This data set is thus well suited for use with \textbf{Envisage}.

The first step is to load the package into R, then load the example data set:

\begin{Schunk}
\begin{Sinput}
> library("Envisage")
> data(SkinvsPancreas)
\end{Sinput}
\end{Schunk}

This will load the example \emph{ExpressionSet} object \texttt{SkinvsPancreas} into the R environment:

\begin{Schunk}
\begin{Sinput}
> SkinvsPancreas
\end{Sinput}
\begin{Soutput}
ExpressionSet (storageMode: lockedEnvironment)
assayData: 50 features, 48 samples 
  element names: exprs 
phenoData
  rowNames: 1, 2, ..., 48  (48 total)
  varLabels and varMetadata description:
    Sample name: Sample name
    Treatment: Treatment
    ...: ...
    Myc ON/OFF: Myc ON/OFF
    (12 total)
featureData
  featureNames: 1416783_at, 1416780_at, ..., 1416685_s_at  (50 total)
  fvarLabels and fvarMetadata description: none
experimentData: use 'experimentData(object)'
Annotation:  
\end{Soutput}
\end{Schunk}

Parameter names can be seen by looking at the \texttt{phenoData} slot of \texttt{SkinvsPancreas}:

\begin{Schunk}
\begin{Sinput}
> names(pData(SkinvsPancreas))
\end{Sinput}
\begin{Soutput}
 [1] "Sample name"      "Treatment"        "RIN"              "Nanodrop Conc."  
 [5] "Tissue batch"     "RNA batch"        "2-Cycle batch"    "Starting cRNA"   
 [9] "Tissue"           "Time point"       "Replicate Number" "Myc ON/OFF"      
\end{Soutput}
\end{Schunk}

\subsection{Using the GUI}
First, we will look at an example of how to run \texttt{envisage()} using the GUI:

\begin{Schunk}
\begin{Sinput}
> envisage(SkinvsPancreas)
\end{Sinput}
\end{Schunk}

The GUI should appear as in figure \ref{fig:GUI}. It is worth noting that several of the variable names have been renamed from their original names:

\begin{enumerate}
\item \textbf{2-Cycle batch} -> X2\_Cycle\_batch
\item \textbf{Myc ON/OFF} -> Myc\_ON\_OFF
\end{enumerate}

The variable \texttt{Sample name} has unique values for each sample as shown below, so is classed as a labelling variable. Any such variables should be removed from the modelling process to avoid overfitting of the data, or alternatively users must be sure that the variables are selected as numeric, and not categoric. Selecting any of these variables for use in the model as a categorical variable results in an error message to limit accidental assignment by the user.

\begin{Schunk}
\begin{Sinput}
> nlevels(pData(SkinvsPancreas)$"Sample name")
\end{Sinput}
\begin{Soutput}
[1] 48
\end{Soutput}
\begin{Sinput}
> length(sampleNames(SkinvsPancreas))
\end{Sinput}
\begin{Soutput}
[1] 48
\end{Soutput}
\end{Schunk}

We make the following class selections for each variable:

\begin{description}
\item[\textbf{Sample name}] \texttt{None}
\item[\textbf{Treatment}] \texttt{None}
\item[\textbf{RIN}] \texttt{numeric}
\item[\textbf{Nanodrop Conc.}] \texttt{None}
\item[\textbf{Tissue batch}] \texttt{categoric}
\item[\textbf{RNA batch}] \texttt{categoric}
\item[\textbf{2-Cycle batch}] \texttt{categoric}
\item[\textbf{Starting cRNA}] \texttt{numeric}
\item[\textbf{Tissue}] \texttt{categoric}
\item[\textbf{Time point}] \texttt{categoric}
\item[\textbf{Replicate Number}] \texttt{None}
\item[\textbf{Myc ON/OFF}] \texttt{categoric}
\end{description}

The default arguments are kept, which uses a Benjamini \& Hochberg false discovery rate multiple testing correction with a P-value cutoff of 0.05. Results will be saved to a folder in the working directory unless otherwise stated. Pressing `\texttt{OK}' brings up another window confirming the variable classes selected. Click `\texttt{Yes}' to continue. The next window that appears allows users to specify which variables to calculate interaction terms for (figure \ref{fig:INTselect}). For now we leave all variables selected, meaning that all of these will be used to calculate interaction terms. Pressing `\texttt{Ok}' brings up an error message that informs us that we have too many variable terms in our maximum model. We can choose to continue, and risk seeing errors in the analysis due to aliasing, or alternatively we can choose to exclude some variables from the interaction term calculations. The 3 batching variables each have a large number of levels which will have a large effect on the number of residual degrees of freedom. We can safely ignore the interaction terms for these variables, since randomisation of batches should remove significant effects. So press `\texttt{Cancel}', deselect the batch variables and press `\texttt{Ok}'. This will start the modelling process.

Once the program has finished running, the output window shown in figure \ref{fig:output} will appear. By default, all terms are selected which will output results for all variables and interactions to the file selected (the R working directory by default). Alternatively, users can select which terms are of interest to them and output only these gene lists.

\subsection{Using the command line}
The same output can be seen by running the \texttt{envisage()} method through the command line:


\begin{Schunk}
\begin{Sinput}
> useParams <- c("RIN", "Tissue batch", "RNA batch", "2-Cycle batch", 
+     "Starting cRNA", "Tissue", "Time point", "Myc ON/OFF")
> paramType <- c("numeric", rep("categoric", 3), "numeric", rep("categoric", 
+     3))
> param4INT <- c("RIN", "Starting cRNA", "Tissue", "Time point", 
+     "Myc ON/OFF")
> results1 <- envisage(SkinvsPancreas, widget = FALSE, MTC = "BH", 
+     pCutoff = 0.05, useParams, param4INT, paramType, fileResults = getwd(), 
+     MEorINT = "INT")
\end{Sinput}
\end{Schunk}

\subsection{Envisage output}
The results folder \texttt{EnvisageResults} contains the resulting gene lists for the analysis, as well as the 2 alias outputs \texttt{AliasGenes.txt} and \texttt{AliasReport.txt}. These files contain information on genes that show aliasing in the modeling procedure. As we can see, the majority of the 50 genes (34 genes) have shown some problem due to aliasing of the variables used in the analysis, and this may mean that the results of the modeling procedure are affected. By looking at the alias report, we can see that aliasing is seen between the same two variables, \texttt{Tissue} and \texttt{Tissue batch}, for all genes:

\begin{Schunk}
\begin{Sinput}
> names(results1$errorGenes)[1]
\end{Sinput}
\begin{Soutput}
[1] "1416780_at"
\end{Soutput}
\begin{Sinput}
> results1$errorGenes[[1]]
\end{Sinput}
\begin{Soutput}
[1] "TissueSkin & (Intercept)"   "TissueSkin & Tissue_batch2"
[3] "TissueSkin & Tissue_batch3"
\end{Soutput}
\end{Schunk}

Batching for tissue extraction was not randomised, and skin samples were all identified with the tissue batch identifier \texttt{1}. Thus the variable \texttt{Tissue} is in fact a subset of the variable \texttt{Tissue\_batch} which explains the intrinsic aliasing seen. We can therefore repeat the process with the \texttt{Tissue batch} variable removed. After repeating analysis with the \texttt{Tissue batch} variable removed, you will find that the result output file contains only significantly changing lists of genes for several variables in the analysis with no problems due to aliasing.

The resulting gene lists can be used for further analysis.

\newpage
\bibliographystyle{plainnat}
\bibliography{EnvisageBib}

\end{document} 
