EBMTP-class             package:multtest             R Documentation

_C_l_a_s_s "_E_B_M_T_P", _c_l_a_s_s_e_s _a_n_d _m_e_t_h_o_d_s _f_o_r _e_m_p_i_r_i_c_a_l _B_a_y_e_s _m_u_l_t_i_p_l_e _t_e_s_t_i_n_g _p_r_o_c_e_d_u_r_e _o_u_t_p_u_t

_D_e_s_c_r_i_p_t_i_o_n:

     An object of class EBMTP is the output of a particular multiple
     testing procedure, as generated by the function 'EBMTP'. The
     object has slots for the various data used to make multiple
     testing decisions, in particular adjusted p-values.

_O_b_j_e_c_t_s _f_r_o_m _t_h_e _C_l_a_s_s:

     Objects can be created by calls of the form 
      new('MTP', 
      statistic = ...., object of class numeric
      estimate  = ...., object of class numeric
      sampsize  = ...., object of class numeric
      rawp      = ...., object of class numeric
      adjp      = ...., object of class numeric
      reject    = ...., object of class matrix
      rawdist   = ...., object of class matrix
      nulldist  = ...., object of class matrix
      nulldist.type = ...., object of class character
      marg.null = ...., object of class character
      marg.par  = ...., object of class matrix
      label     = ...., object of class numeric
      falsepos  = ...., object of class matrix
      truepos   = ...., object of class matrix
      errormat  = ...., object of class matrix
       EB.h0M    = ...., object of class numeric
      prior     = ...., object of class numeric
      prior.type= ...., object of class character
      lqv       = ...., object of class numeric
      Hsets     = ...., object of class matrix
      index     = ...., object of class matrix
      call      = ...., object of class call
      seed      = ...., object of class integer
      )

_S_l_o_t_s:


     '_s_t_a_t_i_s_t_i_c' Object of class 'numeric', observed test statistics
          for each hypothesis, specified by the values of the 'MTP'
          arguments 'test', 'robust', 'standardize', and 'psi0'.

     '_e_s_t_i_m_a_t_e' For the test of single-parameter null hypotheses using
          t-statistics (i.e., not the F-tests), the numeric vector of
          estimated parameters corresponding to each hypothesis, e.g.
          means, differences in means, regression parameters.

     '_s_a_m_p_s_i_z_e' Object of class 'numeric', number of columns (i.e.
          observations) in the input data set.

     '_r_a_w_p' Object of class 'numeric', unadjusted, marginal p-values
          for each hypothesis.

     '_a_d_j_p' Object of class 'numeric', adjusted (for multiple testing)
          p-values for each hypothesis (computed only if the 'get.adjp'
          argument is TRUE).

     '_r_e_j_e_c_t' Object of class ''matrix'', rejection indicators (TRUE
          for a rejected null hypothesis), for each value of the
          nominal Type I error rate 'alpha'.

     '_r_a_w_d_i_s_t' The numeric matrix for the estimated nonparametric
          non-null test statistics distribution (returned only if
          'keep.rawdist=TRUE' and if 'nulldist' is one of 'boot.ctr',
          'boot.cs', or 'boot.qt'). This slot must not be empty if one
          wishes to call 'update' to change choice of bootstrap-based
          null distribution.

     '_n_u_l_l_d_i_s_t' The numeric matrix for the estimated test statistics
          null distribution (returned only if 'keep.nulldist=TRUE'). By
          default (i.e., for 'nulldist='boot.cs''), the entries of
          'nulldist' are the null value shifted and scaled bootstrap
          test statistics, with one null test statistic value for each
          hypothesis (rows) and bootstrap iteration (columns).

     '_n_u_l_l_d_i_s_t._t_y_p_e' Character value describing which choice of null
          distribution was used to generate the MTP results.  Takes on
          one of the values of the original 'nulldist' argument in the
          call to MTP, i.e., 'boot.cs', 'boot.ctr', 'boot.qt', or 'ic'.

     '_m_a_r_g._n_u_l_l' If 'nulldist='boot.qt'', a character value returning
          which choice of marginal null distribution was used by the
          MTP.  Can be used to check default values or to ensure manual
          settings were correctly applied.

     '_m_a_r_g._p_a_r' If 'nulldist='boot.qt'', a numeric matrix returning the
          parameters of the marginal null distribution(s) used by the
          MTP.  Can be used to check default values or to ensure manual
          settings were correctly applied.

     '_f_a_l_s_e_p_o_s' A matrix with rows equal to the number of hypotheses
          and columns the number of samples of null test statistics
          ('B') indicating the number of guessed false positives when
          using the corresponding value of the observed test statistic
          as a cut-off.  Not returned unless 'keep.falsepos=TRUE'.

     '_t_r_u_e_p_o_s' A matrix with rows equal to the number of hypotheses and
          columns the number of samples of null test statistics ('B')
          indicating the number of guessed true positives when using
          the corresponding value of the observed test statistic as a
          cut-off.  Not returned unless 'keep.truepos=TRUE'.

     '_e_r_r_o_r_m_a_t' The matrix obtained after applying to type I error rate
          function closure to the matrices in 'falsepos', and, if
          applicable, 'truepos'.  Not returned unless
          'keep.errormat=TRUE'.

     '_E_B._h_0_M' The sum of the local q-values obtained after density
          estimation.  This number serves as an estimate of the
          proportion of true null hypotheses.  Values close to one
          indicate situations in which type I error control may not be
          guaranteed by the EBMTP.  When 'prior='EBLQV'', this value is
          used as the prior 'pi' during evaluation of the local q-value
          function. 

     '_p_r_i_o_r' The numeric value of the prior 'pi' used when evaluating
          the local q-value function.

     '_p_r_i_o_r._t_y_p_e' Character string returning the value of 'prior' in
          the original call to 'EBMTP'.  One of 'conservative', 'ABH',
          or 'EBLQV'.

     '_l_q_v' A numeric vector of length the number of hypotheses with the
          estimated local q-values used for generating guessed sets of
          true null hypotheses.

     '_H_s_e_t_s' A numeric matrix with the same dimension as 'nulldist',
          containing the Bernoulli realizations of the estimated local
          q-values stored in 'lqv' which were used to partition the
          hypotheses into guessed sets of true and false null
          hypotheses at each round of (re)sampling.  Not returned
          unless 'keep.Hsets=TRUE'.

     '_l_a_b_e_l' If 'keep.label=TRUE', a vector storing the values used in
          the argument 'Y'.  Storing this object is particularly
          important when one wishes to update EBMTP objects with
          F-statistics using default 'marg.null' and 'marg.par'
          settings when 'nulldist='boot.qt''. 

     '_i_n_d_e_x' For tests of correlation parameters a matrix corresponding
          to 't(combn(p,2))', where 'p' is the number of variables in
          'X'.  This matrix gives the indices of the variables
          considered in each pairwise correlation.  For all other
          tests, this slot is empty, as the indices are in the same
          order as the rows of 'X'.

     '_c_a_l_l' Object of class 'call', the call to the MTP function.

     '_s_e_e_d' An integer or vector for specifying the state of the random
          number generator used to create the resampled datasets. The
          seed can be reused for reproducibility in a repeat call to
          'MTP'. This argument is currently used only for the bootstrap
          null distribution (i.e., for 'nulldist="boot.xx"'). See
          '?set.seed' for details.

_M_e_t_h_o_d_s:

     'signature(x = "EBMTP")' 

     [ : Subsetting method for 'EBMTP' class, which operates
          selectively on each slot of an 'EBMTP' instance to retain
          only the data related to the specified hypotheses.

     _a_s._l_i_s_t : Converts an object of class 'EBMTP' to an object of
          class 'list', with an entry for each slot.

     _p_l_o_t : plot methods for 'EBMTP' class, produces the following
          graphical summaries of the results of a EBMTP. The type of
          display may be specified via the 'which' argument. 

          1. Scatterplot of number of rejected hypotheses vs. nominal
          Type I error rate. 

          2. Plot of ordered adjusted p-values; can be viewed as a plot
          of Type I error rate vs. number of rejected hypotheses. 

          3. Scatterplot of adjusted p-values vs. test statistics (also
          known as "volcano plot"). 

          4. Plot of unordered adjusted p-values. 

          The plot method for objects of class 'EBMTP' does not return
          the plots associated with 'which=5' (using confidence
          regions) or with 'which=6' (pertaining to cut-offs) as it
          does for objects of class 'MTP'.  This is because the
          function 'EBMTP' currently only returns adjusted p-values. 
          The argument 'logscale' (by default equal to FALSE) allows
          one to use the negative decimal logarithms of the adjusted
          p-values in the second, third, and fourth graphical displays.
          The arguments 'caption' and 'sub.caption' allow one to change
          the titles and subtitles for each of the plots (default
          subtitle is the MTP function call). Note that some of these
          plots are implemented in the older function 'mt.plot'.

     _p_r_i_n_t : print method for 'EBMTP' class, returns a description of
          an object of class 'EBMTP', including sample size, number of
          tested hypotheses, type of test performed (value of argument
          'test'), Type I error rate (value of argument 'typeone'),
          nominal level of the test  (value of argument 'alpha'), name
          of the EBMTP (value of argument 'method'), call to the
          function 'EBMTP'.

          In addition, this method produces a table with the class,
          mode, length, and dimension of each slot of the 'EBMTP'
          instance. 


     _s_u_m_m_a_r_y : summary method for 'EBMTP' class, provides numerical
          summaries of the results of an EBMTP and returns a list with
          the following three components. 

          1. rejections: A data.frame with the number(s) of rejected
          hypotheses for the nominal Type I error rate(s) specified by
          the 'alpha' argument of the function 'MTP'. 

          2. index: A numeric vector of indices for ordering the
          hypotheses according to first 'adjp', then 'rawp', and
          finally the absolute value of 'statistic' (not printed in the
          summary). 


          3. summaries: When applicable (i.e., when the corresponding
          quantities are returned by 'MTP'), a table with six number
          summaries of the distributions of the adjusted p-values,
          unadjusted p-values, test statistics, and parameter
          estimates.

     _E_B_u_p_d_a_t_e : update method for 'EBMTP' class, provides a mechanism
          to re-run the MTP with different choices of the following
          arguments - nulldist, alternative, typeone, k, q, alpha,
          smooth.null, bw, kernel, prior, keep.nulldist, keep.rawdist,
          keep.falsepos, keep.truepos, keep.errormat, keep.margpar.
          When evaluate is 'TRUE', a new object of class EBMTP is
          returned. Else, the updated call is returned. The 'EBMTP'
          object passed to the update method must have either a 
          non-empty 'rawdist' slot or a non-empty 'nulldist' slot
          (i.e., must have been called with either 'keep.rawdist=TRUE'
          or 'keep.nulldist=TRUE').  

          Additionally, when calling 'EBupdate' for any Type I error
          rate other than FWER, the 'typeone' argument must be
          specified (even if the original object did not control FWER).
          For example,  'typeone="fdr"', would always have to be
          specified, even if the original object also controlled the
          FDR. In other words, for all function arguments, it is safest
          to always assume that you  are updating from the 'EBMTP'
          default function settings, regardless of the original call to
          the 'EBMTP' function. Currently, the main advantage of the
          'EBupdate' method is that it prevents the need for repeated
          estimation of the test statistics null distribution. 


          To save on memory, if one knows ahead of time that one will
          want to compare different choices of bootstrap-based null
          distribution, then it is both necessary and sufficient to
          specify 'keep.rawdist=TRUE', as there is no other means of
          moving between null distributions other than through the
          non-transformed non-parametric bootstrap distribution.  In
          this case, 'keep.nulldist=FALSE' may be used.  Specifically,
          if an object of class 'EBMTP' contains a non-empty 'rawdist'
          slot and an empty 'nulldist' slot, then a new null
          distribution will be generated according to the values of the
          'nulldist=' argument in the original call to 'EBMTP' or any
          additional specifications in the call to 'update'. On the
          other hand, if one knows that one wishes to only update an
          'EBMTP' object in ways which do not involve choice of null
          distribution, then 'keep.nulldist=TRUE' will suffice and
          'keep.rawdist' can be set to 'FALSE' (default settings).  The
          original null distribution object will then be used for all
          subsequent calls to 'update'. 

          N.B.: Note that 'keep.rawdist=TRUE' is only available for the
          bootstrap-based resampling methods.  The non-null
          distribution does not exist for the permutation or influence
          curve multivariate normal null distributions. 

     _e_b_m_t_p_2_m_t_p : coersion method for converting objects of class
          'EBMTP' to objects of class 'MTP'.  Slots common to both
          objects are taken from the object of class 'EBMTP' and used
          to create a new object of class 'MTP'.  Once an object of
          class 'MTP' is created, one may use the method 'update' to
          perform resampling-based multiple testing (as would have been
          done with calls to 'MTP') without the need for repeated
          resampling.

_A_u_t_h_o_r(_s):

     Houston N. Gilbert, based on the original 'MTP' class and method
     definitions written by Katherine S. Pollard

_R_e_f_e_r_e_n_c_e_s:

     H.N. Gilbert, K.S. Pollard, M.J. van der Laan, and S. Dudoit
     (2009). Resampling-based multiple  hypothesis testing with
     applications to genomics: New developments in R/Bioconductor 
     package multtest. _Journal of Statistical Software_ (submitted).
     Temporary URL: <URL:
     http://www.stat.berkeley.edu/~houston/JSSNullDistEBMTP.pdf>.

     Y. Benjamini and Y. Hochberg (2000). On the adaptive control of
     the false  discovery rate in multiple testing with independent
     statistics. _J. Behav. Educ. Statist_. Vol 25: 60-83.

     Y. Benjamini, A. M. Krieger and D. Yekutieli (2006). Adaptive
     linear step-up procedures that control the false discovery rate.
     _Biometrika_.  Vol. 93: 491-507.

     M.J. van der Laan, M.D. Birkner, and A.E. Hubbard (2005). 
     Empirical Bayes and Resampling Based Multiple Testing Procedure
     Controlling the Tail Probability of the Proportion of False
     Positives. Statistical Applications in Genetics and Molecular
     Biology, 4(1). <URL:
     http://www.bepress.com/sagmb/vol4/iss1/art29/> 

     S. Dudoit and M.J. van der Laan.  Multiple Testing Procedures and
     Applications to Genomics.  Springer Series in Statistics.
     Springer, New York, 2008. 

     S. Dudoit, H. N. Gilbert, and M. J. van der Laan (2008). 
     Resampling-based empirical Bayes multiple testing procedures for
     controlling  generalized tail probability and expected value error
     rates: Focus on the false discovery rate and simulation study.
     _Biometrical Journal_, 50(5):716-44. <URL:
     http://www.stat.berkeley.edu/~houston/BJMCPSupp/BJMCPSupp.html>. 

     H.N. Gilbert, M.J. van der Laan, and S. Dudoit. Joint multiple
     testing procedures for  graphical model selection with
     applications to biological networks. Technical report,  U.C.
     Berkeley Division of Biostatistics Working Paper Series, April
     2009. URL <URL: http://www.bepress.com/ucbbiostat/paper245>. 

_S_e_e _A_l_s_o:

     'EBMTP', 'EBMTP-methods', 'MTP', 'MTP-methods', '[-methods',
     'as.list-methods', 'print-methods', 'plot-methods',
     'summary-methods', 'mtp2ebmtp',  'ebmtp2mtp'

_E_x_a_m_p_l_e_s:

     ## See EBMTP function: ? EBMTP

