qb.mcmc                package:qtlbim                R Documentation

_B_a_y_e_s_i_a_n _M_u_t_i_p_l_e _I_n_t_e_r_a_c_t_i_n_g _Q_T_L _m_a_p_p_i_n_g _u_s_i_n_g _M_C_M_C

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

     A computationally efficient MCMC algorithm using the Gibbs sampler
     or  Metropolis-Hastings algorithm is used to produce posterior
     samples for  QTL mapping.

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

     qb.mcmc(cross, data, model, mydir = ".", n.iter = 3000, n.thin = 40,
       n.burnin = 0.01*n.iter*n.thin, algorithm = c("M-H","Gibbs"),
       genoupdate = TRUE, seed = 0, verbose = TRUE, ...)   

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

   cross: An object of class 'cross'. See 'read.cross' for details. 

    data: the list returned by calling the function 'qb.data' .

   model: the list returned by calling the function 'qb.model'.

   mydir: a directory to save output from 'qb.mcmc' in several '*.dat'
          files. A directory is created using the trait name and the
          system time and date. If no directory is specified, the
          default directory is the current working  directory.

  n.iter: number of iterations to be saved in 'mydir', the default
          being 3000. Note that, 'n.iter' is not the total number of   
               iterations performed but the number iterations saved or
          considered as posterior samples for future analysis. The
          actual number of iterations would be 'n.burnin +
          n.iter*n.thin'                                                           

  n.thin: the thinning number which must be a positive number
          (default=40)

n.burnin: the initial burn-in period, i.e number of iterations to
          discard at the beginning of the MCMC run default being
          0.01*n.iter*n.thin.

algorithm: specifies the sampling algorithm for MCMC : Gibbs sampler
          ("Gibbs") or Metropolis-Hastings algorithm ("M-H")

genoupdate: =TRUE will update QTL genotypes and =FALSE will not do so
          and use the expected value of the QTL genotypes.

    seed: Specifies the seed for the random number generator. Using the
          same seed for two runs of the 'qb.mcmc' function will
          generate the exact same output. The 'seed' needs to be an
          integer. The default value for seed is the system time.

 verbose: =TRUE will force periodic output of the number of MCMC
          iterations saved. The location of the output directory where
          results are stored and the time taken for the MCMC run will
          also be displayed to the user.

     ...: Paramters passed to 'qb.data' or 'qb.model' if 'data' or
          'model', respectively, is not provided.

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

     A composite model space approach to develop a Bayesian model
     selection framework for identifying interacting QTL for complex
     traits in experimental crosses from two inbred lines. By placing a
     liberal constraint on the upper bound of the number of detectable
     QTL we restrict attention to models of  fixed dimension. Either
     Gibbs sampler or Metroplis-Hastings algorithm can be applied to
     sample from the posterior distribution.

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

     The 'qb.mcmc' function returns a list of class 'qb', the
     components of which contain input parameters from the 'cross'
     object, 'qb.data' and 'qb.model'. Since, the parameters have
     already been described in their respective man pages  we only
     include the components which have been added on top of these. 
     However, the 'qbOject$subset' component is a way to manipulate the
     Monte Carlo samples to make it ready for the high-end plotting
     routines and might not be of much importance to the average user.

output.dir: directory used for saving all outputs generated by
          'qb.mcmc'.

               *  *'iterdiag'*  is a vector of integers from 1 to
                  'n.iter'.

               *  *'mainloci'*  is a vector of length equaling the sum
                  of the number of QTLs detected in each iteration.
                  This vector is actually a permutation vector of the
                  'mainloci.dat' file stored in 'mydir' sorted with
                  respect to the iteration number and ties are broken
                  with the chromosome number and the locus of the
                  putative QTL.

               *  *'pairloci'*  is a list of 

                  *  _'order'_ is a vector of integers from 1 to the
                     total number of epistatic effects in all
                     iterations.

                  *  _'flip'_  is  a logical vector = TRUE if
                     chromosome no. 1 for the paired loci is greater
                     than chromosome no.2 or if they are the same on
                     the same chromosome then =TRUE when position of
                     the first is greater than the position of the
                     second.  

                  *  _'left'_ is a character vector containing "chrom1"
                     and "locus1" if there is a single TRUE in 'flip'

                  *  _'right'_ is a character vector containing
                     "chrom2" and "locus2" if there is a single TRUE in
                     'flip'

               *  *'region'*   a data frame storing the first and last
                  position of the  marker map for each chromosome.


_O_u_t_p_u_t _F_i_l_e_s:

     The following files are saved in 'output.dir':   

        1.  *'iterdiag.dat'*

           The iteration file saved in 'mydir' has 'n.iter' rows and 4
           major columns:
            'column no 1' :  iteration number.
            'column no 2' :  number of putative QTLs included.
            'column no 3' :  the overall mean.
            'column no 4' :  the residual variance.

           Depending on the type of cross, presence of covariates and
           epistatic effects there would be more columns in the
           following order: variance of additive effect, variance of
           dominant effect, variance of additive-additive interaction,
           variance of additive-dominant interaction, variance of
           dominant-additive interaction, variance of dominant-dominant
           interaction, variance of environment-additive interaction,
           variance of environmnet-dominant interaction, variance of
           environemnt effect, total genetic variance.

        2.  *'covariates.dat'*

           The covariate file saved in 'mydir' has 'n.iter' rows and
           L+M('length(fixcov)+length(rancov)') columns:
            'L columns' : Coeffecient of the fixed effect.
            'M columns' : Variance of the random effect. 

             If an ordinal trait is analyzed, the cutoff points for the
           threshold model are also included in additional columns.
           There would be C-3 bounded threshold values for an ordinal
           phenotype with C categories.

        3.  *'mainloci.dat'*

           The mainloci file saved in 'mydir' has the N rows (N=sum of
           number of QTLs detected in 'n.iter' iterations) and 4 major
           columns:
            'column no 1' : iteration number.
            'column no 2' : number of putative QTLs included in the
           model.
            'column no 3' : the chromosome number on which a putative
           QTL has been detected.
            'column no 4' : the QTL position indicator in the grid.

            Depending on the type of cross there would be more columns
           in the  following order: additive effect, dominant effect,
           variance of additive effect, and variance of dominant
           effect.

        4.  *'pairloci.dat'*

           The pairloci file saved in 'mydir' has the N rows (N=sum of
           number of pairs of QTLs with epistatic effect detected) and
           6 major columns:
            'column no 1' : iteration number.
            'column no 2' : number of pairs of QTLs detected to have
           epistatic effect.
            'column no 3' : the chromosome number for the first one of
           each pair.
            'column no 4' : the QTL position for this one.
            'column no 5' : the chromosome number for the second one of
           each pair.
            'column no 6' : the QTL position for this one.

           Depending on the type of cross there would be more columns
           in the following order: additive-additive interaction
           effect, additive-dominant interaction effect,
           dominant-additive interaction effect, dominant-dominant
           interaction effect, variance of additive-additive
           interaction, variance of additive-dominant interaction,
           variance of dominant-additive interaction, variance of
           dominant-dominant interaction.

        5.  *'gbye.dat'*

           The gbye (Gene by Environment) file saved in 'mydir' has 5
           major columns:

           'column no 1' :  iteration number.
            'column no 2' :  number of GxE interactions.
            'column no 3' :  fixed covariate number.
            'column no 4' :  chromosome number of the putative QTL in
           the GxE interaction.
            'column no 5' :  position of the corresponding QTL.

           Depending on the type of cross there would be more columns
           in the following order: additive effect, dominant effect,
           variance of additive effect, and variance of dominant
           effect.

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

     Nengjun Yi, nyi@ms.ssg.uab.edu

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

     <URL: http://www.qtlbim.org>

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

     'qb.sim.cross',   'qb.data',    'qb.model',   'qb.mcmc'

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

     ## Not run: 
     example(qb.sim.cross)

     ## Calculate grids and genotypic probabilites.
     cross <- qb.genoprob(cross, step=2)

     ## Create MCMC samples
     ## First line as qb.data options; second line has qb.model options.
     qbExample <- qb.mcmc(cross, pheno.col = 3, rancov = 2, fixcov = 1,
       chr.nqtl = rep(3,nchr(cross)), intcov = 1, interval = rep(10,3),
       n.iter = 1000, n.thin = 20)
     ## End(Not run)

