irtree_model: ItemResponseTrees model syntax

In ItemResponseTrees: IR-Tree Modeling in 'mirt', 'Mplus', or 'TAM'

Description

The ItemResponseTrees model syntax describes the statistical model. The function irtree_model() turns a user-defined model string into an object of class irtree_model that represents the full model as needed by the package.

Usage

irtree_model(model = NULL)

Arguments

model

String with a specific structure as described below.

Value

List of class irtree_model. It contains the information extracted from model. Side note: The returned list contains an element mappping_matrix that contains the pseudoitems. This information is instructive, and it might be used as an input to the dendrify() function of the irtrees package.

Overview of the Model Syntax

1. The model string must contain at least the sections IRT, Class, and (if class is tree) Equations.

2. Section headings must appear on a separate line ending with a colon (:).

3. The model may contain empty lines and commented lines, which begin with # (do not use inline comments).

4. Line breaks are only allowed in section IRT.

Details for all the required and optional sections of the model string are given in the following.

Equations

The model must contain a section with heading Equations if Class is Tree. Therein, the model equations are described. They have a structure similar to Cat = p1*(1-p2), where Cat is any observed response category in the data set, and where p1 is a freely chosen name of a parameter. These names must match the names of the latent variables in the section IRT (combined with Constraints if specified).

If you prefer to work with pseudo-items, irtree_create_template() can generate the equations for you.

The equations may contain only products and not sums. That is, it is not possible to estimate genuine mixture models as, for example, in the package mpt2irt.

Each equation must appear on a separate, non-broken line. For example:

Equations:
1 = (1-m)*(1-t)*e
2 = (1-m)*(1-t)*(1-e)
3 = m
4 = (1-m)*t*(1-e)
5 = (1-m)*t*e

IRT

The model must contain a section with heading IRT. Therein, the IRT structure of the model is described in a way resembling the MODEL part of an Mplus input file. It has a structure of LV BY item1*, item2@1, where LV is the name of the latent variable/parameter/process, and item is the name of the observed variable in the data set, which is followed by the loading. The loading may either be fixed (e.g., to 1) using @1 or it may be set free using * (which is equivalent to omitting a loading altogether).

Each measurement model (i.e., the LV and its items) must appear on a separate line ending with a semicolon. Items must be separated by commas. Line breaks are allowed. For example:

IRT:
t BY x1, x2, x3, x4, x5, x6;
e BY x1@1, x2@1, x3@1, x4@1, x5@1, x6@1;
m BY x1@1, x2@1, x3@1, x4@1, x5@1, x6@1;

Class

The model must contain a section with heading Class to specify the type/class of IRT model to use. Currently, may be either Tree, GRM, or PCM. For example:

Class:
Tree

Constraints

The model may contain a section with heading Constraints to specify equality constraints of latent variables. Constraints may be useful for multidimensional questionnaires to link IRT and Equations in a specific way. Or, latent variables in IRT may be constrained to equality.

Constraints in order to link sections IRT and Equations

A process in the model equations (section Equations) may correspond to multiple latent variables (section IRT). For example, when analyzing a Big Five data set, one may wish to specify only one extremity process e for all items but multiple target traits t, namely, one for each of the five scales. In such a case, the section Equations would list only the parameter t, while the section IRT would list the parameters t1, ..., t5.

In the framework of MPT, one would think of such a situation in terms of multiple albeit similar trees with specific parameter contraints across trees. For example, one would use one tree for each Big Five scale and fix the response style parameters to equality across trees but not the target trait parameters.

Each line in this section has a structure of Param = LV1 | LV2, where Param is the name of the process used only in section Equations and LV1 it the name of the process used only in section IRT. Use one line for each definition. For example:

Constraints:
t = t1 | t2 | t3 | t4 | t5

Constraints within section IRT

For example, in a sequential model as proposed by Tutz as well as Verhelst, one would specify two processes for a 3-point item. The first process would correspond to a pseudoitem of 0-1-1 and the second process to a pseudoitem of NA-0-1. However, the latent variables corresponding to these two processes would typically be assumed to be equal and need thus be constrained accordingly.

Each line in this section has a structure of LV1 = LV2, where LV1 and LV2 are the names of the latent variables used in section IRT. Use one line for each definition. For example:

Constraints:
LV1 = LV2
LV1 = LV3

Addendum

The model may contain a section with heading Addendum if engine = "mplus" is used for estimation. Any code in this section is directly pasted in the MODEL section of the Mplus input file. Use a semicolon at the end of each line; lines must not exceed 90 characters. Note that the addendum is ignored in irtree_gen_data(). For example:

Addendum:
e WITH t@0;
m WITH t@0;

Weights

The model may contain a section with heading Weights if model Class is PCM. This allows to specify (uni- and) multidimensional partial credit models. They have been proposed, for example, by Wetzel and Carstensen (2017), as an alternative to IR-tree models. Note that fitting these models is only implemented for engine = "tam".

Each line in this section has a structure of LV = weights, where LV is the name of the latent variable used in section IRT. weights must be valid R code, namely, a vector of weights (see, e.g., Table 1 in Wetzel & Carstensen, 2017, or Table 2 in Falk & Cai, 2015). Use one line for each definition. For example:

Weights:
t = c(0, 1, 2, 3, 4)
e = c(1, 0, 0, 0, 1)
m = c(0, 0, 1, 0, 0)

Examples

m1 <- "
# Random comment

Equations:
1 = (1-m)*(1-t)*e
2 = (1-m)*(1-t)*(1-e)
3 = m
4 = (1-m)*t*(1-e)
5 = (1-m)*t*e

IRT:
t1 BY x1@1, x2*, x3*;
t2 BY x4@1, x5*, x6*;
e  BY x1@1, x2@1, x3@1, x4@1, x5@1, x6@1;
m  BY x1@1, x2@1, x3@1, x4@1, x5@1, x6@1;

Constraints:
t = t1 | t2

Class:
Tree
"

model <- irtree_model(m1)

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