ei.MD.bayes              package:eiPack              R Documentation

_M_u_l_t_i_n_o_m_i_a_l _D_i_r_i_c_h_l_e_t _m_o_d_e_l _f_o_r _E_c_o_l_o_g_i_c_a_l _I_n_f_e_r_e_n_c_e _i_n _R_x_C _t_a_b_l_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     Implements a version of the hierarchical model suggested in Rosen
     et al. (2001)

_U_s_a_g_e:

     ei.MD.bayes(formula, covariate = NULL, total = NULL, data, 
                 lambda1 = 4, lambda2 = 2, covariate.prior.list = NULL,
                 tune.list = NULL, start.list = NULL, sample = 1000, thin = 1, 
                 burnin = 1000, verbose = 0, ret.beta = 'r', 
                 ret.mcmc = TRUE, usrfun = NULL) 

_A_r_g_u_m_e_n_t_s:

 formula: A formula of the form 'cbind(col1, col2, ...) ~ cbind(row1,
          row2, ...)'.   Column and row marginals must have the same
          totals.

covariate: An optional formula of the form '~ covariate'.  The  default
          is 'covariate = NULL', which fits the model without a
          covariate.

   total: if row and/or column marginals are given as proportions,
          'total' identifies the name of the variable in 'data'
          containing the total number of individuals in each unit

    data: A data frame containing the variables specified in 'formula'
          and 'total'

 lambda1: The shape parameter for the gamma prior (defaults to 4)

 lambda2: The rate parameter for the gamma prior (defaults to 2)

covariate.prior.list: a list containing the parameters for normal prior
          distributions on delta and gamma for model with covariate. 
          See `details' for more information.

tune.list: A list containing tuning parameters for each block of
          parameters.  See `details' for more information.  Typically,
          this will be a list generated by 'tuneMD'.  The default is
          'NULL', in which case fixed tuning parameters are used.

start.list: A list containing starting values for each block of
          parameters.  See `details' for more information.  The default
          is 'start.list = NULL', which generates appropriate random
          starting values.

  sample: Number of draws to be saved from chain and returned as output
          from the function (defaults to 1000).  The total length of
          the chain is 'sample'*'thin' + 'burnin'.

    thin: an integer specifying the thinning interval for posterior
          draws (defaults to 1, but most problems will require a much
          larger thinning interval).

  burnin: integer specifying the number of initial iterations to be
          discarded (defaults to 1000, but most problems will require a
          longer burnin).

 verbose: an integer specifying whether the progress of the sampler  is
          printed to the screen (defaults to 0).  If 'verbose' is
          greater than 0, the iteration number is printed to the screen
          every 'verbose'th iteration.

ret.beta: A character indicating how the posterior draws of beta should
          be   handled: `'r''eturn as an R object, `'s''ave as .txt.gz
          files, `'d''iscard (defaults to 'r').

ret.mcmc: A logical value indicating how the samples from the posterior
           should be returned.  If 'TRUE' (default), samples are
          returned as coda 'mcmc' objects.  If 'FALSE', samples are
          returned as arrays.

  usrfun: the name of an optional a user-defined function to obtain
          quantities of interest while drawing from the MCMC chain
          (defaults to 'NULL').

_D_e_t_a_i_l_s:

     'ei.MD.bayes' implements a version of the hierarchical
     Multinomial-Dirichlet model for ecological inference in R x C
     tables suggested by Rosen et al. (2001).

     Let r = 1, ..., R index rows, C = 1, ..., C index columns, and i =
     1, ..., n index units.  Let N_.ci be the marginal count for column
     c in unit i and X_ri be the marginal proportion for row r in unit
     i.  Finally, let beta_rci be the proportion of row r in column c
     for unit i.

     The first stage of the model assumes that the vector of column
     marginal counts in unit i follows a Multinomial distribution of
     the form:


 (N_.1i,..., N_.Ci) ~ Multinomial(N_i,sum_{r=1}^R(beta_r1i*X_ri), ..., sum_{r=1}^R (beta_rCi*X_ri)


     The second stage of the model assumes that the vector of beta for
     row r in unit i follows a Dirichlet distribution with C
     parameters.  The model may be fit with or without a covariate. 

     If the model is fit without a covariate, the distribution of the
     vector beta_ri is :


    (beta_r1i, ..., beta_rCi) ~ Dirichlet(alpha_r1, ..., alpha_rC)


     In this case, the prior on each alpha_rc is assumed to be:


                 alpha_rc ~ Gamma(lambda_1, lambda_2


     If the model is fit with a covariate, the  distribution of the
     vector beta_ri is :


 (beta_r1i, ..., beta_rCi) ~ Dirichlet(d_r*exp(gamma_r1 + delta_r1 * Z_i), ..., d_r * exp(gamma_r(C-1) + delta_r(C-1)*Z_i), d_r)


     The parameters gamma_rC and delta_rC are constrained to be zero
     for identification.  (In this function, the last column entered in
     the formula is so constrained.)

     Finally, the prior for d_r is: 


                   d_r ~ Gamma(lambda_1, lambda_2)


     while gamma_rC and delta_rC are given improper uniform priors if
     'covariate.prior.list = NULL' or have independent normal priors of
     the form:


        delta_{rC} ~ N(mu_{delta_{rC}}, sigma_{delta_{rC}}^2)



        gamma_{rC} ~ N(mu_{gamma_{rC}}, sigma_{gamma_{rC}}^2)


     If the user wishes to estimate the model with proper normal priors
     on gamma_rC and delta_rC, a list with four elements must be
     provided for 'covariate.prior.list':

   '_m_u._d_e_l_t_a' an R x (C-1) matrix of prior means for Delta

   '_s_i_g_m_a._d_e_l_t_a' an R x (C-1) matrix of prior standard deviations for
        Delta 

   '_m_u._g_a_m_m_a' an R x (C-1) matrix of prior means for Gamma 

   '_s_i_g_m_a._g_a_m_m_a' an R x (C-1) matrix of prior standard deviations for
        Gamma

     Applying the model without a covariate is most reasonable in
     situations where one can think of individuals being randomly
     assigned to units, so that there are no aggregation or contextual
     effects.  When this assumption is not reasonable, including an
     appropriate covariate may improve inferences; note, however, that
     there is typically little information in the data about the
     relationship of any given covariate to the unit parameters, which
     can lead to extremely slow mixing of the MCMC chains and
     difficulty in assessing convergence.

     Because the conditional distributions are non-standard, draws from
     the posterior are obtained by using a Metropolis-within-Gibbs
     algorithm. The proposal density for each parameter is a univariate
     normal distribution centered at the current parameter value with
     standard deviation equal to the tuning constant; the only
     exception is for draws of gamma_rc and delta_rc, which use a
     bivariate normal proposal with covariance zero.  

     The function will accept user-specified starting values as an
     argument. If the model includes a covariate, the starting values
     must be a list with the following elements, in this order:


   '_s_t_a_r_t._d_r' a vector of length R of starting values for Dr. Starting
        values for Dr must be greater than zero.

   '_s_t_a_r_t._b_e_t_a_s' an R x C by precincts array of starting values for
        Beta.  Each row of every precinct must sum to 1.

   '_s_t_a_r_t._g_a_m_m_a' an R x C matrix of starting values for Gamma.  Values
        in the right-most column must be zero.

   '_s_t_a_r_t._d_e_l_t_a' an R x C matrix of starting values for Delta.  Values
        in the right-most column must be zero.

     If there is no covariate, the starting values must be a list with
     the following elements:

   '_s_t_a_r_t._a_l_p_h_a_s' an R x C matrix of starting values for Alpha. 
        Starting values for Alpha must be greater than zero.

   '_s_t_a_r_t._b_e_t_a_s' an R x C x units array of starting values for Beta. 
        Each row in every unit must sum to 1.

     The function will accept user-specified tuning parameters as an
     argument.  The tuning parameters define the standard deviation of
     the normal distribution used to generate candidate values for each
     parameter.  For the model with a covariate, a bivariate normal
     distribution is used to generate proposals; the covariance of
     these normal distributions is fixed at zero.  If the model
     includes a covariate, the tuning parameters must be a list with
     the following elements, in this order:

   '_t_u_n_e._d_r' a vector of length R of tuning parameters for Dr

   '_t_u_n_e._b_e_t_a' an R x (C-1) by precincts array of tuning parameters for
        Beta 

   '_t_u_n_e._g_a_m_m_a' an R x (C-1) matrix of tuning parameters for Gamma 

   '_t_u_n_e._d_e_l_t_a' an R x (C-1) matrix of tuning parameters for Delta

     If there is no covariate, the tuning parameters are a list with
     the following elements:

   '_t_u_n_e._a_l_p_h_a' an R x C matrix of tuning parameters for Alpha

   '_t_u_n_e._b_e_t_a' an R x (C-1) by precincts array of tuning parameters for
        Beta

_V_a_l_u_e:

     A list containing  

   draws: A list containing samples from the posterior distribution of
          the parameters.  If a covariate is included in the model, the
          list contains: 

        '_D_r' Posterior draws for Dr parameters as an R xsample matrix. 
             If 'ret.mcmc = TRUE', 'Dr' is an 'mcmc' object.

        '_B_e_t_a' Posterior draws for beta parameters.  Only returned if 
             'ret.beta = TRUE'.  If 'ret.mcmc =  TRUE', a  (R * C *
             units) x sample matrix saved as an 'mcmc'  object. 
             Otherwise, a R x C x units x sample array

        '_G_a_m_m_a' Posterior draws for gamma parameters.  If 'ret.mcmc =
             TRUE', a  (R * (C - 1)) x sample matrix saved as an 'mcmc'
             object.  Otherwise, a R x (C - 1) x sample array

        '_D_e_l_t_a' Posterior draws for delta parameters.  If 'ret.mcmc =  
                            TRUE', a  (R * (C - 1)) x sample matrix
             saved as an 'mcmc'       object.  Otherwise, a R x(C - 1)
             x sample array

        '_C_e_l_l._c_o_u_n_t' Posterior draws for the cell counts, summed across
             units.  If 'ret.mcmc = TRUE', a (R * C) x sample matrix
             saved as an 'mcmc' object. Otherwise, a R x C x sample
             array

          If the model is fit without a covariate, the list includes:

        '_A_l_p_h_a' Posterior draws for alpha parameters.  If 'ret.mcmc =
             TRUE', a (R * C) x sample matrix saved as an 'mcmc'
             object. Otherwise, a R x C x sample array

        '_B_e_t_a' Posterior draws for beta parameters.  If 'ret.mcmc =
             TRUE', a (R * C * units) x sample matrix saved as an
             'mcmc' object.  Otherwise, a R x C x units x sample array 

        '_C_e_l_l._c_o_u_n_t' Posterior draws for the cell counts, summed across
             units.  If 'ret.mcmc = TRUE', a (R * C) x sample matrix
             saved as an'mcmc' object. Otherwise, a R x C x sample
             array

acc.ratios: A list containing acceptance ratios for the parameters.  If
          the model includes a covariate, the list includes:

        '_d_r._a_c_c' A vector of acceptance ratios for 'Dr' draws

        '_b_e_t_a._a_c_c' A vector of acceptance ratios for 'Beta' draws

        '_g_a_m_m_a._a_c_c' A vector of acceptance ratios for 'Gamma' and
             'Delta' draws

          If the model is fit without a covariate , the list includes:

        '_a_l_p_h_a._a_c_c' A vector of acceptance ratios for 'Alpha' draws

        '_b_e_t_a._a_c_c' A vector of acceptance ratios for 'Beta' draws  

  usrfun: Output from the optional 'usrfn'

    call: Call to 'ei.MD.bayes'

_A_u_t_h_o_r(_s):

     Michael Kellermann <kellerm@post.harvard.edu> and Olivia Lau 
     <olivia.lau@post.harvard.edu>

_R_e_f_e_r_e_n_c_e_s:

     Martyn Plummer, Nicky Best, Kate Cowles, and Karen Vines. 2002.
     _Output Analysis and Diagnostics for MCMC (CODA)_. <URL: 
     http://www-fis.iarc.fr/coda/>.

     Ori Rosen, Wenxin Jiang, Gary King, and Martin A. Tanner. 2001. 
     ``Bayesian and Frequentist Inference for Ecological Inference: The
     R x (C-1) Case.''  _Statistica Neerlandica_ 55: 134-156.

_S_e_e _A_l_s_o:

     'lambda.MD', 'cover.plot',  'density.plot', 'tuneMD',  'mergeMD'

