MTP-methods             package:multtest             R Documentation

_M_e_t_h_o_d_s _f_o_r _M_T_P _a_n_d _E_B_M_T_P _o_b_j_e_c_t_s _i_n _P_a_c_k_a_g_e _m_u_l_t_t_e_s_t

_D_e_s_c_r_i_p_t_i_o_n:

     Summary, printing, plotting, subsetting, updating, as.list and
     class conversion methods were defined for the 'MTP' and 'EBMTP'
     classes. These methods provide visual and numeric summaries of the
     results of a multiple testing procedure (MTP) and allow one to
     perform some basic manipulations of  objects class 'MTP' or
     'EBMTP'.  

     Several of the methods with the same name will work on objects of
     their respective class.  One exception to this rule is the
     difference between 'update' and 'EBupdate' (described below). 
     Because of the differences in the testing procedures, separately
     named methods were chosen to clearly delineate which method was
     being applied to which type of object.

_M_e_t_h_o_d_s:



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

     _a_s._l_i_s_t : Converts an object of class 'MTP' or 'EBMTP' to an
          object of class 'list', with an entry for each slot.

     _p_l_o_t : plot methods for 'MTP' and 'EBMTP' classes, produces the
          following graphical summaries of the results of a MTP. 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. 

          Only for objects of class 'MTP': 

          5. Plot of confidence regions for user-specified parameters,
          by default the 10 parameters corresponding to the smallest
          adjusted p-values  (argument 'top'). 

          6. Plot of test statistics and corresponding cut-offs (for
          each value of 'alpha') for user-specified hypotheses, by
          default the 10 hypotheses corresponding to the smallest
          adjusted p-values (argument 'top'). 

          Plots (5) and (6) are not available for objects of class
          'EBMTP' because the function 'EBMTP' returns only adjusted
          p-values and not confidence regions of cut-offs.  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 'MTP' and 'EBMTP' classes, returns a
          description of an object of either class, 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 MTP (value of argument
          'method'), call to the function 'MTP' or 'EBMTP'. 

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


     _s_u_m_m_a_r_y : summary method for 'MTP' and 'EBMTP' classes, provides
          numerical summaries of the results of a MTP 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' or 'EBMTP'. (For
          objects of class 'MTP', NULL values are returned if all three
          arguments 'get.cr', 'get.cutoff', and 'get.adjp' are FALSE). 

          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' or 'EBMTP'), a table with
          six number summaries of the distributions of the adjusted
          p-values, unadjusted p-values, test statistics, and parameter
          estimates.

     _u_p_d_a_t_e : update methods for 'MTP' class, respectively, provides a
          mechanism to re-run the MTP with different choices of the
          following arguments - nulldist, alternative, typeone, k, q,
          fdr.method, alpha, smooth.null, method, get.cr, get.cutoff,
          get.adjp, keep.nulldist, keep.rawdist, keep.margpar. When
          evaluate is 'TRUE', a new object of class MTP is returned.
          Else, the updated call is returned. The 'MTP' 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').

     _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 'MTP' or '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 '(EB)MTP' or any
          additional specifications in the call to '(EB)update'. On the
          other hand, if one knows that one wishes to only update an
          '(EB)MTP' object in ways which do not involve choice of
          bootstrap 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.

     _m_t_p_2_e_b_m_t_p : coersion method for converting objects of class 'MTP'
          to objects of class 'EBMTP'.  Slots common to both objects
          are taken from the object of class 'MTP' and used to create a
          new object of class 'EBMTP'.  Once an object of class 'EBMTP'
          is created, one may use the method 'EBupdate' to perform
          resampling-based empirical Bayes multiple testing without the
          need for repeated resampling.

     _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):

     Katherine S. Pollard and Houston N. Gilbert with design
     contributions from Sandrine Dudoit and Mark J. van der Laan.

