ggumMCMC {bggum} | R Documentation |

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

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)

`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 |

`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 |

`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. |

`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.

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.

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.

## 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)

[Package *bggum* version 1.0.2 Index]