Description Usage Arguments Details Value Author(s) References See Also Examples
Automatically generates lavaan
model syntax to specify a confirmatory
factor analysis (CFA) model with equality constraints imposed on
userspecified measurement (or structural) parameters. Optionally returns
the fitted model (if data are provided) representing some chosen level of
measurement equivalence/invariance across groups and/or repeated measures.
1 2 3 4 5  measEq.syntax(configural.model, ..., ID.fac = "std.lv",
ID.cat = "Wu.Estabrook.2016", ID.thr = c(1L, 2L), group = NULL,
group.equal = "", group.partial = "", longFacNames = list(),
longIndNames = list(), long.equal = "", long.partial = "",
auto = "all", warn = TRUE, debug = FALSE, return.fit = FALSE)

configural.model 
A model with no measurementinvariance constraints
(i.e., representing only configural invariance), unless required for model
identification.
Note that the specified or fitted model must not contain any latent structural parameters (i.e., it must be a CFA model), unless they are higherorder constructs with latent indicators (i.e., a secondorder CFA). 
... 
Additional arguments (e.g., 
ID.fac 
See Kloessner & Klopp (2019) for details about all three methods. 
ID.cat 
See Details and References for more information. 
ID.thr 

group 
optional 
group.equal 
optional 
group.partial 
optional 
longFacNames 
optional named 
longIndNames 
optional named 
long.equal 
optional 
long.partial 
optional 
auto 
Used to automatically included autocorrelated measurement errors
among repeatedly measured indicators in 
warn, debug 

return.fit 

This function is a pedagogical and analytical tool to generate model syntax representing some level of measurement equivalence/invariance across any combination of multiple groups and/or repeated measures. Support is provided for confirmatory factor analysis (CFA) models with simple or complex structure (i.e., crossloadings and correlated residuals are allowed). For any complexities that exceed the limits of automation, this function is intended to still be useful by providing a means to generate syntax that users can easily edit to accommodate their unique situations.
Limited support is provided for bifactor models and higherorder constructs.
Because bifactor models have crossloadings by definition, the option
ID.fac = "effects.code"
is unavailable. ID.fac = "UV"
is
recommended for bifactor models, but ID.fac = "UL"
is available on
the condition that each factor has a unique first indicator in the
configural.model
. In order to maintain generality, higherorder
factors may include a mix of manifest and latent indicators, but they must
therefore require ID.fac = "UL"
to avoid complications with
differentiating lowerorder vs. higherorder (or mixedlevel) factors.
The keyword "loadings"
in group.equal
or long.equal
constrains factor loadings of all manifest indicators (including loadings on
higherorder factors that also have latent indicators), whereas the keyword
"regressions"
constrains factor loadings of latent indicators. Users
can edit the model syntax manually to adjust constraints as necessary, or
clever use of the group.partial
or long.partial
arguments
could make it possible for users to still automated their model syntax.
The keyword "intercepts"
constrains the intercepts of all manifest
indicators, and the keyword "means"
constrains intercepts and means
of all latent common factors, regardless of whether they are latent
indicators of higherorder factors. To test equivalence of lowerorder and
higherorder intercepts/means in separate steps, the user can either
manually edit their generated syntax or conscientiously exploit the
group.partial
or long.partial
arguments as necessary.
ID.fac
: If the configural.model
fixes any (e.g.,
the first) factor loadings, the generated syntax object will retain those
fixed values. This allows the user to retain additional constraints that
might be necessary (e.g., if there are only 1 or 2 indicators). Some methods
must be used in conjunction with other settings:
ID.cat = "Millsap"
requires ID.fac = "UL"
and
parameterization = "theta"
.
ID.cat = "LISREL"
requires parameterization = "theta"
.
ID.fac = "effects.code"
is unavailable when there are any
crossloadings.
ID.cat
: Wu & Estabrook (2016) recommended constraining
thresholds to equality first, and doing so should allow releasing any
identification constraints no longer needed. For each ordered
indicator, constraining one threshold to equality will allow the item's
intercepts to be estimated in all but the first group or repeated measure.
Constraining a second threshold (if applicable) will allow the item's
(residual) variance to be estimated in all but the first group or repeated
measure. For binary data, there is no independent test of threshold,
intercept, or residualvariance equality. Equivalence of thresholds must
also be assumed for threecategory indicators. These guidelines provide the
least restrictive assumptions and tests, and are therefore the default.
The default setting in Mplus is similar to Wu & Estabrook (2016),
except that intercepts are always constrained to zero (so they are assumed
to be invariant without testing them). Millsap & Tein (2004) recommended
parameterization = "theta"
and identified an item's residual variance
in all but the first group (or occasion; Liu et al., 2017) by constraining
its intercept to zero and one of its thresholds to equality. A second
threshold for the reference indicator (so ID.fac = "UL"
) is used to
identify the commonfactor means in all but the first group/occasion. The
LISREL software fixes the first threshold to zero and (if applicable) the
second threshold to 1, and assumes any remaining thresholds to be equal
across groups / repeated measures; thus, the intercepts are always
identified, and residual variances (parameterization = "theta"
) are
identified except for binary data, when they are all fixed to one.
Repeated Measures: If each repeatedly measured factor is measured
by the same indicators (specified in the same order in the
configural.model
) on each occasion, without any crossloadings, the
user can let longIndNames
be automatically generated. Generic names
for the repeatedly measured indicators are created using the name of the
repeatedly measured factors (i.e., names(longFacNames)
) and the
number of indicators. So the repeatedly measured first indicator
("ind"
) of a longitudinal construct called "factor" would be
generated as "._factor_ind.1"
.
The same types of parameter can be specified for long.equal
as for
group.equal
(see lavOptions
for a list), except
for "residual.covariances"
or "lv.covariances"
. Instead, users
can constrain autocovariances using keywords "resid.autocov"
or "lv.autocov"
. Note that group.equal = "lv.covariances"
or
group.equal = "residual.covariances"
will constrain any
autocovariances across groups, along with any other covariances the user
specified in the configural.model
. Note also that autocovariances
cannot be specified as exceptions in long.partial
, so anything more
complex than the auto
argument automatically provides should instead
be manually specified in the configural.model
.
When users set orthogonal=TRUE
in the configural.model
(e.g.,
in bifactor models of repeatedly measured constructs), autocovariances of
each repeatedly measured factor will still be freely estimated in the
generated syntax.
Missing Data: If users wish to utilize the auxiliary
function to automatically include auxiliary variables in conjunction with
missing = "FIML"
, they should first generate the hypothesizedmodel
syntax, then submit that syntax as the model to auxiliary()
.
If users utilized runMI
to fit their configural.model
to multiply imputed data, that model can also be passed to the
configural.model
argument, and if return.fit = TRUE
, the
generated model will be fitted to the multiple imputations.
By default, an object of class measEq.syntax
.
If return.fit = TRUE
, a fitted lavaan
model, with the measEq.syntax
object stored in the
@external
slot, accessible by fit@external$measEq.syntax
.
Terrence D. Jorgensen (University of Amsterdam; TJorgensen314@gmail.com)
Kloessner, S., & Klopp, E. (2019). Explaining constraint interaction: How to interpret estimated model parameters under alternative scaling methods. Structural Equation Modeling, 26(1), 143–155. doi: 10.1080/10705511.2018.1517356
Liu, Y., Millsap, R. E., West, S. G., Tein, J.Y., Tanaka, R., & Grimm, K. J. (2017). Testing measurement invariance in longitudinal data with orderedcategorical measures. Psychological Methods, 22(3), 486–506. doi: 10.1037/met0000075
Millsap, R. E., & Tein, J.Y. (2004). Assessing factorial invariance in orderedcategorical measures. Multivariate Behavioral Research, 39(3), 479–515. doi: 10.1207/S15327906MBR3903_4
Wu, H., & Estabrook, R. (2016). Identification of confirmatory factor analysis models of different levels of invariance for ordered categorical outcomes. Psychometrika, 81(4), 1014–1045. doi: 10.1007/s1133601695060
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 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235  mod.cat < ' FU1 =~ u1 + u2 + u3 + u4
FU2 =~ u5 + u6 + u7 + u8 '
## the 2 factors are actually the same factor (FU) measured twice
longFacNames < list(FU = c("FU1","FU2"))
## CONFIGURAL model: no constraints across groups or repeated measures
syntax.config < measEq.syntax(configural.model = mod.cat,
# NOTE: data provides info about numbers of
# groups and thresholds
data = datCat,
ordered = paste0("u", 1:8),
parameterization = "theta",
ID.fac = "std.lv", ID.cat = "Wu.Estabrook.2016",
group = "g", longFacNames = longFacNames)
## print lavaan syntax to the Console
cat(as.character(syntax.config))
## print a summary of model features
summary(syntax.config)
## THRESHOLD invariance:
## only necessary to specify thresholds if you have no data
mod.th < '
u1  t1 + t2 + t3 + t4
u2  t1 + t2 + t3 + t4
u3  t1 + t2 + t3 + t4
u4  t1 + t2 + t3 + t4
u5  t1 + t2 + t3 + t4
u6  t1 + t2 + t3 + t4
u7  t1 + t2 + t3 + t4
u8  t1 + t2 + t3 + t4
'
syntax.thresh < measEq.syntax(configural.model = c(mod.cat, mod.th),
# NOTE: data not provided, so syntax must
# include thresholds, and number of
# groups == 2 is indicated by:
sample.nobs = c(1, 1),
parameterization = "theta",
ID.fac = "std.lv", ID.cat = "Wu.Estabrook.2016",
group = "g", group.equal = "thresholds",
longFacNames = longFacNames,
long.equal = "thresholds")
## notice that constraining 4 thresholds allows intercepts and residual
## variances to be freely estimated in all but the first group & occasion
cat(as.character(syntax.thresh))
## print a summary of model features
summary(syntax.thresh)
## Fit a model to the data either in a subsequent step (recommended):
mod.config < as.character(syntax.config)
fit.config < cfa(mod.config, data = datCat, group = "g",
ordered = paste0("u", 1:8), parameterization = "theta")
## or in a single step (not generally recommended):
fit.thresh < measEq.syntax(configural.model = mod.cat, data = datCat,
ordered = paste0("u", 1:8),
parameterization = "theta",
ID.fac = "std.lv", ID.cat = "Wu.Estabrook.2016",
group = "g", group.equal = "thresholds",
longFacNames = longFacNames,
long.equal = "thresholds", return.fit = TRUE)
## compare their fit to test threshold invariance
anova(fit.config, fit.thresh)
## 
## RECOMMENDED PRACTICE: fit one invariance model at a time
## 
##  A downside of setting return.fit=TRUE is that if the model has trouble
## converging, you don't have the opportunity to investigate the syntax,
## or even to know whether an error resulted from the syntaxgenerator or
## from lavaan itself.
##  A downside of automatically fitting an entire set of invariance models
## (like the old measurementInvariance() function did) is that you might
## end up testing models that shouldn't even be fitted because less
## restrictive models already fail (e.g., don't test full scalar
## invariance if metric invariance fails! Establish partial metric
## invariance first, then test equivalent of intercepts ONLY among the
## indicators that have invariate loadings.)
## The recommended sequence is to (1) generate and save each syntax object,
## (2) print it to the screen to verify you are fitting the model you expect
## to (and potentially learn which identification constraints should be
## released when equality constraints are imposed), and (3) fit that model
## to the data, as you would if you had written the syntax yourself.
## Continuing from the examples above, after establishing invariance of
## thresholds, we proceed to test equivalence of loadings and intercepts
## (metric and scalar invariance, respectively)
## simultaneously across groups and repeated measures.
## Not run:
## metric invariance
syntax.metric < measEq.syntax(configural.model = mod.cat, data = datCat,
ordered = paste0("u", 1:8),
parameterization = "theta",
ID.fac = "std.lv", ID.cat = "Wu.Estabrook.2016",
group = "g", longFacNames = longFacNames,
group.equal = c("thresholds","loadings"),
long.equal = c("thresholds","loadings"))
summary(syntax.metric) # summarize model features
mod.metric < as.character(syntax.metric) # save as text
cat(mod.metric) # print/view lavaan syntax
## fit model to data
fit.metric < cfa(mod.metric, data = datCat, group = "g",
ordered = paste0("u", 1:8), parameterization = "theta")
## test equivalence of loadings, given equivalence of thresholds
anova(fit.thresh, fit.metric)
## scalar invariance
syntax.scalar < measEq.syntax(configural.model = mod.cat, data = datCat,
ordered = paste0("u", 1:8),
parameterization = "theta",
ID.fac = "std.lv", ID.cat = "Wu.Estabrook.2016",
group = "g", longFacNames = longFacNames,
group.equal = c("thresholds","loadings",
"intercepts"),
long.equal = c("thresholds","loadings",
"intercepts"))
summary(syntax.scalar) # summarize model features
mod.scalar < as.character(syntax.scalar) # save as text
cat(mod.scalar) # print/view lavaan syntax
## fit model to data
fit.scalar < cfa(mod.scalar, data = datCat, group = "g",
ordered = paste0("u", 1:8), parameterization = "theta")
## test equivalence of intercepts, given equal thresholds & loadings
anova(fit.metric, fit.scalar)
## For a single table with all results, you can pass the models to
## summarize to the compareFit() function
compareFit(fit.config, fit.thresh, fit.metric, fit.scalar)
## 
## NOT RECOMMENDED: fit several invariance models at once
## 
test.seq < c("thresholds","loadings","intercepts","means","residuals")
meq.list < list()
for (i in 0:length(test.seq)) {
if (i == 0L) {
meq.label < "configural"
group.equal < ""
long.equal < ""
} else {
meq.label < test.seq[i]
group.equal < test.seq[1:i]
long.equal < test.seq[1:i]
}
meq.list[[meq.label]] < measEq.syntax(configural.model = mod.cat,
data = datCat,
ordered = paste0("u", 1:8),
parameterization = "theta",
ID.fac = "std.lv",
ID.cat = "Wu.Estabrook.2016",
group = "g",
group.equal = group.equal,
longFacNames = longFacNames,
long.equal = long.equal,
return.fit = TRUE)
}
compareFit(meq.list)
## 
## Binary indicators
## 
## borrow example data from Mplus user guide
myData < read.table("http://www.statmodel.com/usersguide/chap5/ex5.16.dat")
names(myData) < c("u1","u2","u3","u4","u5","u6","x1","x2","x3","g")
bin.mod < '
FU1 =~ u1 + u2 + u3
FU2 =~ u4 + u5 + u6
'
## Must SIMULTANEOUSLY constrain thresholds, loadings, and intercepts
test.seq < list(strong = c("thresholds","loadings","intercepts"),
means = "means",
strict = "residuals")
meq.list < list()
for (i in 0:length(test.seq)) {
if (i == 0L) {
meq.label < "configural"
group.equal < ""
long.equal < ""
} else {
meq.label < names(test.seq)[i]
group.equal < unlist(test.seq[1:i])
# long.equal < unlist(test.seq[1:i])
}
meq.list[[meq.label]] < measEq.syntax(configural.model = bin.mod,
data = myData,
ordered = paste0("u", 1:6),
parameterization = "theta",
ID.fac = "std.lv",
ID.cat = "Wu.Estabrook.2016",
group = "g",
group.equal = group.equal,
#longFacNames = longFacNames,
#long.equal = long.equal,
return.fit = TRUE)
}
compareFit(meq.list)
## 
## Multilevel Invariance
## 
## To test invariance across levels in a MLSEM, specify syntax as though
## you are fitting to 2 groups instead of 2 levels.
mlsem < ' f1 =~ y1 + y2 + y3
f2 =~ y4 + y5 + y6 '
## metric invariance
syntax.metric < measEq.syntax(configural.model = mlsem, meanstructure = TRUE,
ID.fac = "std.lv", sample.nobs = c(1, 1),
group = "cluster", group.equal = "loadings")
## by definition, Level1 means must be zero, so fix them
syntax.metric < update(syntax.metric,
change.syntax = paste0("y", 1:6, " ~ c(0, NA)*1"))
## save as a character string
mod.metric < as.character(syntax.metric, groups.as.blocks = TRUE)
## convert from multigroup to multilevel
mod.metric < gsub(pattern = "group:", replacement = "level:",
x = mod.metric, fixed = TRUE)
## fit model to data
fit.metric < lavaan(mod.metric, data = Demo.twolevel, cluster = "cluster")
summary(fit.metric)
## End(Not run)

Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.