irtree_sim: Run a simulation by generating from and fitting an...

Description Usage Arguments Value See Also Examples

View source: R/simulation.R

Description

The function irtree_sim() generates data from an irtree_model and fits one or more models to these data. This process is repeated R times, and the argument plan allows to run the simulation in parallel.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
irtree_sim(
  R = 1,
  gen_model = NULL,
  fit_model = gen_model,
  N = NULL,
  sigma = NULL,
  itempar = NULL,
  link = c("logit", "probit"),
  na_okay = TRUE,
  engine = c("mirt", "mplus", "tam"),
  verbose = FALSE,
  control = NULL,
  improper_okay = FALSE,
  par_type = "difficulty",
  plan = NULL,
  plan_args = list(),
  file = NULL,
  dir = tempdir(),
  save_rdata = TRUE,
  in_memory = c("reduced", "everything", "nothing")
)

Arguments

R

Number of replications. Can be either a single number indicating the number of replications (e.g., R = 100), or can be a range (e.g., R = 1:100).

gen_model

Object of class irtree_model describing the data-generating model. See irtree_model for more information.

fit_model

Object of class irtree_model describing the model that should be fit to the data. May be a list of multiple objects of class irtree_model if different models should be fit to the same data set. See irtree_model for more information.

N

Integer, the number of persons.

sigma

Either a matrix or a function that returns a matrix. This matrix is the variance-covariance matrix of the person parameters that is passed to MASS::mvrnorm(). Note that the order of the person parameters is taken from the section Processes in the model object (see irtree_model).

itempar

Either a list or a function that returns a list. The list has an element beta and an element alpha. Each of these is a matrix of item parameters. Note that the order of items (rows) is taken from the section Items and the order of processes (columns) is taken from the section Processes in the model (see irtree_model).

link

Character. Link function to use.

na_okay

Logical indicating whether variables with unobserved response categories are permitted. If FALSE, rejection sampling is used to ensure that all categories are observed.

engine

String specifying whether to use mirt, Mplus, or TAM for estimation.

verbose

Logical indicating whether output should be printed to the console.

control

List. The allowed elements of this list depend on the engine. Use control_mirt(), control_mplus(), or control_tam() for convenience. Note that the fit() function does not use ..., but that you can use the control_*() functions to pass additional arguments.

improper_okay

Logical indicating whether the model should also be fit if it is not a proper IR-tree model. Set this only to TRUE if you really know what you are doing.

par_type

Only used if the fit engine was mirt. Item parameters (or thresholds) can be either of type easiness (the mirt default) or difficulty (as in Mplus and TAM).

plan

Parameter passed as argument strategy to future::plan(). May be set to, for example, multiprocess in order to run the simulations in parallel.

plan_args

Named list. Parameters passed future::plan().

file

String giving the file path used to save the output if save_rdata = TRUE. Note that the file ending is automatically set to .rda. This argument is also passed to irtree_fit_mplus() if applicable.

dir

Path name that is used to save the results of every run if save_rdata = TRUE.

save_rdata

Logical indicating whether to save the results to an RData file.

in_memory

Character string indicating what output should be kept in memory (note the argument save_rdata, which is not affected by in_memory). If "reduced", the output of fit() is discarded and only summary information is retained. The alternative is to keep "everything" in memory, or to keep "nothing" in memory (which makes only sense in combination with save_rdata = TRUE).

Value

Returns a list of length R. For each replication, a list is returned with two elements. The element spec contains various specifications (such as the data). The element fits is a list with one element for each fit_model that contains the output of fit() as well as the elements glanced, tidied, and augmented (see glance(), tidy(), and augment()). Thus, res$sim3$fits$m2$glanced gives model-fit information such as AIC for the second model in the third replication, and res$sim3$spec$data contains the corresponding data set.

If in_memory = "nothing", returns NULL.

See Also

The data are generated via irtree_gen_data(), and the models are fit via fit().

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
# Running these examples may take a while

m1 <- "
Equations:
1 = 1-a
2 = a*(1-b)
3 = a*b

IRT:
a BY x1@1, x2@1, x3@1, x4@1, X5@1, X6@1, X7@1;
b BY x1@1, x2@1, x3@1, x4@1, X5@1, X6@1, X7@1;

Class:
Tree
"

m2 <- "
IRT:
a BY x1@1, x2@1, x3@1, x4@1, X5@1, X6@1, X7@1;

Class:
GRM
"

model1 <- irtree_model(m1)
model2 <- irtree_model(m2)

res <- irtree_sim(
    ### Data generation ###
    gen_model = model1,
    link = "logit",
    N = 500,
    sigma = function(x) diag(2),
    itempar = function(x) list(
        beta = matrix(sort(runif(model1$J*model1$P, -2, 2)),
                      model1$J, model1$P),
        alpha = matrix(1, model1$J, model1$P)),
    na_okay = FALSE,

    ### Estimation ###
    fit_model = list(model1, model2),
    engine = "mirt",
    control = control_mirt(SE = FALSE),
    par_type = "difficulty",

    ### Replications ###
    R = 2,
    save_rdata = FALSE,

    ### Optional parallelization ###
    plan = "multiprocess",
    plan_args = list(workers = future::availableCores() - 1)
)

tab1 <- matrix(NA, 0, 4, dimnames = list(NULL, c("Rep", "Model", "AIC", "BIC")))

for (ii in seq_along(res)) {
    for (jj in seq_along(res[[ii]]$fits)) {
        IC <- res[[ii]]$fits[[jj]]$glanced
        tab1 <- rbind(tab1, c(ii, jj, round(IC$AIC, -1), round(IC$BIC, -1)))
    }
}
tab1
#>      Rep Model  AIC  BIC
#> [1,]   1     1 6900 6970
#> [2,]   1     2 7000 7060
#> [3,]   2     1 6810 6880
#> [4,]   2     2 6880 6940

ItemResponseTrees documentation built on July 2, 2020, 2:25 a.m.