measEq.syntax  R Documentation 
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.
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
compareFit
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.