\name{stam.evaluate}
\alias{stam.evaluate}
\title{StAM Evaluation Procedure}
\description{
  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. 
}
\usage{
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)
}
\arguments{
  \item{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{classifications}{This character vector must contain one entry per sample 
    identifying the group it belongs to.}
  \item{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{testset}{indeces of the columns in the expression.matrix representing test 
    samples.}
  \item{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{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{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{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{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{ndeltas}{number of automatically determined graph shrinkage candidates determined 
    if \code{deltas} is not defined.}
  \item{titlestem}{the first part of the title of the HTML page to be written, is 
    complemented by some of the parameters.}
  \item{report.dir}{the directory where the HTML pages are to be written}
  \item{no.output}{do not generate any HTML or images}
  \item{minspec}{nodes to be shown in molecular symptoms image must be at least this 
    specific}
  \item{minsens}{nodes to be shown in molecular symptoms image must be at least this 
    sensitive}
  \item{maxsens}{nodes to be shown in molecular symptoms image must be at most this 
    sensitive}
  \item{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.}
}
\details{
  \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.
}
\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.
}
\author{Claudio Lottaz}
\seealso{\code{\link{stamEval-class}}, \code{\link{stam.cv}}, \code{\link{stam.fit}}, 
  \code{\link{stam.predict}}, \code{\link{stam.writeHTML}}}
\examples{
# load and normalize some data
\dontrun{
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)
}}
\keyword{classif}