The mirt.model function scans/reads user input to specify the
confirmatory model. Item locations must be used in the specifications if no
itemnames argument is supplied. This is called implicitly by estimation functions
when a string is passed to the model argument.
mirt.model(
input = NULL,
itemnames = NULL,
file = "",
COV = NULL,
quiet = TRUE,
...
)input for writing out the model syntax. Can either be a string declaration of
class character or the so-called Q-matrix or class matrix that specifies the model
either with integer or logical values. If the Q-matrix method
is chosen covariances terms can be specified with the COV input
a character vector or factor indicating the item names. If a data.frame or
matrix object is supplied the names will be extracted using colnames(itemnames).
Supplying this input allows the syntax to be specified with the raw item names rather than
item locations
a input specifying an external file that declares the input.
a symmetric, logical matrix used to declare which covariance terms are estimated
logical argument passed to scan() to suppress console read message
additional arguments for scan()
Factors are first named and then specify which numerical items they affect
(i.e., where the slope is not equal to 0), separated either by commas or by
- to indicate a range of items. Products between factors may be specified
by enclosing the left hand term within brackets. To finish the declaration of
a model simply enter a blank line with only a carriage return (i.e., the
'enter' or 'return' key), or instead read in an input version of the model syntax.
The associated slopes throughout the package label these coefficients as
a1, a2, ..., ak, where the associated number is assigned according to the
respective order of the defined factors.
For example, if the syntax were
"G = 1-10
F = 1-5
A = 6-10"
then the G factor would be assigned the slopes a1 for each item, F assigned
the slopes a2, and A assigned the slopes a3. The same principle applies to the
bfactor function whereby the slopes are automatically included for the specific factors
after the general factor structure has been assigned.
There is an optional keyword for specifying the correlation between relationships between factors
called COV, and non-linear factor products can be included by enclosing the product
combination on the left hand side of the declaration (e.g., (F1*F1) would create a
quadratic factor for F1).
The keywords CONSTRAIN, CONSTRAINB, PRIOR, FIXED, FREE, START, UBOUND, LBOUND can
be applied to specific sub-groups in multiple-group models by included square brackets before the
= sign, where groups are separated by commas. For example, to apply within-group equality
constraints to a group called "male", then specifying:
CONSTRAIN [male] = (1-5, a1)
is appropriate, while specifying the same constraints to the sub-groups "male" and "female" would appear as
CONSTRAIN [male, female] = (1-5, a1)
For all other groups in the multi-group model, these within-group equality constraints would not appear. Therefore, these bracketed group specifications are useful when modifying priors, starting values, between/within group equality constraints, and so on when the specifications for each sub-group may differ.
Finally, the keyword GROUP can be used to specify the group-level
hyper-parameter terms, such as the means and variance of the default Gaussian
distribution. For example, to set the starting value of the variance
parameter (COV_11) to 1.5:
START = (GROUP, COV_11, 1.5)
Specify the relationship between the latent factors. Estimating a correlation between factors is declared by joining the two factors with an asterisk (e.g., F1*F2), or with an asterisk between three or more factors to estimate all the possible correlations (e.g., F1*F2*F3)
A comma separated list specifying which latent factor means to freely estimate.
E.g., MEAN = F1, F2 will free the latent means for factors F1 and F2
A bracketed, comma separated list specifying equality constrains between items.
The input format is
CONSTRAIN = (items, ..., parameterName(s)),
(items, ..., parameterName).
For example, in a single group 10-item dichotomous tests, using the default 2PL model,
the first and last 5 item slopes (a1) can be constrained to be equal by using
CONSTRAIN = (1-5, a1), (6-10, a1), or some combination
such as CONSTRAIN = (1-3,4,5,a1), (6,7,8-10,a1).
When constraining parameters to be equal across items with different parameter names, a
balanced bracketed vector must be supplied. E.g., setting the first slope for item 1 equal to
the second slope in item 3 would be CONSTRAIN = (1, 3, a1, a2)
A bracketed, comma separate list specifying equality constrains between groups.
The input format is CONSTRAINB = (items, ..., parameterName),
(items, ..., parameterName).
For example, in a two group 10-item dichotomous tests, using the default 2PL model, the first
5 item slopes (a1) can be constrained to be equal across both groups by using
CONSTRAINB = (1-5, a1), or some combination such as CONSTRAINB = (1-3,4,5,a1)
A bracketed, comma separate list specifying prior parameter distributions.
The input format is
PRIOR = (items, ..., parameterName, priorType, val1, val2),
(items, ..., parameterName, priorType, val1, val2).
For example, in a single group 10-item dichotomous tests, using the default 2PL model,
defining a normal prior of N(0,2) for the first 5 item intercepts (d) can be defined by
PRIOR = (1-5, d, norm, 0, 2)
Currently supported priors are of the form: (items, norm, mean, sd)
for the normal/Gaussian, (items, lnorm, log_mean, log_sd) for log-normal,
(items, beta, alpha, beta) for beta, and (items, expbeta, alpha, beta)
for the beta distribution after applying the
function plogis to the input value (note, this is specifically for applying a beta
prior to the lower-bound parameters in 3/4PL models)
A bracketed, comma separate list specifying lower bounds for estimated
parameters (used in optimizers such as L-BFGS-B and nlminb).
The input format is LBOUND = (items, ..., parameterName, value),
(items, ..., parameterName, value).
For example, in a single group 10-item dichotomous tests, using the 3PL model and
setting lower bounds for the 'g' parameters for the first 5 items to 0.2 is accomplished with
LBOUND = (1-5, g, 0.2)
same as LBOUND, but specifying upper bounds in estimated parameters
A bracketed, comma separate list specifying the starting values for individual parameters.
The input is of the form (items, ..., parameterName, value). For instance, setting the 10th and
12th to 15th item slope parameters (a1) to 1.0 is specified with START = (10, 12-15, a1, 1.0)
For more hands on control of the starting values pass the argument pars = 'values' through
whatever estimation function is being used
A bracketed, comma separate list specifying which parameters should be fixed at their
starting values (i.e., not freely estimated).
The input is of the form (items, ..., parameterName). For instance, fixing the 10th and
12th to 15th item slope parameters (a1) is accomplished with FIXED = (10, 12-15, a1)
For more hands on control of the estimated values pass the argument pars = 'values' through
whatever estimation function is being used
Equivalent to the FIXED input, except that parameters are freely estimated instead
of fixed at their starting value
Number of exploratory factors to extract. Usually this is not required
because passing a numeric value to the model argument in the estimation function
will generate an exploratory factor analysis model, however if different start values,
priors, lower and upper bounds, etc, are desired then this input can be used
Chalmers, R., P. (2012). mirt: A Multidimensional Item Response Theory Package for the R Environment. Journal of Statistical Software, 48(6), 1-29. doi:10.18637/jss.v048.i06
# \donttest{
# interactively through the console (not run)
#model <- mirt.model()
# F1 = 1,2,3,4-10
# F2 = 10-20
# (F1*F2) = 1,2,3,4-10
# COV = F1*F2
# Or alternatively with a string input
s <- 'F1 = 1,2,3,4-10
F2 = 10-20
(F1*F2) = 1,2,3,4-10
COV = F1*F2'
model <- mirt.model(s)
# strings can also be passed to the estimation functions directly,
# which silently calls mirt.model(). E.g., using the string above:
# mod <- mirt(data, s)
# Q-matrix specification
Q <- matrix(c(1,1,1,0,0,0,0,0,0,1,1,1), ncol=2, dimnames = list(NULL, c('Factor1', 'Factor2')))
COV <- matrix(c(FALSE, TRUE, TRUE, FALSE), 2)
model <- mirt.model(Q, COV=COV)
## constrain various items slopes and all intercepts in single group model to be equal,
# and use a log-normal prior for all the slopes
s <- 'F = 1-10
CONSTRAIN = (1-3, 5, 6, a1), (1-10, d)
PRIOR = (1-10, a1, lnorm, .2, .2)'
model <- mirt.model(s)
## constrain various items slopes and intercepts across groups for use in multipleGroup(),
# and constrain first two slopes within 'group1' to be equal
s <- 'F = 1-10
CONSTRAIN = (1-2, a1)
CONSTRAINB = (1-3, 5, 6, a1), (1-10, d)'
model <- mirt.model(s)
## specify model using raw item names
data(data.read, package = 'sirt')
dat <- data.read
# syntax with variable names
mirtsyn2 <- "
F1 = A1,B2,B3,C4
F2 = A1-A4,C2,C4
MEAN = F1
COV = F1*F1, F1*F2
CONSTRAIN=(A2-A4,a2),(A3,C2,d)
PRIOR = (C3,A2-A4,a2,lnorm, .2, .2),(B3,d,norm,0,.0001)"
# create a mirt model
mirtmodel <- mirt.model(mirtsyn2, itemnames=dat)
# or equivalently:
# mirtmodel <- mirt.model(mirtsyn2, itemnames=colnames(dat))
# mod <- mirt(dat , mirtmodel)
# }