recovery_irtree: Recovery simulation of mpt2irt models.

Description Usage Arguments Details Value Examples

View source: R/simulation.R

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

1
2
3
4
5
6
7
8
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
## 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 Aug. 4, 2018, 10:52 a.m.