matest                package:maanova                R Documentation

_S_t_a_t_i_s_t_i_c_a_l _t_e_s_t _f_o_r _M_i_c_r_o_a_r_r_a_y _e_x_p_e_r_i_m_e_n_t

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

     This is the function to perform F or T test on one or multiple
     experimental factor(s). Permutation test will be carried upon
     request.

_U_s_a_g_e:

     matest(data, anovaobj, term, Contrast, n.perm=1000, nnodes=1,
            critical=.9, test.type = c("ttest", "ftest"),
            shuffle.method=c("sample", "resid"),
            MME.method=c("REML","noest","ML"),
            test.method=c(1,1),pval.pool=TRUE, verbose=TRUE)

_A_r_g_u_m_e_n_t_s:

    data: An object of class 'madata'.

anovaobj: An object of class 'fitmaanova'.

    term: The term(s) to be tested. It can be multiple terms. Note that
          the tested term must be fixed. If the term to be tested is a
          random term, it will be converted to a fixed term than do
          test.

Contrast: The contrast matrix for the term. The number of columns
          equals to the number of levels in the term. The number of
          rows is the number of T-test you want to carry. Note that it
          must be a matrix. Use 'PairContrast' to make all possible
          pairwise comparison or 'matrix' command to make it manually.
          Note that the the hypothesis test can be formulated as H0:
          Lb=0 versus alternative. This contrast matrix is L. For
          testing a covariate, use a one by one contrast matrix of 1.

  n.perm: An integer for number of permutations.

  nnodes: Number of nodes in the MPI cluster. If 1, the permutation
          test will be running on the local computer.

critical: percentile of F-distribution used to get a subset to 
          calculate p-value. Default is 90th percentile of
          F-distribution, and  permutation analysis is conducted based
          on genes whose test statistics  are smaller than 90th
          percentile of the F-distribution.

test.type: Test type. It could be F-test or T-test. If the Contrast
          matrix is missing, this should be a "ftest" and the  contrast
          matrix is generated automatically to cover the whole linear
          space except for testing covariates. If the Contrast matrix 
          is given, this could be "ftest" or "ttest". The default is
          "ttest"  (for backward compatability). For T-test, the code
          will do a series  of T-test, where each T-test corresponds to
          a row in the contrast matrix.

shuffle.method: Data shuffling method. "sample" for sample shuffling
          and "resid" for residual shuffling. Read "Data Shuffling"
          section for detail.

MME.method: The method used to solve the Mixed Model Equations. See
          'fitmaanova' for detail. This parameter only applies for
          mixed effects model permutation test. Default method is
          "REML". The variance components for observed data will be
          used for permuted data. It will greatly increase the speed
          but you may lose power in statistical test in some cases.

test.method: An integer vector of two elements to indicate which F test
          to carry. Default is c(1,1), which means do F1 and Fs test.

pval.pool: A logical value to indicate whether to use pooled
          permutation F values to calculate the P values.

 verbose: A logical value to indicate whether to display some message
          for calculation progress.

_D_e_t_a_i_l_s:

     If user provide a comparison matrix, this function will perform
     T-test on the given comparison(s). Otherwise, this function will
     perform F-test for the given term.

     There are three types of tests available. All three tests are
     based on the gene-specific ANOVA model.  F1 is the usual F
     statistic, Fs is based on the James-Stein shrinkage estimates of
     the error variance.

     Permutation tests can run on MPI cluster.  This feature is only
     available for Unix/Linux system. Several other R packages (such
     like SNOW, Rmpi, etc.) are needed for using cluster. You may need
     help from your system administrator to setup LAM-MPI correctly.
     For detailed information on LAM-MPI cluster setup and the cluster
     usage in R, read "MPI_README" distributed with the package.

_V_a_l_u_e:

     An object of class 'matest', which is a list of the following
     components: 

   model: Input model object.

    term: The input term(s) to be tested.

    dfde: Denominator's degree of freedom for the test.

    dfnu: Numerator's degree of freedom for the test. Note that this is
          always 1 for T-test.

obsAnova: An object of 'fitmaanova', which is the ANOVA model fitting
          result on the original data.

Contrast: The contrast matrix used in the test.

  n.perm: Number of permutations.

 shuffle: Shuffle style

pval.pool: Use pooled P value or not.

  F1, Fs: Objects of four different F tests results. All or any of them
          could be there according to the requested F test method. Each
          of them contains the following fields:

        _F_o_b_s F value for the observed data.

        _P_t_a_b Tabulated P values for the observed data.

        _P_v_a_l_p_e_r_m Nominal permutation P values for each gene. This field
             will be unavailable if user do not do permutation test.

        _P_v_a_l_m_a_x FWER one-step adjusted P values from the permutation
             test.

          All the F values and P values are matrices. The number of
          rows in the matrices equals to the number of genes. For
          F-test, the number of columns will be one. For T-test, the
          number of columns equals to the number of tests carried. 

_D_a_t_a _S_h_u_f_f_l_i_n_g:

     Data shuffling method is a crucial part in the permutation test.
     Currently there are two shuffling method available, residual
     shuffling and sample shuffling. 

     Residual shuffling is to shuffle the null model residuals within
     gene without replacement. 

     Sample shuffling is to shuffle the samples based on the nesting
     relationship among the experimental factors in the model. For
     sample shuffling, you need to make sure you have a  good sample
     size. Otherwise the result may be biased.

_A_u_t_h_o_r(_s):

     Hao Wu

_R_e_f_e_r_e_n_c_e_s:

     Cui, X. and Churchill,GA (2003), Statistical tests for
     differential expression in cDNA Microarray experiments, _Genome
     Biology_ 4:210. 

     Cui, X., Hwang, J.T.G., Blades N., Qiu J. and Churchill GA (2003),
     Improved statistical tests for differential gene expression by
     shrinking variance components, to be submitted.

_S_e_e _A_l_s_o:

     'makeModel', 'fitmaanova'

_E_x_a_m_p_l_e_s:

     # load in abf1 data
     data(abf1)
     ## Not run: 
     fit.full.mix <- fitmaanova(abf1, formula = ~Strain+Sample, 
        random = ~Sample)
     ftest.all = matest(abf1, fit.full.mix, test.method=c(1,1),
         shuffle.method="sample", term="Strain", n.perm= 100)
     C = matrix(c(1,-1,0,1,0,-1), ncol=3, byrow=T)
     ftest.pair = matest(abf1, fit.full.mix, Contrast = C, 
        term="Strain", n.perm=100)
     ## End(Not run)

