| Title: | Bayesian Estimation of Generalized Graded Unfolding ModelParameters |
| Version: | 1.0.2 |
| Date: | 2020-01-18 |
| Description: | Provides a Metropolis-coupled Markov chain Monte Carlo sampler, post-processing and parameter estimation functions, and plotting utilities for the generalized graded unfolding model of Roberts, Donoghue, and Laughlin (2000) <doi:10.1177/01466216000241001>. |
| URL: | https://github.com/duckmayr/bggum |
| BugReports: | https://github.com/duckmayr/bggum/issues |
| Depends: | R (≥ 3.5.0) |
| Imports: | stats, graphics, Rcpp (≥ 0.12.14) |
| LinkingTo: | Rcpp, RcppDist |
| License: | GPL-2 |GPL-3 [expanded from: GPL (≥ 2)] |
| Suggests: | devtools, testthat, covr, knitr, rmarkdown, dplyr, tidyr |
| Collate: | 'bggum-package.R' 'RcppExports.R' 'ggumProbability.R''tune_proposals.R' 'tune_temps.R' 'ggumMCMC.R' 'ggumMC3.R''ggum_simulation.R' 'color_palettes.R' 'irf.R' 'icc.R''summary.R' 'post_process.R' |
| Encoding: | UTF-8 |
| RoxygenNote: | 6.1.1 |
| VignetteBuilder: | knitr |
| NeedsCompilation: | yes |
| Packaged: | 2020-01-18 23:31:56 UTC; jb |
| Author: | JBrandon Duck-Mayr [aut, cre], Jacob Montgomery [aut], Patrick Silva [ctb], Luwei Ying [ctb] |
| Maintainer: | JBrandon Duck-Mayr <j.duckmayr@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2020-01-19 08:40:02 UTC |
bggum
Description
bggum provides R tools for the Bayesian estimation of generalized gradedunfolding model (Roberts, Donoghue, and Laughlin 2000) parameters.Please see the vignette (viavignette("bggum")) for a practicalguide to Bayesian estimation of GGUM parameters.Duck-Mayr and Montgomery (2019) provides a more detailed theoreticaldiscussion of Bayesian estimation of GGUM parameters.
Author(s)
JBrandon Duck-Mayr and Jacob Montgomery
References
Duck-Mayr, JBrandon, and Jacob Montgomery. 2019.“Ends Against the Middle: Scaling Votes When Ideological OppositesBehave the Same for Antithetical Reasons.”http://jbduckmayr.com/papers/ggum.pdf.
Roberts, James S., John R. Donoghue, and James E. Laughlin. 2000.“A General Item Response Theory Model for Unfolding UnidimensionalPolytomous Responses.”Applied Psychological Measurement24(1): 3–32.
Color palettes provided bybggum.
Description
bggum provides color palettes that can be used with its plotting functions.Theokabe_ito palette is the eight color, colorblind-friendly palettefrom Okabe and Ito (2008).Thetango palette is comprised of six colors from the Tango palette(Tango Desktop Project 2013).
Usage
okabe_ito(n)tango(n)Arguments
n | An integer vector of length one; the number of colors to return.If |
Palettes provided
- okabe_ito
c("#e69f00", "#56b4e9", "#009e73", "#f0e442","#0072b2", "#d55e00", "#cc79a7", "#000000")
- tango
c("#cc0000", "#75507b", "#73d216", "#f57900", "#3465a4","#555753")
References
Okabe, Masataka and Kei Ito. 2008.“Color Universal Design.”https://jfly.uni-koeln.de/color/.
Tango Desktop Project. 2013.“Tango Icon Theme Guidelines.”https://web.archive.org/web/20160202102503/http://tango.freedesktop.org/Tango_Icon_Theme_Guidelines
Examples
## Palettes that are a subset of the total available colorsokabe_ito(3)tango(3)## Palettes that need more colors than are available -- leads to recyclingokabe_ito(10)tango(10)GGUM MC3
Description
Metropolis Coupled Markov Chain Monte Carlo (MC3) Sampling for the GGUM
Usage
ggumMC3(data, sample_iterations = 10000, burn_iterations = 10000, sd_tune_iterations = 5000, temp_tune_iterations = 5000, temp_n_draws = 2500, swap_interval = 1, flip_interval = NA, n_temps = length(temps), temps = NULL, optimize_temps = TRUE, temp_multiplier = 0.1, 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, return_temps = TRUE)Arguments
data | An integer matrix giving the individuals' responses;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 giving the numberof iterations the sampler should complete (default is 10000) |
burn_iterations | An integer vector of length one giving the number ofiterations to burn in (default is 10000) |
sd_tune_iterations | An integer vector of length one; the number ofiterations to use to tune the proposals before the burn-in periodbegins (default is 5000). If 0 is given, the proposals are not tuned. |
temp_tune_iterations | An integer vector of length one; if atemperature schedule is not provided in the |
temp_n_draws | An integer vector of length one; if a temperatureschedule is not provided in the |
swap_interval | The period by which to attempt chain swaps;e.g. if swap_interval = 100, a state swap will be proposed between twoadjacent chains every 100 iterations (default is 1) |
flip_interval | (Optional) If given, provides the number of iterationsafter which the sign of the thetas and deltas should be changed.For example, if |
n_temps | The number of chains; should only be given if |
temps | (Optional) A numeric vector giving the temperatures;if not provided and |
optimize_temps | A logical vector of length one; if TRUE and atemperature schedule is not provided in the |
temp_multiplier | A numeric vector of length one; if a temperatureschedule is not provided and |
proposal_sds | (Optional) A list of length four where is element is anumeric vector giving standard deviations for the proposals;the first element should be a numeric vector with a standard deviationfor 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 deviationfor each item's delta (location) parameter, and the fourth a vector witha standard deviation for each item's tau (option threshold) parameters.If not given, the standard deviations are all set to 1.0 before anytuning begins. |
theta_init | (Optional) Either a numeric vector giving an initial valuefor each respondent's theta parameter, or a numeric matrix giving aninitial value for each respondent's theta parameter for each parallel chain;if not given, the initial values are drawn from the prior distribution |
alpha_init | (Optional) Either a numeric vector giving an initial valuefor each item's alpha parameter, or a numeric matrix giving aninitial value for each item's alpha parameter for each parallel chain;if not given, the initial values are drawn from the prior distribution |
delta_init | (Optional) Either a numeric vector giving an initial valuefor each item's delta parameter, or a numeric matrix giving aninitial value for each item's delta parameter for each parallel chain;if not given, the initial values are drawn from the prior distribution |
tau_init | (Optional) Either a list giving an initial valuefor each item's tau vector, or a list of lists giving aninitial value for each item's tau vector for each parallel chain;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' priordistribution (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' priordistribution (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' priordistribution (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 proposalstandard deviations are stored in an attribute of the returned objectnamed "proposal_sds." The default is TRUE. |
return_temps | A logical vector of length one; if TRUE, the temperaturesof the parallel chains are stored in an attribute of the returned objectnamed "temps." The default is TRUE. |
Details
ggumMC3 providesR implementation of the MC3 algorithmfrom Duck-Mayr and Montgomery (2019).Some details are provided in this help file, but please see the vignette(viavignette("bggum")) for a full in-depth practical guide toBayesian estimation of GGUM parameters.
Our sampler creates random initial values for the parameters of the model,according to their prior distributions.N parallel chains are run, each at a different inverse "temperature";the first "cold" chain has an inverse temperature of 1, and each subsequentchain has increasingly lower values (still greater than zero,i.e. fractional values).At each iteration, for each chain, new parameter values are proposedfrom a normal distribution with a mean of the current parameter value,and the proposal is accepted probabilistically using aMetropolis-Hastings acceptance ratio.The purpose of the chains' "temperatures" is to increase the probability ofaccepting proposals for chains other than the "cold" chain recorded forinference; the acceptance probability in the Metropolis-Hastingsupdate steps for parameter values are raised to the power of the chain'sinverse temperature.After everyswap_intervalth iteration of the sampler, a proposal ismade to swap states between adjacent chains as a Metropolis step.For details, please read the vignette viavignette("bggum"),or see Duck-Mayr and Montgomery (2019);see also Gill (2008) and Geyer (1991).
Before burn-in, the standard deviation of the proposal densities can betuned 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 argumentandsd_tune_iterations is greater than 0.
The temperature schedule can also be tuned using an implementation of thetemperature tuning algorithm in Atchadé, Roberts, and Rosenthal (2011).This is done if a temperature schedule is not provided as an argument andoptimize_temps = TRUE.If a temperature schedule is not provided andoptimize_temps = FALSE,each temperature T_t for t > 1 is given by1 / (1 +temp_multiplier * (t-1)), and T_1 = 1.
Value
A numeric matrix giving the parameter values at each iterationfor the cold chain.The matrix will additionally have classes "ggum"(so thatsummary.ggum can be called on the result)and "mcmc" with an "mcpar" attribute(so that functions from thecoda package can be used, e.g.to assess convergence).Ifreturn_sds isTRUE, the result also has an attribute"proposal_sds", which will be a list of length four giving the standarddeviations of the proposal densities for the theta, alpha, delta, andtau parameters respectively.Ifreturn_temps isTRUE, the result also has an attribute"temps", which will be a numeric vector giving the parallel chains'inverse temperatures.
References
Atchadé, Yves F., Gareth O. Roberts, and Jeffrey S. Rosenthal.2011. “Towards Optimal Scaling of Metropolis-Coupled Markov ChainMonte Carlo.”Statistics and Computing 21(4): 555–68.
Duck-Mayr, JBrandon, and Jacob Montgomery. 2019.“Ends Against the Middle: Scaling Votes When Ideological OppositesBehave the Same for Antithetical Reasons.”http://jbduckmayr.com/papers/ggum.pdf.
Geyer, Charles J. 1991. “Markov Chain Monte Carlo MaximumLikelihood.” In Computing Science and Statistics. Proceedings of the 23rdSymposium on the Interface, edited by E. M. Keramides, 156–63. FairfaxStation, VA: Interface Foundation.
Gill, Jeff. 2008.Bayesian Methods: A Social and BehavioralSciences Approach. 2d ed. Boca Raton, FL: Taylor & Francis.
See Also
ggumProbability,ggumMCMC,tune_temperatures
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 <- ggumMC3(data = sim_data$response_matrix, n_temps = 2, sd_tune_iterations = 100, temp_tune_iterations = 100, temp_n_draws = 50, burn_iterations = 100, sample_iterations = 100)GGUM MCMC Sampler
Description
MCMC sampler for the generalized graded unfolding model (GGUM), utilizinga 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 toeach 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 notstored (default is 50000). |
tune_iterations | An integer vector of length one; the number ofiterations to use to tune the proposals before the burn-in periodbegins (default is 5000). If 0 is given, the proposals are not tuned. |
flip_interval | (Optional) If given, provides the number of iterationsafter 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 anumeric vector giving standard deviations for the proposals;the first element should be a numeric vector with a standard deviationfor 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 deviationfor each item's delta (location) parameter, and the fourth a vector witha standard deviation for each item's tau (option threshold) parameters.If not given, the standard deviations are all set to 1.0 before anytuning begins. |
theta_init | (Optional) A numeric vector giving an initial valuefor 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 valuefor 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 valuefor 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 valuefor 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' priordistribution (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' priordistribution (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' priordistribution (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 proposalstandard deviations are stored in an attribute of the returned objectnamed "proposal_sds." The default is TRUE. |
Details
ggumMCMC providesR implementation of an MCMC sampler forthe GGUM, based heavily on the algorithm given in de la Torre et al (2006);though the package allows parameter estimation fromR,the functions are actually written inC++ to allow for reasonableexecution time.Some details are provided in this help file, but please see the vignette(viavignette("bggum")) for a full in-depth practical guide toBayesian 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 proposedfrom a normal distribution with a mean of the current parameter value,and the proposal is accepted probabilistically using a standardMetropolis-Hastings acceptance ratio.During burn-in, parameter draws are not stored.Before burn-in, the standard deviation of the proposal densities can betuned 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 argumentandsd_tune_iterations is greater than 0.
Value
A numeric matrix withsample_iterations rowsand one column for every parameter of the model, so that each elementof the matrix gives the value of a parameter for a particular iterationof the MCMC algorithm.The matrix will additionally have classes "ggum"(so thatsummary.ggum can be called on the result)and "mcmc" with an "mcpar" attribute(so that functions from thecoda package can be used, e.g.to assess convergence).Ifreturn_sds isTRUE, the result also has an attribute"proposal_sds", which will be a list of length four giving the standarddeviations of the proposal densities for the theta, alpha, delta, andtau parameters respectively.
References
de la Torre, Jimmy, Stephen Stark, and Oleksandr S.Chernyshenko. 2006. “Markov Chain Monte Carlo Estimation of ItemParameters for the Generalized Graded Unfolding Model.”AppliedPsychological Measurement 30(3): 216–232.
Geyer, Charles J. 1991. “Markov Chain Monte Carlo MaximumLikelihood.” In Computing Science and Statistics. Proceedings of the 23rdSymposium on the Interface, edited by E. M. Keramides, 156–63. FairfaxStation, VA: Interface Foundation.
Roberts, James S., John R. Donoghue, and James E. Laughlin. 2000.“A General Item Response Theory Model for Unfolding UnidimensionalPolytomous Responses.”Applied Psychological Measurement24(1): 3–32.
See Also
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)GGUM Probability Function
Description
Calculate the probability of a response according to the GGUM
Usage
ggumProbability(response, theta, alpha, delta, tau)Arguments
response | A numeric vector or matrix giving the response(s) for whichprobability should be calculated. |
theta | A numeric vector of latent trait score(s) for respondent(s) |
alpha | A numeric vector of discrimination parameter(s) |
delta | A numeric vector of location parameter(s) |
tau | A numeric vector (if responses to one item are given) or a list(if responses to multiple items are given); the tau parameters for eachitem is a numeric vector of length K (the number of possible responses)giving the options' threshold parameters; the first element of |
Details
The General Graded Unfolding Model (GGUM) is an item response modeldesigned to consider the possibility of disagreement for opposite reasons.This function gives the probability of a respondent's response to a testitem given item and respondent parameters. The user can calculate theprobability of one particular response to an item, for any number of thepossible responses to the item, the probability of a vector of responses(either responses by one person to multiple items, or by multiple people toone item), or the probability of each response in a response matrix.
The probability that respondenti chooses optionk for itemj is given by
\frac{\exp (\alpha_j [k (\theta_i - \delta_j) -\sum_{m=0}^k \tau_{jm}]) + \exp (\alpha_j [(2K - k - 1)(\theta_i - \delta_j) - \sum_{m=0}^k \tau_{jm}])}{%\sum_{l=0}^{K-1} [\exp (\alpha_j [l (\theta_i - \delta_j) -\sum_{m=0}^l \tau_{jm}]) + \exp (\alpha_j [(2K - l - 1)(\theta_i - \delta_j) - \sum_{m=0}^l \tau_{jm}])]}
,where\theta_i isi's latent trait parameter,\alpha_j is the item's discrimination parameter,\delta_j is the item's location parameter,\tau_{j0}, \ldots, \tau_{j(K-1)} are the options' thresholdparameters, and\tau_{j0} is 0,K is the number of options for itemj, andthe options are indexed byk = 0, \ldots, K-1.
Value
A matrix or vector of the same dimensions/length ofresponse.
Note
Please note that items' options should be zero-indexed.
References
de la Torre, Jimmy, Stephen Stark, and Oleksandr S.Chernyshenko. 2006. “Markov Chain Monte Carlo Estimation of ItemParameters for the Generalized Graded Unfolding Model.”AppliedPsychological Measurement 30(3): 216–232.
Roberts, James S., John R. Donoghue, and James E. Laughlin. 2000.“A General Item Response Theory Model for Unfolding UnidimensionalPolytomous Responses.”Applied Psychological Measurement24(1): 3–32.
Examples
## What is the probability of a 1 response to a dichotomous item## with discrimination parameter 2, location parameter 0, and## option threshold vector (0, -1) for respondents at -1, 0, and 1## on the latent scale?ggumProbability(response = rep(1, 3), theta = c(-1, 0, 1), alpha = 2, delta = 0, tau = c(0, -1))## We can also use this function for getting the probability of all## observed responses given the data and item and person parameter estimtes.## Here's an example of that with some simulated data:## Simulate data with 10 items, each with four options, and 100 respondentsset.seed(123)sim_data <- ggum_simulation(100, 10, 4)head(ggumProbability(response = sim_data$response_matrix, theta = sim_data$theta, alpha = sim_data$alpha, delta = sim_data$delta, tau = sim_data$tau))GGUM Simulation
Description
Generates randomly drawn item and person parameters, and simulated responses.
Usage
ggum_simulation(n, m, K, theta = NULL, alpha = NULL, delta = NULL, tau = NULL, theta_params = c(0, 1), alpha_params = c(1.5, 1.5, 0.25, 4), delta_params = c(2, 2, -5, 5), tau_params = c(1.5, 1.5, -2, 0))Arguments
n | An integer vector of length one giving the number of respondents |
m | An integer vector of length one giving the number of items |
K | An integer vector giving the number of options for each item;if the vector is of length one, all m items will have the same number ofoptions. |
theta | (Optional) A numeric vector of respondents' latent traits;if not given, the values are drawn from a normal distribution whosemean and standard deviation are given by the |
alpha | (Optional) A numeric vector of items' discrimination parameters;if not given, the values are drawn from a four parameter beta distributionwhose parameters are given by |
delta | (Optional) A numeric vector of items' location parameters;if not given, the values are drawn from a four parameter beta distributionwhose parameters are given by |
tau | (Optional) A list of numeric vectors giving each item's optionthresholds; if not given, the values are drawn from a four parameter betadistribution whose parameters are given by |
theta_params | A numeric vector of length two; the mean and standarddeviation of the normal distribution theta is drawn from |
alpha_params | A numeric vector of length four; the two shapeparameters and a and b values for the four parameter beta distributionalpha is drawn from; the default is 1.5, 1.5, 0.25, and 4 |
delta_params | A numeric vector of length four; the two shapeparameters and a and b values for the four parameter beta distributiondelta is drawn from; the default is 2, 2, -5, and 5 |
tau_params | A numeric vector of length four;the two shapeparameters and a and b values for the four parameter beta distributioneach tau vector is drawn from; the default is 1.5, 1.5, -2, and 0 |
Value
A list with five elements; "theta" containing the theta draws,"alpha" containing the alpha draws, "delta" containing the delta draws,"tau" containing the tau draws, and "response_matrix" containing thesimulated response matrix.
See Also
Examples
## Simulate data with 10 items, each with four options, and 100 respondentsset.seed(123)sim_data <- ggum_simulation(100, 10, 4)str(sim_data)Item Characteristic Curve
Description
Plots item characteristic curves given alpha, delta, and tau parameters.
Usage
icc(a, d, t, from = -3, to = 3, by = 0.01, layout_matrix = 1, main_title = "Item Characteristic Curve", sub = "", color = "black", plot_responses = FALSE, thetas = NULL, responses = NULL, response_color = "#0000005f")Arguments
a | A numeric vector of alpha parameters |
d | A numeric vector of delta parameters |
t | Either a list of numeric vectors for the tau parameters for eachoption, or a numeric vector if the IRF for only one item is desired –note the first element of each vector should be zero |
from | A numeric vector of length one,the lowest theta value to estimate response probabilities for;default is -3 |
to | A numeric vector of length one,the highest theta value to estimate response probabilities for;default is 3 |
by | A numeric vector of length one giving the spacing betweentheta values; default is 0.01 |
layout_matrix | An integer matrix dictating the layout of the plot;the default is a one-column matrix with one element for each item |
main_title | A character vector giving the plots' main titles;default is "Item Characteristic Curve". |
sub | An optional character vector of subtitles for the resulting plots,to be pasted onto the main title (helpful for titling individual plotswhen plotting multiple items' ICCs). |
color | The color to plot the ICC line in; default is "black" |
plot_responses | A logical vector of length one specifying whether todraw points at the theta estimates of actual responses; default is FALSE |
thetas | An optional vector of theta estimates for response drawing;if |
responses | An optional matrix or vector (if the ICC for only one itemis desired) of responses; if |
response_color | The color to plot the response points when |
Examples
## We'll simulate data to use for these examples:set.seed(123)sim_data <- ggum_simulation(100, 10, 4)## You can plot the ICC for one item:icc(sim_data$alpha[1], sim_data$delta[1], sim_data$tau[[1]])## Or multiple items:icc(sim_data$alpha[1:2], sim_data$delta[1:2], sim_data$tau[1:2], sub = 1:2)## You can also plot the actual responses over the expected response line:icc(sim_data$alpha[1], sim_data$delta[1], sim_data$tau[[1]], plot_responses = TRUE, responses = sim_data$response_matrix[ , 1], thetas = sim_data$theta)Item Response Function
Description
Plots response functions given alpha, delta, and tau parameters.
Usage
irf(a, d, t, from = -3, to = 3, by = 0.01, layout_matrix = 1, main_title = "Item Response Function", sub = "", option_names = NULL, line_types = NULL, color = "black", rug = FALSE, thetas = NULL, responses = NULL, sides = 1, rug_colors = "black")Arguments
a | A numeric vector of alpha parameters |
d | A numeric vector of delta parameters |
t | Either a list of numeric vectors for the tau parameters for eachoption, or a numeric vector if the IRF for only one item is desired –note the first element of each vector should be zero |
from | A numeric vector of length one,the lowest theta value to estimate response probabilities for;default is -3 |
to | A numeric vector of length one,the highest theta value to estimate response probabilities for;default is 3 |
by | A numeric vector of length one giving the spacing betweentheta values; default is 0.01 |
layout_matrix | An integer matrix dictating the layout of the plot;the default is a one-column matrix with one element for each item |
main_title | A character vector giving the plots' main titles;default is "Item Response Function". |
sub | An optional character vector of subtitles for the resulting plots,to be pasted onto the main title (helpful for titling individual plotswhen plotting multiple items' IRFs). |
option_names | An optional character vector giving names for the items'options; if NULL, generic names (e.g. "Option 1", "Option 2", etc.)are used |
line_types | An optional integer vector specifying lty for each option;if not provided, the first option for each question will have lty = 1,the second will have lty = 2, etc. |
color | A specification of the colors to draw lines in. Colors can bespecified by either a character vector of colors (either names that Rrecognizes or hexidecimal specifications) or a function taking a singleargument for the number of colors to return. See |
rug | A logical vector of length one specifying whether to draw arug of theta estimates; the default is FALSE |
thetas | An optional vector of theta estimates for rug drawing;if |
responses | An optional matrix or vector (if the IRF for only one itemis desired) of responses; if |
sides | A vector giving the side(s) to draw the rug on if |
rug_colors | A vector giving the color(s) to draw the rug in if |
Examples
## We'll simulate data to use for these examples:set.seed(123)sim_data <- ggum_simulation(100, 10, 4)## You can plot the IRF for one item:irf(sim_data$alpha[1], sim_data$delta[1], sim_data$tau[[1]], option_names = 0:3)## Or multiple items:irf(sim_data$alpha[1:2], sim_data$delta[1:2], sim_data$tau[1:2], option_names = 0:3, sub = 1:2)## You can plot it in color:irf(sim_data$alpha[1], sim_data$delta[1], sim_data$tau[[1]], option_names = 0:3, color = tango)## You can also plot a rug of the repsondents' theta estimates with the IRFirf(sim_data$alpha[1], sim_data$delta[1], sim_data$tau[[1]], rug = TRUE, responses = sim_data$response_matrix[ , 1], thetas = sim_data$theta, option_names = 0:3)Post-process a Posterior Sample
Description
Post-process the results ofggumMCMC orggumMC3using an artificial identifiability constraint (AIC).
Usage
post_process(sample, constraint, expected_sign)Arguments
sample | A numeric matrix of posterior draws as returned by |
constraint | An integer vector of length one giving the column numberof the parameter to constrain, or a character vector of length one givingthe column name for the constraint. |
expected_sign | A character vector of length one giving the sign forthe constraint; it should be either "-" if the constrained parameter isto be negative or "+" if the constrained parameter is to be positive. |
Details
Since under the GGUM the probability of a response is the same for any givenchoice of theta and delta parameters and the negative of that choice; i.e.
Pr(z | \theta, \alpha, \delta, \tau) = Pr(z | -\theta, \alpha, -\delta, \tau),
if symmetric priors are used, the posterior has a reflective mode.This function transforms a posterior sample by enforcing a constraintthat a particular parameter is of a given sign, essentially transformingit into a sample from only one of the reflective modes if a suitableconstraint is chosen; using a sufficiently extreme parameter is suggested.
Please see the vignette (viavignette("bggum")) for a full in-depthpractical guide to Bayesian estimation of GGUM parameters.
Value
A numeric matrix, the post-processed sample.
See Also
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 <- ggumMC3(data = sim_data$response_matrix, n_temps = 2, sd_tune_iterations = 100, temp_tune_iterations = 100, temp_n_draws = 50, burn_iterations = 100, sample_iterations = 100)## Then you can post-process the outputprocessed_draws <- post_process(sample = draws, constraint = which.min(sim_data$theta), expected_sign = "-")Summarize Posterior Draws for GGUM Parameters
Description
Summarize the results ofggumMCMC orggumMC3.
Usage
## S3 method for class 'ggum'summary(object, ...)## S3 method for class 'list'summary(object, ..., combine = TRUE)Arguments
object | A numeric matrix of posterior draws as returned by |
... | Arguments to be passed to or from other methods |
combine | A logical vector of length one; if |
Details
This function provides the posterior mean, median, standard deviation,and 0.025 and 0.975 quantiles for GGUM parameters from posterior samplesdrawn usingggumMCMC orggumMC3.Please note that the quantiles are calculated using the type 8 algorithmfrom Hyndman and Fan (1996), as suggested by Hyndman and Fan (1996), ratherthan the type 7 algorithm that would be the default from R'squantile()).Before calling this function, care should be taken to ensure thatpost-processing has been done if necessary to identify the correctreflective posterior mode, as discussed in the vignette and Duck-Mayr andMontgomery (2019).
Please see the vignette (viavignette("bggum")) for a full in-depthpractical guide to Bayesian estimation of GGUM parameters.
Value
A list with three elements: estimates (a list of length four;a numeric vector giving the means of the theta draws, a numeric vectorgiving the means of the alpha draws, a numeric vector giving the meansof the delta draws, and a list where the means of the tau draws arecollated into a tau estimate vector for each item), sds (a list of lengthfour giving the posterior standard deviations for the theta, alpha, delta,and tau draws), and statistics (a matrix with five columns and one rowfor each parameter giving the 0.025 quantile, the 0.5 quantile, the mean,the 0.975 quantile, and the standard deviation of the posterior drawsfor each parameter; please note the quantiles are calculated using thetype 8 algorithm from Hyndman and Fan 1996, as suggested by Hyndman andFan 1996, rather than the type 7 algorithm that would be the defaultfrom R'squantile()).
Ifobject is a list andcombine isFALSE,a list of such lists will be returned.
References
Duck-Mayr, JBrandon, and Jacob Montgomery. 2019.“Ends Against the Middle: Scaling Votes When Ideological OppositesBehave the Same for Antithetical Reasons.”http://jbduckmayr.com/papers/ggum.pdf.
Hyndman, R. J. and Fan, Y. 1996. “Sample Quantiles inPackages.”American Statistician 50, 361–365.
See Also
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 <- ggumMC3(data = sim_data$response_matrix, n_temps = 2, sd_tune_iterations = 100, temp_tune_iterations = 100, temp_n_draws = 50, burn_iterations = 100, sample_iterations = 100)## Then post-process the outputprocessed_draws <- post_process(sample = draws, constraint = which.min(sim_data$theta), expected_sign = "-")## And now we can obtain a summary of the posteriorposterior_summary <- summary(processed_draws)## It contains all the parameter estimatesstr(posterior_summary$estimates)## As well as the posterior standard deviationsstr(posterior_summary$sds)## And a matrix of the mean (estimates), median, standard deviations,## and 0.025 and 0.975 quantileshead(posterior_summary$statistics)Tune proposal densities
Description
Tunes the standard deviation for the parameters' proposal densities
Usage
tune_proposals(data, tune_iterations, K = NULL, thetas = NULL, alphas = NULL, deltas = NULL, taus = 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))Arguments
data | An integer matrix giving the response by eachrespondent to each item |
tune_iterations | An integer vector of length one;the number of iterations to complete |
K | (Optional) A numeric vector with an element for each item givingthe number of options for the item; if not provided, it is generated bytaking the number of unique options observed in the data |
thetas | (Optional) A numeric vector giving an initial valuefor each respondent's theta parameter;if not given, the initial values are drawn from the prior distribution |
alphas | (Optional) A numeric vector giving an initial valuefor each item's alpha parameter;if not given, the initial values are drawn from the prior distribution |
deltas | (Optional) A numeric vector giving an initial valuefor each item's delta parameter;if not given, the initial values are drawn from the prior distribution |
taus | (Optional) A list giving an initial valuefor 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' priordistribution (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' priordistribution (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' priordistribution (where the tau parameters have a four parameter beta prior;the default is 2, 2, -6, and 6) |
Details
This function runs the MCMC algorithm for the number of iterationsspecified intune_iterations, updating parameter values at eachiteration. Every 100 iterations, the function determines how manyof the previous 100 iterations resulted in an accepted proposal foreach parameter. If the number of acceptances was less than 20,the standard deviation of the proposal for that parameter isdecreased by (20 - N) * 0.01, where N is the number of acceptances inthe previous 100 iterations. If N is greater than 25, the proposalstandard deviation is increased by (N - 25) * 0.01.
Please see the vignette (viavignette("bggum")) for a full in-depthpractical guide to Bayesian estimation of GGUM parameters.
Value
A list, where each element is a numeric vector;the first element is a numeric vector of standard deviations for thetheta parameters' proposals, the second for the alpha parameters, thethird for the delta parameters, and the fourth for the tau parameters
Warning
The parameters are updated in place;that is, if you supply objects for thetheta,alpha,delta, andtau arguments, the objects will not hold thesame values after the function is run(in the underlying C++ function, these objects are passed by reference).
Examples
## NOTE: This is a toy example just to demonstrate the function, which uses## a small dataset and an unreasonably low number of tuning 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 exampleset.seed(123)sim_data <- ggum_simulation(100, 10, 2)## Now we can tune the proposal densities## (for the purposes of example, we use 100 iterations,## though in practice you would use much more)proposal_sds <- tune_proposals(data = sim_data$response_matrix, tune_iterations = 100)tune_temperatures
Description
Find Optimal Temperatures for the GGUM MCMCMC Sampler
Usage
tune_temperatures(data, n_temps, temp_tune_iterations = 5000, n_draws = 2500, K = NULL, proposal_sds = NULL, sd_tune_iterations = 5000, 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))Arguments
data | An integer matrix giving the response by eachrespondent to each item |
n_temps | How many temperatures to make? |
temp_tune_iterations | How many iterations should the temperaturetuning algorithm run for each temperature? (default is 5000) |
n_draws | How many draws should be used to determine each temperature?(specifying n_draws < temp_tune_iterations will result in an error;default is 2500). |
K | (Optional) A numeric vector with an element for each item givingthe number of options for the item; if not provided, it is generated bytaking the number of unique options observed in the data |
proposal_sds | (Optional) A list of length four where is element is anumeric vector giving standard deviations for the proposals;the first element should be a numeric vector with a standard deviationfor 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 deviationfor each item's delta (location) parameter, and the fourth a vector witha standard deviation for each item's tau (option threshold) parameters.If not given, the standard deviations are all set to 1.0 before anytuning begins. |
sd_tune_iterations | A numeric vector of length one; if proposalstandard deviations are not given, this provides the number ofiterations to use to tune the proposals before the temperature findingalgorithm begins (default is 5000) |
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' priordistribution (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' priordistribution (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' priordistribution (where the tau parameters have a four parameter beta prior;the default is 2, 2, -6, and 6) |
Details
Atchadé, Roberts, and Rosenthal (2011) determine the optimal swap-acceptancerate for Metropolis-coupled MCMC and provide an algorithm for buildingoptimal temperature schedules. We implement this algorithm in the context ofthe GGUM to provide a temperature schedule that should result inapproximately 0.234 swap acceptance rate between adjacent chains.
Please see the vignette (viavignette("bggum")) for a full in-depthpractical guide to Bayesian estimation of GGUM parameters.
Value
A numeric vector of temperatures
References
Atchadé, Yves F., Gareth O. Roberts, and Jeffrey S. Rosenthal.2011. “Towards Optimal Scaling of Metropolis-Coupled Markov ChainMonte Carlo.”Statistics and Computing 21(4): 555–68.
See Also
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 tune the temperature schedule:## (for the purposes of example, we use 100 iterations,## though in practice you would use much more)temps <- tune_temperatures(data = sim_data$response_matrix, n_temps = 5, temp_tune_iterations = 100, n_draws = 50, sd_tune_iterations = 100)