stam.evaluate              package:stam              R Documentation

_S_t_A_M _E_v_a_l_u_a_t_i_o_n _P_r_o_c_e_d_u_r_e

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

     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)

_A_r_g_u_m_e_n_t_s:

expression.matrix: holds the expression levels. It may be of class
          'exprSet' or 'ExpressionSet', or a plain numeric matrix. In
          the first case 'exprs' is used to extract the  expression
          levels. The matrix is expected to hold one column per sample
          and one row per probeset.

classifications: This character vector must contain one entry per
          sample  identifying the group it belongs to.

  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.

 testset: indeces of the columns in the expression.matrix representing
          test  samples.

    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.

    root: the GO node used as root of the classifier graph. Only
          successors of this  node are considered during construction
          of the graph/model.

   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.

    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.

  deltas: numeric vector holding graph shrinkage candidates. Default is
          to  determine 'ndelta' candidates between 0 and the lowest
          shrinkage level which  removes all leaf nodes.

 ndeltas: number of automatically determined graph shrinkage candidates
          determined  if 'deltas' is not defined.

titlestem: the first part of the title of the HTML page to be written,
          is  complemented by some of the parameters.

report.dir: the directory where the HTML pages are to be written

no.output: do not generate any HTML or images

 minspec: nodes to be shown in molecular symptoms image must be at
          least this  specific

 minsens: nodes to be shown in molecular symptoms image must be at
          least this  sensitive

 maxsens: nodes to be shown in molecular symptoms image must be at most
          this  sensitive

pamimagefile: When this parameter is specified 'stam.cv' tries to read
          this  file and extract a 'stamCV' object to avoid recomputing
          PAM fits. If the file  does not yet exist, PAM fits are
          stored there after computation.

_D_e_t_a_i_l_s:

     '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.

_V_a_l_u_e:

     Returns an object of class '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.

_A_u_t_h_o_r(_s):

     Claudio Lottaz

_S_e_e _A_l_s_o:

     'stamEval-class', 'stam.cv', 'stam.fit',  'stam.predict',
     'stam.writeHTML'

_E_x_a_m_p_l_e_s:

     # 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)

