Title: Bayesian Multidimensional Generalized Graded Unfolding Model
Version: 0.1.0
Date: 2021-4-8
Description: Full Bayesian estimation of Multidimensional Generalized Graded Unfolding Model (MGGUM) using 'rstan' (See Stan Development Team (2020) https://mc-stan.org/). Functions are provided for estimation, result extraction, model fit statistics, and plottings.
License: GPL (≥ 3)
Encoding: UTF-8
RoxygenNote: 7.1.1.9000
Biarch: true
Depends: R (≥ 3.4.0)
Imports: methods, Rcpp (≥ 0.12.0), RcppParallel (≥ 5.0.1), rstan (≥ 2.18.1), rstantools (≥ 2.1.1), edstan, ggplot2, GGUM, loo, stats
LinkingTo: BH (≥ 1.66.0), Rcpp (≥ 0.12.0), RcppEigen (≥ 0.3.3.3.0), RcppParallel (≥ 5.0.1), rstan (≥ 2.18.1), StanHeaders (≥ 2.18.0)
SystemRequirements: GNU make
Suggests: knitr, rmarkdown
VignetteBuilder: knitr
URL: https://github.com/Naidantu/bmggum
BugReports: https://github.com/Naidantu/bmggum/issues
NeedsCompilation: yes
Packaged: 2021-04-08 14:16:41 UTC; NaidanTu
Author: Naidan Tu [aut, cre], Bo Zhang [aut]
Maintainer: Naidan Tu <naidantu@usf.edu>
Repository: CRAN
Date/Publication: 2021-04-09 08:50:06 UTC

The 'bmggum' package.

Description

Full Bayesian estimation of Multidimensional Generalized Graded Unfolding Model (MGGUM)

References

Stan Development Team (2020). RStan: the R interface to Stan. R package version 2.21.2. https://mc-stan.org

bayesian convergence diagnosis plotting function

Description

This function provides plots including density plots, trace plots, and auto-correlation plots to aid model convergence diagnosis.

Usage

bayesplot(x, pars, plot, inc_warmup = FALSE)

Arguments

x

returned object

pars

Names of plotted parameters. They can be "theta", "alpha", "delta", "tau", "cor", "lambda", or a subset of parameters. See vignette for bmggum for more details.

plot

Types of plots.They can be "density", "trace", or "autocorrelation".

inc_warmup

Whether to include warmup iterations or not when plotting. The default is FALSE.

Value

Selected plots for selected parameters

Examples

Data <- c(1,4,2,3)
Data <- matrix(Data,nrow = 2)
deli <- c(1,-1,2,1)
deli <- matrix(deli,nrow = 2)
ind <- c(1,2)
ind <- t(ind)
cova <- c(0.70, -1.25)
mod <- bmggum(GGUM.Data=Data,delindex=deli,trait=2,ind=ind,option=4,covariate=cova,iter=5,chains=1)
bayesplot(mod, 'alpha', 'density', inc_warmup=FALSE)

Bayesian Multidimensional Generalized Graded Unfolding Model (bmggum)

Description

This function implements full Bayesian estimation of Multidimensional Generalized Graded Unfolding Model (MGGUM) using rstan

Usage

bmggum(
  GGUM.Data,
  delindex,
  trait,
  ind,
  option,
  model = "UM8",
  covariate = NULL,
  iter = 1000,
  chains = 3,
  warmup = floor(iter/2),
  adapt_delta = 0.9,
  max_treedepth = 15,
  init = "random",
  thin = 1,
  cores = 2,
  ma = 0,
  va = 0.5,
  mdne = -1,
  mdnu = 0,
  mdpo = 1,
  vd = 1,
  mt = seq(-3, 0, 3/(option - 1)),
  vt = 2
)

Arguments

GGUM.Data

Response data in wide format

delindex

A two-row data matrix: the first row is the item number (1, 2, 3, 4...); the second row indicates the signs of delta for each item (-1,0,1,...). For items that have negative deltas for sure, "-1" should be assigned; for items that have positive deltas, "1" should be assigned; for items whose deltas may be either positive or negative (e.g., intermediate items), "0" should assigned. We recommend at least two positive and two negative items per trait for better estimation.

trait

The number of latent traits.

ind

A row vector mapping each item to each trait. For example, c(1, 1, 1, 2, 2, 2) means that the first 3 items belong to trait 1 and the last 3 items belong to trait 2.

option

The number of response options.

model

Models fitted. They can be "UM8", "UM7", and "UM4". The default is UM8, which is the GGUM model. UM4 is UM8 with alpha = 1, called partial credit unfolding model. UM7 is UM8 with equal taus across items, called generalized rating scale unfolding model.

covariate

An p*c person covariate matrix where p equals sample size and c equals the number of covariates. The default is NULL, meaning no person covariate.

iter

The number of iterations. The default value is 1000. See documentation for rstan for more details.

chains

The number of chains. The default value is 3. See documentation for rstan for more details.

warmup

The number of warmups to discard. The default value is 0.5*iterations. See documentation for rstan for more details.

adapt_delta

Target average proposal acceptance probability during Stan's adaptation period. The default value is 0.90. See documentation for rstan for more details.

max_treedepth

Cap on the depth of the trees evaluated during each iteration. The default value is 15. See documentation for rstan for more details.

init

Initial values for estimated parameters. The default is random initial values. See documentation for rstan for more details.

thin

Thinning. The default value is 1. See documentation for rstan for more details.

cores

The number of computer cores used for parallel computing. The default value is 2.

ma

Mean of the prior distribution for alpha, which follows a lognormal distribution. The default value is 0.

va

Standard deviation of the prior distribution for alpha. The default value is 0.5.

mdne

Mean of the prior distribution for negative deltas, which follows a normal distribution. The default value is -1.

mdnu

Mean of the prior distribution for neutral deltas, which follows a normal distribution. The default value is 0.

mdpo

Mean of the prior distribution for positive deltas, which follows a normal distribution. The default value is 1.

vd

Standard deviation of the prior distribution for deltas. The default value is 1.

mt

Means of the prior distributions for taus, which follows a normal distribution. The default values are seq(-3, 0, 3/(options-1)). The last one has to be 0. For items with only 2 options, we recommend to use (-2, 0) as means of priors.

vt

Standard deviation of the prior distribution for taus. The default value is 2.

Value

Result object that stores information including the (1) stanfit object, (2) estimated item parameters, (3) estimated person parameters, (4) correlations among traits, (5) regression coefficients linking person covariates to each trait, (6) response data (excluding respondents who endorse a single option across all items), and (7) the input row vector mapping each item to each trait. Note that when covariates are included, output (4) represents residual correlations among the traits after controlling for the covariates.

Examples

Data <- c(1,4,2,3)
Data <- matrix(Data,nrow = 2)
deli <- c(1,-1,2,1)
deli <- matrix(deli,nrow = 2)
ind <- c(1,2)
ind <- t(ind)
cova <- c(0.70, -1.25)
mod <- bmggum(GGUM.Data=Data,delindex=deli,trait=2,ind=ind,option=4,covariate=cova,iter=5,chains=1)

results extraction

Description

This function extracts estimation results.

Usage

extract(x, pars)

Arguments

x

returned object

pars

Names of extracted parameters. They can be "theta" (person trait estimates), "alpha" (item discrimination parameters), "delta" (item location parameters), "tau" (item threshold parameters), "cor" (correlations among latent traits), "lambda" (regression coefficients linking person covariates to latent traits), "data" (GGUM.Data after deleting respondents who endorse the same response options across all items), "fit" (the stanfit object), and "dimension" (the input row vector mapping each item to each trait). Note that when the model is UM4 in which alpha is fixed to 1, the extracted alpha is a n*1 matrix where n equals to the number of items.

Value

Selected results output

Examples

Data <- c(1,4,2,3)
Data <- matrix(Data,nrow = 2)
deli <- c(1,-1,2,1)
deli <- matrix(deli,nrow = 2)
ind <- c(1,2)
ind <- t(ind)
cova <- c(0.70, -1.25)
mod <- bmggum(GGUM.Data=Data,delindex=deli,trait=2,ind=ind,option=4,covariate=cova,iter=5,chains=1)
alpha <- extract(mod, 'alpha')

item plotting function including observable response categories (ORCs)

Description

This function provides item plots including observable response categories plots.

Usage

itemplot(x, items = NULL)

Arguments

x

returned object

items

The items to be plotted. The default is all the items.

Value

Selected ORC plots for selected items

Examples

Data <- c(1,4,2,3)
Data <- matrix(Data,nrow = 2)
deli <- c(1,-1,2,1)
deli <- matrix(deli,nrow = 2)
ind <- c(1,2)
ind <- t(ind)
cova <- c(0.70, -1.25)
mod <- bmggum(GGUM.Data=Data,delindex=deli,trait=2,ind=ind,option=4,covariate=cova,iter=5,chains=1)
itemplot(mod, items=1)

Model fit

Description

This function provides model fit statistics.

Usage

modfit(x, index = "loo")

Arguments

x

returned object

index

Model fit indices. They can be "waic", which is the widely applicable information criterion, "loo", which is the leave-one-out cross-validation, or "chisq.df", which is the adjusted chi-square degrees of freedom ratios for each trait separately that were introduced by Drasgow et al. (1995). The default is loo. Note that chisq.df can only be computed when the sample size is large. See documentation for loo and GGUM for more details.

Value

Selected model fit statistics

Examples

Data <- c(1,4,2,3)
Data <- matrix(Data,nrow = 2)
deli <- c(1,-1,2,1)
deli <- matrix(deli,nrow = 2)
ind <- c(1,2)
ind <- t(ind)
cova <- c(0.70, -1.25)
mod <- bmggum(GGUM.Data=Data,delindex=deli,trait=2,ind=ind,option=4,covariate=cova,iter=5,chains=1)
waic <- modfit(mod, 'waic')