farms                  package:xps                  R Documentation

_F_a_c_t_o_r _A_n_a_l_y_s_i_s _f_o_r _R_o_b_u_s_t _M_i_c_r_o_a_r_r_a_y _S_u_m_m_a_r_i_z_a_t_i_o_n _E_x_p_r_e_s_s_i_o_n _M_e_a_s_u_r_e

_D_e_s_c_r_i_p_t_i_o_n:

     This function converts a 'DataTreeSet' into an 'ExprTreeSet' using
     the Factor Analysis for Robust Microarray Summarization (FARMS)
     method.

_U_s_a_g_e:

     farms(xps.data,
           filename   = character(0),
           filedir    = getwd(),
           tmpdir     = "",
           normalize  = TRUE,
           weight     = 0.5,
           mu         = 0.0,
           scale      = 1.0,
           tol        = 0.00001,
           cyc        = 100,
           weighted   = TRUE,
           version    = "1.3.1",
           option     = "transcript",
           exonlevel  = "",
           xps.scheme = NULL,
           add.data   = TRUE,
           verbose    = TRUE)

_A_r_g_u_m_e_n_t_s:

xps.data: object of class 'DataTreeSet'.

filename: file name of ROOT data file.

 filedir: system directory where ROOT data file should be stored.

  tmpdir: optional temporary directory where temporary ROOT files
          should be stored.

normalize: logical. If 'TRUE' normalize data using quantile
          normalization.

  weight: hyperparameter, usually set to 0.5 for 'version="1.3.1"' and
          to 8.0 for 'version="1.3.0"'.

      mu: hyperparameter allowing to correct for potential bias.

   scale: scaling parameter, usually set to 1.0 for 'version="1.3.1"'
          and to 2.0 for 'version="1.3.0"'.

     tol: termination tolerance for EM algorithm.

     cyc: maximum number of cycles of EM algorithm.

weighted: logical, used only with 'version="1.3.1"'. Default is TRUE.

 version: version of original farms package. Currently,
          'version="1.3.1"' and 'version="1.3.0"' are implemented.
          Default is 'version="1.3.1"'.

  option: option determining the grouping of probes for summarization,
          one of  'transcript', 'exon', 'probeset'; exon arrays only.

exonlevel: exon annotation level determining which probes should be
          used for summarization; exon/genome arrays only.

xps.scheme: optional alternative 'SchemeTreeSet'.

add.data: logical. If 'TRUE' expression data will be included as slot
          'data'.

 verbose: logical, if 'TRUE' print status information.

_D_e_t_a_i_l_s:

     This function computes the FARMS (Factor Analysis for Robust
     Microarray Summarization) expression  measure described in
     Hochreiter et al. for both expression arrays and exon arrays. 

     Parameter 'version' currently allows the user to choose between
     the original implementation  of FARMS as implemented in package
     'farms_1.3.0' or enhanced FARMS as implemented in  package
     'farms_1.3.1'. By default 'version="1.3.1"' is used.

     Parameter 'weight' is a hyperparameter which determines the
     influence of the prior. For  'version="1.3.1"' the value in the
     range of [0,1]. 

     Parameter 'mu' is a hyperparameter which allows to quantify
     different aspects of potential  prior knowledge. Values near zero
     assume that most genes do not contain a signal and introduce  a
     bias for loading matrix elements near zero. 

     Parameter 'weighted' is a logical and indicates whether a weighted
     mean or a least square  fit is used to summarize the loading
     matrix. It is applicable only to 'version="1.3.1"'. 

     For exon arrays it is necessary to supply the requested 'option'
     and 'exonlevel'.

     Following 'option's are valid for exon arrays:

       'transcript':  expression levels are computed for transcript clusters, i.e. probe sets containing the same 'transcript_cluster_id'.
       'exon':        expression levels are computed for exon clusters, i.e. probe sets containing the same 'exon_id', where each exon cluster consists of one or more 'probeset's.
       'probeset':    expression levels are computed for individual probe sets, i.e. for each 'probeset_id'.

     Following 'exonlevel' annotations are valid for exon arrays:

         'core':          probesets supported by RefSeq and full-length GenBank transcripts.
         'metacore':      core meta-probesets.
         'extended':      probesets with other cDNA support.
         'metaextended':  extended meta-probesets.
         'full':          probesets supported by gene predictions only.
         'metafull':      full meta-probesets.
         'affx':          standard AFFX controls.
         'all':           combination of above (including affx).

     Following 'exonlevel' annotations are valid for whole genome
     arrays:

         'core':      probesets with category 'unique', 'similar' and 'mixed'.
         'metacore':  probesets with category 'unique' only.
         'affx':      standard AFFX controls.
         'all':       combination of above (including affx).

     Exon levels can also be combined, with following combinations
     being most useful:

       'exonlevel="metacore+affy"':       core meta-probesets plus AFFX controls
       'exonlevel="core+extended"':       probesets with cDNA support
       'exonlevel="core+extended+full"':  supported plus predicted probesets

     Exon level annotations are described in the Affymetrix whitepaper
     exon_probeset_trans_clust_whitepaper.pdf: 
       "Exon Probeset Annotations and Transcript Cluster Groupings".

     In order to use an alternative 'SchemeTreeSet' set the
     corresponding SchemeSet 'xps.scheme'.

_V_a_l_u_e:

     An 'ExprTreeSet'

_N_o_t_e:

     The expression measure obtained with FARMS is given in linear
     scale, analogously to the expression  measures computed with
     'mas5' and 'rma'. 

     For the analysis of many exon arrays it may be better to define a
     'tmpdir', since this will store only the results in the main file
     and not e.g. background and normalized intensities, and thus will
     reduce the file size of the main file. For quantile normalization
     memory should not be an issue, however DFW depends on RAM unless
     you are using a temporary file.

_A_u_t_h_o_r(_s):

     Christian Stratowa

_R_e_f_e_r_e_n_c_e_s:

     Hochreiter, S., Clevert D.-A., and Obermayer, K. (2006), A new
     summarization method for  Affymetrix probe level data.
     Bioinformatics 22(8):943-949

_S_e_e _A_l_s_o:

     'express'

_E_x_a_m_p_l_e_s:

     ## first, load ROOT scheme file and ROOT data file
     scheme.test3 <- root.scheme(paste(.path.package("xps"),"schemes/SchemeTest3.root",sep="/"))
     data.test3 <- root.data(scheme.test3, paste(.path.package("xps"),"rootdata/DataTest3_cel.root",sep="/"))

     data.farms <- farms(data.test3,"tmp_Test3FARMS",verbose=FALSE)

     ## get data.frame
     expr.farms <- validData(data.farms)
     head(expr.farms)

