\name{stam.cv}
\alias{stam.cv}
\title{Cross Validated Training for StAM}
\description{
  Determine classifiers in leaf nodes and weights in inner nodes as well as best graph 
  shrinkage by cross validated model fitting.
}
\usage{
stam.cv(expression.matrix, classifications, 
        chip = "hgu95av2", root = "GO:0008150", 
        beta = NULL, deltas = NULL, ndeltas = 10, 
        results.per.node = FALSE, old.cv = NULL, 
        pamimagefile = NULL, verbose = FALSE)
}
\arguments{
  \item{expression.matrix}{holds the expression levels. It may be of
    classes exprSet or 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. Alternatively, if \code{expression.matrix} is 
    an \code{exprSet} or \code{ExpressionSet}, this may be the name of
    a \code{phenoData} variable.}
  \item{chip}{the name of the microarray chip. A meta data package 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.}
  \item{beta}{holds class weights used when judging classifier quality. The default is to 
    set class weights to the corresponding prevalence. }
  \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{results.per.node}{whether results for each node should be returned}
  \item{old.cv}{\code{stamCV} object used to modify when PAM fits need not to be 
    recomputed. E.g. used when only \code{beta} is adapted. }
  \item{pamimagefile}{When this parameter is specified \code{stam.cv} tries to read this 
    file and extract a \code{stamCV} object to be used as \code{old.cv}. If the file does 
    not yet exist, PAM fits are stored there after computation.}
  \item{verbose}{when set to TRUE reports summary on each leaf training, otherwise shows
    a progress bar.}
}
\details{
  \code{stam.cv} uses \code{stam.net} to generate a classifier graph for the microarray 
  chip at hand. It then fits a PAM classifier for each leaf node only considering the 
  probesets annotated to the node. Afterwards, in each inner node, weights are attributed 
  to each child according to the childs classification performance. Finally, the weights 
  are shrunken such that most of them become zero. In fact, the best shrinkage level is 
  chosen in a cross validation setting. 

  Classification performance is evaluated using an inverted deviance like measure which 
  uses weights to overstate specificity of a classifier. Weights for nodes are chosen 
  according to this measure and shrunken by an absolute shrinkage level. For each 
  shrinkage candidate cross validated performance results in terms of graph heterogeneity 
  and classification performance are stored.
}
\value{
  An object of class stamCV is returned. Use the methods print and plot to extract 
  information about the cross validation. 
}
\author{Claudio Lottaz}
\seealso{\code{\link{stamCV-class}}, \code{\link{plot.stamCV}}, 
  \code{\link{stam.writeHTML}}}
\examples{
\dontrun{
# load and prepare some data
library(golubEsets)
data(Golub_Merge)
golubTrain <- Golub_Merge[,1:38]

# classify into ALL and AML
# (root is chosen to yield results reasonably fast, 
#  consider GO:0008150 (biological process) to obtain 
#  meaningful results)
golubTrain.cv <- stam.cv(golubTrain, "ALL.AML", chip="hu6800",
                         root="GO:0005576", ndeltas=10)

# get further information
print(golubTrain.cv)
plot(golubTrain.cv, delta=0.6)
}
}
\keyword{classif}