ggumMCMC {bggum}

GGUM MCMC Sampler

Description

MCMC sampler for the generalized graded unfolding model (GGUM), utilizing a Metropolis-Hastings algorithm

Usage

ggumMCMC(data, sample_iterations = 50000, burn_iterations = 50000,
  tune_iterations = 5000, flip_interval = NA, proposal_sds = NULL,
  theta_init = NULL, alpha_init = NULL, delta_init = NULL,
  tau_init = NULL, theta_prior_params = c(0, 1),
  alpha_prior_params = c(1.5, 1.5, 0.25, 4), delta_prior_params = c(2,
  2, -5, 5), tau_prior_params = c(2, 2, -6, 6), return_sds = TRUE)

Arguments

data

An integer matrix giving the response by each respondent to each item; note the item options should be of the form 0, 1, ... (an example of preparing data for analysis is given in the vignette, available via vignette("bggum"))

sample_iterations

An integer vector of length one; the number of iterations the sampler should store (default is 50000)

burn_iterations

An integer vector of length one; the number of "burn-in" iterations to run, during which parameter draws are not stored (default is 50000).

tune_iterations

An integer vector of length one; the number of iterations to use to tune the proposals before the burn-in period begins (default is 5000). If 0 is given, the proposals are not tuned.

flip_interval

(Optional) If given, provides the number of iterations after which the sign of the thetas and deltas should be changed. For example, if flip_interval = 1000, every 1000 iterations the theta and delta parameters will be multiplied by -1 (a valid parameter value change as discussed in Geyer (1991)).

proposal_sds

(Optional) A list of length four where is element is a numeric vector giving standard deviations for the proposals; the first element should be a numeric vector with a standard deviation for the proposal for each respondent's theta parameter (the latent trait), the second a vector with a standard deviation for each item's alpha (discrimination) parameter, the third a vector with a standard deviation for each item's delta (location) parameter, and the fourth a vector with a standard deviation for each item's tau (option threshold) parameters. If not given, the standard deviations are all set to 1.0 before any tuning begins.

theta_init

(Optional) A numeric vector giving an initial value for each respondent's theta parameter; if not given, the initial values are drawn from the prior distribution

alpha_init

(Optional) A numeric vector giving an initial value for each item's alpha parameter; if not given, the initial values are drawn from the prior distribution

delta_init

(Optional) A numeric vector giving an initial value for each item's delta parameter; if not given, the initial values are drawn from the prior distribution

tau_init

(Optional) A list giving an initial value for each item's tau vector; if not given, the initial values are drawn from the prior distribution

theta_prior_params

A numeric vector of length two; the mean and standard deviation of theta parameters' prior distribution (where the theta parameters have a normal prior; the default is 0 and 1)

alpha_prior_params

A numeric vector of length four; the two shape parameters and a and b values for alpha parameters' prior distribution (where the alpha parameters have a four parameter beta prior; the default is 1.5, 1.5, 0.25, and 4)

delta_prior_params

A numeric vector of length four; the two shape parameters and a and b values for delta parameters' prior distribution (where the delta parameters have a four parameter beta prior; the default is 2, 2, -5, and 5)

tau_prior_params

A numeric vector of length four; the two shape parameters and a and b values for tau parameters' prior distribution (where the tau parameters have a four parameter beta prior; the default is 2, 2, -6, and 6)

return_sds

A logical vector of length one; if TRUE, the proposal standard deviations are stored in an attribute of the returned object named "proposal_sds." The default is TRUE.

Details

ggumMCMC provides R implementation of an MCMC sampler for the GGUM, based heavily on the algorithm given in de la Torre et al (2006); though the package allows parameter estimation from R, the functions are actually written in C++ to allow for reasonable execution time. Some details are provided in this help file, but please see the vignette (via vignette("bggum")) for a full in-depth practical guide to Bayesian estimation of GGUM parameters.

Our sampler creates random initial values for the parameters of the model, according to their prior distributions. At each iteration, new parameter values are proposed from a normal distribution with a mean of the current parameter value, and the proposal is accepted probabilistically using a standard Metropolis-Hastings acceptance ratio. During burn-in, parameter draws are not stored. Before burn-in, the standard deviation of the proposal densities can be tuned to ensure that the acceptance rate is neither too high nor too low (we keep the acceptance rate between 0.2 and 0.25). This is done if proposal standard deviations are not provided as an argument and sd_tune_iterations is greater than 0.

Value

A numeric matrix with sample_iterations rows and one column for every parameter of the model, so that each element of the matrix gives the value of a parameter for a particular iteration of the MCMC algorithm. The matrix will additionally have classes "ggum" (so that summary.ggum can be called on the result) and "mcmc" with an "mcpar" attribute (so that functions from the coda package can be used, e.g. to assess convergence). If return_sds is TRUE, the result also has an attribute "proposal_sds", which will be a list of length four giving the standard deviations of the proposal densities for the theta, alpha, delta, and tau parameters respectively.

References

de la Torre, Jimmy, Stephen Stark, and Oleksandr S. Chernyshenko. 2006. “Markov Chain Monte Carlo Estimation of Item Parameters for the Generalized Graded Unfolding Model.” Applied Psychological Measurement 30(3): 216–232.

Geyer, Charles J. 1991. “Markov Chain Monte Carlo Maximum Likelihood.” In Computing Science and Statistics. Proceedings of the 23rd Symposium on the Interface, edited by E. M. Keramides, 156–63. Fairfax Station, VA: Interface Foundation.

Roberts, James S., John R. Donoghue, and James E. Laughlin. 2000. “A General Item Response Theory Model for Unfolding Unidimensional Polytomous Responses.” Applied Psychological Measurement 24(1): 3–32.

See Also

ggumProbability, ggumMC3

Examples

## NOTE: This is a toy example just to demonstrate the function, which uses
## a small dataset and an unreasonably low number of sampling interations.
## For a longer practical guide on Bayesian estimation of GGUM parameters,
## please see the vignette ( via vignette("bggum") ).
## We'll simulate data to use for this example:
set.seed(123)
sim_data <- ggum_simulation(100, 10, 2)
## Now we can generate posterior draws:
## (for the purposes of example, we use 100 iterations,
## though in practice you would use much more)
draws <- ggumMCMC(data = sim_data$response_matrix,
                  tune_iterations = 100,
                  burn_iterations = 100,
                  sample_iterations = 100)