Description Usage Arguments Value Overview of the Model Syntax Examples

View source: R/s3_tree_model.R

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.

1 | ```
irtree_model(model = NULL)
``` |

`model` |
String with a specific structure as described below. |

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.

The

`model`

string must contain at least the sections**IRT**,**Class**, and (if class is tree)**Equations**.Section headings must appear on a separate line ending with a colon (:).

The model may contain empty lines and commented lines, which begin with

`#`

(do not use inline comments).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.

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:

1 2 3 4 5 6 |

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:

1 2 3 4 | ```
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;
``` |

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:

1 2 | ```
Class:
Tree
``` |

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.

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:

1 2 | ```
Constraints:
t = t1 | t2 | t3 | t4 | t5
``` |

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:

1 2 3 | ```
Constraints:
LV1 = LV2
LV1 = LV3
``` |

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:

1 2 3 |

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:

1 2 3 4 |

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | ```
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)
``` |

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.