recovery_irtree: Recovery simulation of mpt2irt models.

In hplieninger/mpt2irt: Bringing Multinomial Processing Tree Models To Item Response Theory To Investigate Response Styles

Description

This function allows to run a simulation study of mpt2irt models. Data are generated either from the Boeckenholt Model (genModel = "2012") or from the Acquiescence Model (genModel = "ext"). Subsequently, one or both of these models are fit to the generated data using either JAGS or Stan. The results are saved in an RData file in dir.

Usage

recovery_irtree(rrr = NULL, N = NULL, J = NULL, prop.rev = 0.5,
  genModel = c("ext", "2012"), fitModel = c("ext", "2012", "pcm",
  "steps", "shift", "ext2"), fitMethod = c("stan", "jags"),
  theta_vcov = NULL, betas = NULL, beta_ARS_extreme = NULL,
  df = NULL, V = NULL, M = 500, n.chains = 3, thin = 1,
  warmup = 500, method = "simple", outFormat = NULL,
  startSmall = FALSE, df_vcov = 50, dir = NULL, keep_mcmc = FALSE,
  savext_all = FALSE, savext_mcmc = TRUE, add2varlist = c("deviance",
  "pd", "popt", "dic"), ...)

Arguments

rrr	Sequence of integers (e.g., 1:100) of length greater or equal to 1 specifying the number of replications to run.
N	number of persons
J	number of items. Can be a vector for multiple traits (e.g., J=c(10,10,10)).
prop.rev	number of reversed items. Can be a vector for multiple traits(e.g., prop.rev=c(5,3,5)/10)
genModel	Character. The data generating model (either "2012" or "ext").
fitModel	Character. The model for data analysis ("2012", "ext", or both as vector c("2012", "ext")).
fitMethod	Character. Whether to use "stan" or "jags".
theta_vcov	true covariance matrix of response processes (order: middle, extreme, (acquiescence), trait). standard is diag(3) / diag(4). Can be a vector of variances (not SDs).
betas	Optional list. May have entries "beta.mrs", "beta.ers", "beta.trait", and/or "beta.ars". Each of those may have arguments passed to rtruncnorm.
beta_ARS_extreme	Numeric. Only for genModel="ext": probability (on probit scale) of choosing category 5 (vs.4) in case of ARS. Defaults to rtruncnorm(mean = qnorm(.7), sd = sqrt(.1), a = qnorm(.5), b = qnorm(.9)).
df	degrees of freedom for wishart prior on covariance of traits (default: number of processes + 1)
V	prior for wishart distribution (default: diagonal matrix)
M	number of MCMC samples (after warmup)
n.chains	number of MCMC chains (and number of CPUs used)
thin	thinning of MCMC samples
warmup	number of samples for warmup (in JAGS: 1/5 for adaptation, 4/5 for burnin)
method	Passed to run.jags. Can be, for example, parallel or simple.
outFormat	either "mcmc.list" (can be analyzed with coda package) or "stan" or "runjags"
startSmall	Whether to use random starting values for beta sampled from "wide" (FALSE) or "narrow" priors (TRUE; beta and theta closer to 0; might solve problems with slow convergence of some chains for extreme starting values).
df_vcov	Numeric. Degrees of freedom for wishart distribution from which the variance-covariance matrix for generating the data is drawn.
dir	Path to directory where results should be stored,
keep_mcmc	Logical indicating wheter to retain, besides a summary of the parameters, the raw mcmc samples.
savext_all	Logical indicating wheter to save the output from Stan/JAGS in an external RData file.
savext_mcmc	Logical indicating wheter to save the mcmc samples in an external RData file.
add2varlist	Additional variables to monitor (e.g., c("deviance", "pd", "popt", "dic") for JAGS)
...	further arguments passed to sampling (for Stan) or run.jags (for JAGS)

Details

Note that a text file "progress.txt" is written (and updated) to dir informing you about the progress of the simulation.

Value

Function does not directly return anything but saves an external RData file to dir. This object is a list containing the generated parameters in sim-results$param.sum$gen, fitted parameters and other model fit information in sim-results$param.sum$foo, as well as a summary of the setup.

Examples

## Not run: 
recovery_irtree(rrr = 1:2, N = 20, J = 10, genModel = "ext", fitModel = "ext",
                fitMethod = "stan", M = 200, n.chains = 2, warmup = 200,
                dir = "~/")
                
# run multiple simulations in parallel using the 'parallel' package
no_cores <- parallel::detectCores() - 1
cl <- parallel::makeCluster(no_cores)
parallel::clusterApplyLB(cl, x = 11:13, fun = recovery_irtree, cores = 1,
                         N = 20, J = 10, genModel = "ext", fitModel = "ext",
                         fitMethod = "stan", M = 200, n.chains = 2, warmup = 200,
                         dir = "~/")
parallel::stopCluster(cl = cl)

## End(Not run)

hplieninger/mpt2irt documentation built on May 17, 2019, 4:54 p.m.