ei.MD.bayes {eiPack}R Documentation

Multinomial Dirichlet model for Ecological Inference in RxC tables

Description

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

Usage

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

Arguments

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)
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 Desired number of draws to be returned from chain (defaults to 1000).
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 verboseth iteration.
ret.beta A character indicating how the posterior draws of beta should be handled: return as an R object, save as .txt.gz files, discard (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).

Details

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, gamma_rC and delta_rC are given improper uniform priors, while the prior for d_r is:

d_r ~ Gamma(lambda_1, lambda_2)

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 unreasonable, including an appropriate covariate can 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.

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:

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

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

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

Value

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:
    Dr
    Posterior draws for Dr parameters as an R xsample matrix. If ret.mcmc = TRUE, Dr is an mcmc object.
    Beta
    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
    Gamma
    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
    Delta
    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
    Cell.count
    Posterior draws for the cell counts. 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:
    Alpha
    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
    Beta
    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
    Cell.count
    Posterior draws for the cell counts. If ret.mcmc = TRUE, a (R * C) x sample matrix saved as anmcmc 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:
    dr.acc
    A vector of acceptance ratios for Dr draws
    beta.acc
    A vector of acceptance ratios for Beta draws
    gamma.acc
    A vector of acceptance ratios for Gamma and Delta draws
If the model is fit without a covariate , the list includes:
    alpha.acc
    A vector of acceptance ratios for Alpha draws
    beta.acc
    A vector of acceptance ratios for Beta draws
usrfun Output from the optional usrfn
call Call to ei.MD.bayes

Author(s)

Michael Kellermann <kellerm@fas.harvard.edu> and Olivia Lau <olau@fas.harvard.edu>

References

Martyn Plummer, Nicky Best, Kate Cowles, and Karen Vines. 2002. Output Analysis and Diagnostics for MCMC (CODA). 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.

See Also

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


[Package eiPack version 0.1-1 Index]