\HeaderA{stam.evaluate}{StAM Evaluation Procedure}{stam.evaluate}
\keyword{classif}{stam.evaluate}
\begin{Description}\relax
This performs a structured analysis of microarrays (StAM) from scratch to the end. It 
starts with a cross-validation, performas a model fit, predicts phenotypes and writes 
complete HTML code with images.
\end{Description}
\begin{Usage}
\begin{verbatim}
stam.evaluate(expression.matrix, classifications, 
              report.dir = getwd(), aclass = 
              names(table(classifications))[1], 
              titlestem = NULL, testset = 
              stam.balanced.folds(classifications, 3)[[1]], 
              chip = "hgu95av2", root = "GO:0008150", 
              no.output = FALSE, alpha = seq(0, 1, 0.1), 
              beta = NULL, deltas = NULL, ndeltas = 30, 
              minspec = NULL, minsens = 0.1, maxsens = 1, 
              pamimagefile = NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{expression.matrix}] holds the expression levels. It may be of
class \code{exprSet} or \code{ExpressionSet}, or a
plain numeric matrix. In the first case \code{exprs} is used to extract the 
expression levels. The matrix is expected to hold one column per sample and one row
per probeset.
\item[\code{classifications}] This character vector must contain one entry per sample 
identifying the group it belongs to.
\item[\code{aclass}] the name of the phenotype class of interest, usually the disease class. 
If set to NULL the first class in lexicographical order is chosen.
\item[\code{testset}] indeces of the columns in the expression.matrix representing test 
samples.
\item[\code{chip}] the name of the microarray chip. A meta data package of the same name is 
expected to be found holding the needed annotation, namely the links between 
probesets and Gene Ontology nodes.
\item[\code{root}] the GO node used as root of the classifier graph. Only successors of this 
node are considered during construction of the graph/model.
\item[\code{alpha}] root performance vs. mean redundancy weight. If set to NULL the root error
rate is used exclusively to determine the best shrinkage level. If a numeric vector 
is provided, all alternatives are computed and the user is given an interactive 
choice. Values between 0 and 1 are valid, 0 meaning exclusive weight on redundancy 
and 1 putting exclusive weight on performance.
\item[\code{beta}] holds class weights used when judging classifier quality. The default is to
set class weights to the corresponding prevalence. Several combinations of class 
weights may be provided for testing one after the other. To do so a matrix is 
expected to hold one combination of weights per row and must thus have one column per
class.
\item[\code{deltas}] numeric vector holding graph shrinkage candidates. Default is to 
determine \code{ndelta} candidates between 0 and the lowest shrinkage level which 
removes all leaf nodes.
\item[\code{ndeltas}] number of automatically determined graph shrinkage candidates determined 
if \code{deltas} is not defined.
\item[\code{titlestem}] the first part of the title of the HTML page to be written, is 
complemented by some of the parameters.
\item[\code{report.dir}] the directory where the HTML pages are to be written
\item[\code{no.output}] do not generate any HTML or images
\item[\code{minspec}] nodes to be shown in molecular symptoms image must be at least this 
specific
\item[\code{minsens}] nodes to be shown in molecular symptoms image must be at least this 
sensitive
\item[\code{maxsens}] nodes to be shown in molecular symptoms image must be at most this 
sensitive
\item[\code{pamimagefile}] When this parameter is specified \code{stam.cv} tries to read this 
file and extract a \code{stamCV} object to avoid recomputing PAM fits. If the file 
does not yet exist, PAM fits are stored there after computation.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{stam.evaluate} exexutes all steps needed in a structured analysis of a microarray
study and coherently generates HTML output including plots and images. In Firstly, a 10
fold cross validation is performed with the data not identified as test set. Secondly,
using an adequate graph shrinkage level, a model fit is computed. Finally, all data is
used for prediction to illustrate the performance. 

Furthermore, this method generates a set of HTML pages. One page reports on the 
analysis as a whole, while additional interlinked pages, one for each node in the 
model fit, contain information on the fit and results of each node. On the main page
plots and images illustrate and summarize the analysis. Clickable maps make the 
exploration of the results convenient. All files are stored together with an R data
containing the returned R object in the user specified report directory.
\end{Details}
\begin{Value}
Returns an object of class \code{stamEval} containing all results generated during the 
above described procedure. Use the methods defined on the class corresponding the slot
you want to investigat further.
\end{Value}
\begin{Author}\relax
Claudio Lottaz
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{stamEval-class}{stamEval.Rdash.class}}, \code{\LinkA{stam.cv}{stam.cv}}, \code{\LinkA{stam.fit}{stam.fit}}, 
\code{\LinkA{stam.predict}{stam.predict}}, \code{\LinkA{stam.writeHTML}{stam.writeHTML}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
# load and normalize some data
## Not run: 
library(golubEsets)
data(Golub_Merge)

# (root is chosen to yield results reasonably fast, 
#  consider GO:0008150 (biological process) to obtain 
#  meaningful results)

# demonstrate the use of several combinations of class weights
betas <- cbind(c(0.5, 0.8, 0.9), c(0.5, 0.2, 0.1))
golubNorm.eval.explore <- stam.evaluate(Golub_Merge, "ALL.AML", 
                                         chip="hu6800", root="GO:0005576", 
                                         alpha=seq(0, 1, 0.1), beta=betas, ndelta=10)

# demonstrate the use of testsets
golubNorm.eval.predict <- stam.evaluate(Golub_Merge, "ALL.AML", testset=39:72,
                                         chip="hu6800", root="GO:0005576", ndelta=10)
## End(Not run)\end{ExampleCode}
\end{Examples}

