\HeaderA{stam.cv}{Cross Validated Training for StAM}{stam.cv}
\keyword{classif}{stam.cv}
\begin{Description}\relax
Determine classifiers in leaf nodes and weights in inner nodes as well as best graph 
shrinkage by cross validated model fitting.
\end{Description}
\begin{Usage}
\begin{verbatim}
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)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{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[\code{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[\code{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[\code{root}] the GO node used as root of the classifier graph. Only successors of this 
node are considered during construction of the graph.
\item[\code{beta}] holds class weights used when judging classifier quality. The default is to 
set class weights to the corresponding prevalence. 
\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{results.per.node}] whether results for each node should be returned
\item[\code{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[\code{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[\code{verbose}] when set to TRUE reports summary on each leaf training, otherwise shows
a progress bar.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\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.
\end{Details}
\begin{Value}
An object of class stamCV is returned. Use the methods print and plot to extract 
information about the cross validation.
\end{Value}
\begin{Author}\relax
Claudio Lottaz
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{stamCV-class}{stamCV.Rdash.class}}, \code{\LinkA{plot.stamCV}{plot.stamCV}}, 
\code{\LinkA{stam.writeHTML}{stam.writeHTML}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Not run: 
# 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)
## End(Not run)
\end{ExampleCode}
\end{Examples}

