multilevel.invar: Cross-Level Measurement Invariance Evaluation

In misty: Miscellaneous Functions 'T. Yanagida'

Cross-Level Measurement Invariance Evaluation

Description

This function evaluates configural, metric, and scalar cross-level measurement invariance using multilevel confirmatory factor analysis with continuous indicators by calling the cfa function in the R package lavaan. By default, the function evaluates configural and metric cross-level measurement invariance by providing a table with model fit information (i.e., chi-square test, fit indices and information criteria), and model comparison (i.e., chi-square difference test, change in fit indices, and change in information criteria). Additionally, variance-covariance coverage of the data, descriptive statistics, parameter estimates, modification indices, residual correlation matrix, and relative Opdyke distribution percentile matrix can be requested by specifying the argument print.

Usage

multilevel.invar(data, ..., cluster, model = NULL, rescov = NULL,
                 invar = c("config", "metric", "scalar"), fix.resid = NULL,
                 ident = c("marker", "var", "effect"), estimator = c("ML", "MLR"),
                 optim.method = c("nlminb", "em"), missing = c("listwise", "fiml"),
                 print = c("all", "summary", "coverage", "descript", "fit", "est",
                           "modind", "resid", "opdyke"),
                 print.fit = c("all", "standard", "scaled", "robust"),
                 mod.minval = 6.63, resid.minval = 0.1,
                 opdyke.prec = 1, opdyke.minmax = c(0.40, 0.60),
                 color = "b.red", style = c("regular", "bold", "italic"),
                 digits = 3, p.digits = 3, as.na = NULL, write = NULL,
                 append = TRUE, check = TRUE, output = TRUE)

Arguments

data	a data frame. If model is NULL, multilevel confirmatory factor analysis based on a measurement model with one factor at the Within and Between level comprising all variables in the data frame is conducted to evaluate cross-level measurement invariance. Note that the cluster variable specified in cluster is excluded from data when specifying the argument cluster using the variable name of the cluster variable. If model is specified, the data frame needs to contain all variables used in the model argument.
...	an expression indicating the variable names in data, e.g., multilevel.invar(dat, x1, x2, x3, cluster = "cluster"). Note that the operators +, -, ~, :, ::, and ! can also be used to select variables, see 'Details' in the df.subset function.
cluster	either a character string indicating the variable name of the cluster variable in data, or a vector representing the nested grouping structure (i.e., group or cluster variable).
model	a character vector specifying the same factor structure with one factor at the Within and Between Level, or a list of character vectors for specifying the same measurement model with more than one factor at the Within and Between Level, e.g.,model = c("x1", "x2", "x3", "x4") for specifying a measurement model with one factor labeled wf at the Within level and a measurement model with one factor labeled bf at the Between level each comprising four indicators, or model = list(factor1 = c("x1", "x2", "x3", "x4"), factor2 = c("x5", "x6", "x7", "x8")) for specifying a measurement model with two latent factors labeled wfactor1 and wfactor2 at the Within level and a measurement model with two latent factors labeled bfactor1 and bfactor2 at the Between level each comprising four indicators. Note that the name of each list element is used to label factors, where prefixes w and b are added the labels to distinguish factor labels at the Within and Between level, i.e., all list elements need to be named, otherwise factors are labeled with "wf1", "wf2", "wf3" for labels at the Within level and "bf1", "bf2", "bf3" for labels at the Between level and so on.
rescov	a character vector or a list of character vectors for specifying residual covariances at the Within level, e.g. rescov = c("x1", "x2") for specifying a residual covariance between indicators x1 and x2 at the Within level or rescov = list(c("x1", "x2"), c("x3", "x4")) for specifying residual covariances between indicators x1 and x2, and indicators x3 and x4 at the Within level. Note that residual covariances at the Between level can only be specified by using the arguments model.w, model.b, and model.b.
invar	a character string indicating the level of measurement invariance to be evaluated, i.e., config to evaluate configural measurement invariance (i.e., same factor structure across levels), metric (default) to evaluate configural and metric measurement invariance (i.e., equal factor loadings across level), and scalar to evaluate configural, metric and scalar measurement invariance (i.e., all residual variances at the Between level equal zero).
fix.resid	a character vector for specifying residual variances to be fixed at 0 at the Between level for the configural and metric invariance model, e.g., fix.resid = c("x1", "x3") to fix residual variances of indicators x1 and x2 at the Between level at 0. Note that it is also possible to specify fix.resid = "all" which fixes all residual variances at the Between level at 0 in line with the strong factorial measurement invariance assumption across cluster.
ident	a character string indicating the method used for identifying and scaling latent variables, i.e., "marker" for the marker variable method fixing the first factor loading of each latent variable to 1, "var" for the fixed variance method fixing the variance of each latent variable to 1, or "effect" for the effects-coding method using equality constraints so that the average of the factor loading for each latent variable equals 1.
estimator	a character string indicating the estimator to be used: "ML" for maximum likelihood with conventional standard errors and "MLR" (default) for maximum likelihood with Huber-White robust standard errors and a scaled test statistic that is asymptotically equal to the Yuan-Bentler test statistic. Note that by default, full information maximum likelihood (FIML) method is used to deal with missing data when using "ML" (missing = "fiml"), whereas incomplete cases are removed listwise (i.e., missing = "listwise") when using "MLR".
optim.method	a character string indicating the optimizer, i.e., "nlminb" (default) for the unconstrained and bounds-constrained quasi-Newton method optimizer and "em" for the Expectation Maximization (EM) algorithm.
missing	a character string indicating how to deal with missing data, i.e., "listwise" (default) for listwise deletion or "fiml" for full information maximum likelihood (FIML) method. Note that FIML method is only available when estimator = "ML", that it takes longer to estimate the model using FIML, and that FIML is prone to convergence issues which might be resolved by switching to listwise deletion.
print	a character string or character vector indicating which results to show on the console, i.e. "all" for all results, "summary" for a summary of the specification of the estimation method and missing data handling in lavaan, "coverage" for the variance-covariance coverage of the data, "descript" for descriptive statistics, "fit" for model fit and model comparison, "est" for parameter estimates, and "modind" for modification indices. By default, a summary of the specification and model fit and model comparison are printed.
print.fit	a character string or character vector indicating which version of the CFI, TLI, and RMSEA to show on the console, i.e., "all" for all versions of the CFI, TLI, and RMSEA, "standard" (default when estimator = "ML") for fit indices without any non-normality correction, "scaled" for population-corrected robust fit indices with ad hoc non-normality correction, and robust (default when estimator = "MLR") for sample-corrected robust fit indices based on formula provided by Li and Bentler (2006) and Brosseau-Liard and Savalei (2014).
mod.minval	numeric value to filter modification indices and only show modifications with a modification index value equal or higher than this minimum value. By default, modification indices equal or higher 6.63 are printed. Note that a modification index value of 6.63 is equivalent to a significance level of \alpha = .01.
resid.minval	numeric value indicating the minimum absolute residual correlation coefficients and standardized means to highlight in boldface. By default, absolute residual correlation coefficients and standardized means equal or higher 0.1 are highlighted. Note that highlighting can be disabled by setting the minimum value to 1.
opdyke.prec	a numeric value indicating the precision of the probability density function calculations of the Opdyke distribution. The default is 1 which calculates the PDF for polar angles between (0, pi) in 0.01 increments. Specifying 10 calculates the PDF polar angles between (0, pi) in 0.001 increments, which takes considerably longer, especially if there are many correlation elements.
opdyke.minmax	a numeric vector with two elements indicating the minimum and maximum percentile of the Opdyke distribution that is considered to be acceptably close to the observed correlation represented by the Opdyke distribution median. Predicted correlation outside the range will be color highlighted in line with to the argument color.
color	a character string indicating the text color for highlighting absolute residual correlation coefficients and standardized means equal or higher resid.minval and predicted correlations outside the minimum and maximum percentile of the Opdyke distribution, i.e., i.e., "default" for the default text color without color coding and various text colors for highlighting "red", "b.red" (default), "green", "b.green", "blue", or "b.blue", see the help page of the chr.color function. Note that this option is not supported when using R Markdown and when writing the output into a text file (.txt).
style	a character vector indicating the font style for highlighting absolute residual correlation coefficients and standardized means equal or higher resid.minval, i.e., "regular" (default) for regular text, "bold" for bold text, and "italic" for italic text. Note that the font style "bold" and "italic" can be combined, i.e., style = c("bold", "italic") provides a bold and italic text. Note that the argument color needs to be specified to change the style of the text, e.g. color = "black" and style = "bold" to for bold text.
digits	an integer value indicating the number of decimal places to be used for displaying results. Note that information criteria and chi-square test statistic is printed with digits minus 1 decimal places.
p.digits	an integer value indicating the number of decimal places to be used for displaying the p-value.
as.na	a numeric vector indicating user-defined missing values, i.e. these values are converted to NA before conducting the analysis. Note that as.na() function is only applied to data but not to cluster.
write	a character string naming a file for writing the output into either a text file with file extension ".txt" (e.g., "Output.txt") or Excel file with file extension ".xlsx" (e.g., "Output.xlsx"). If the file name does not contain any file extension, an Excel file will be written.
append	logical: if TRUE (default), output will be appended to an existing text file with extension .txt specified in write, if FALSE existing text file will be overwritten.
check	logical: if TRUE (default), argument specification, convergence and model identification is checked.
output	logical: if TRUE (default), output is shown.

Value

Returns an object of class misty.object, which is a list with following entries:

call	function call
type	type of analysis
data	data frame specified in data
args	specification of function arguments
model	list with specified model for the configural, metric, and scalar invariance model
model.fit	list with fitted lavaan object of the configural, metric, and scalar invariance model
check	list with the results of the convergence and model identification check for the configural, metric, and scalar invariance model
result	list with result tables, i.e., summary for the summary of the specification of the estimation method and missing data handling in lavaan, coverage for the variance-covariance coverage of the data, descript for descriptive statistics, fit for a list with model fit based on standard, scaled, and robust fit indices, est for a list with parameter estimates for the configural, metric, and scalar invariance model, and modind for the list with modification indices for the configural, metric, and scalar invariance model

Note

The function uses the functions lavTestLRT provided in the R package lavaan by Yves Rosseel (2012). The relative Opdyke distribution percentile matrix is based on the functions opdyke and opdyke.percentiles provided in the R package opddyke by Dan McNeish (2026).

Author(s)

Takuya Yanagida [e-mail]

References

McNeish D (2026). opdyke: Opdyke Percentiles for Approximate Local Fit in Structural Equation Models. R package version 1.0.0. Retrieved from https://github.com/dmcneish18/opdyke

Rosseel, Y. (2012). lavaan: An R Package for Structural Equation Modeling. Journal of Statistical Software, 48, 1-36. https://doi.org/10.18637/jss.v048.i02

See Also

multilevel.cfa, multilevel.fit, multilevel.omega, multilevel.cor, multilevel.descript

Examples

## Not run: 

# Load data set "Demo.twolevel" in the lavaan package
data("Demo.twolevel", package = "lavaan")

#—————————————————————————————————————————————————————————————————————————————
# Cluster Variable Specification

# Example 1a: Specification using the argument '...'
multilevel.invar(Demo.twolevel, y1:y4, cluster = "cluster")

# Example 1b: Alternative specification with cluster variable 'cluster' in 'data'
multilevel.invar(Demo.twolevel[, c("y1", "y2", "y3", "y4", "cluster")], cluster = "cluster")

# Example 1c: Alternative specification with cluster variable 'cluster' not in 'data'
multilevel.invar(Demo.twolevel[, c("y1", "y2", "y3", "y4")], cluster = Demo.twolevel$cluster)

#—————————————————————————————————————————————————————————————————————————————
# Model Specification Using 'data' for an One-Factor Model

#——————————————————————————————————————
## Level of Measurement Invariance

# Example 2a: Configural invariance
multilevel.invar(Demo.twolevel, y1, y2, y3, y4, cluster = "cluster", invar = "config")

# Example 2b: Metric invariance
multilevel.invar(Demo.twolevel, y1, y2, y3, y4, cluster = "cluster", invar = "metric")

# Example 2c: Scalar invariance
multilevel.invar(Demo.twolevel, y1, y2, y3, y4, cluster = "cluster", invar = "scalar")

#——————————————————————————————————————
## Residual (Co-)Variance at the Within and Between Level

# Example 3a: Residual covariance between "y3" and "y4" at the Within level
multilevel.invar(Demo.twolevel, y1, y2, y3, y4, cluster = "cluster",
                 rescov = c("y3", "y4"))

# Example 3b: Residual variances of 'y1' at the Between level fixed at 0
multilevel.invar(Demo.twolevel, y1, y2, y3, y4, cluster = "cluster", fix.resid = "y1")

#——————————————————————————————————————
## Arguments 'print', 'mod.minval', 'resid.minval', and 'opdyke.minmax'

# Example 4a: Request all results
multilevel.invar(Demo.twolevel, y1:y6, cluster = "cluster", print = "all")

# Example 4b: Request modification indices with value equal or higher than 2
multilevel.invar(Demo.twolevel, y1:y6, cluster = "cluster", print = "modind",
                 mod.minval = 2)

# Example 4c: Highlight absolute residual correlation equal or higher than 0.05
multilevel.invar(Demo.twolevel, y1:y6, cluster = "cluster", print = "resid",
                 resid.minval = 0.05, color = "b.blue")

# Example 4d: Highlight Opdyke distribution percentiles outside 0.45 and 0.55
multilevel.invar(Demo.twolevel, y1:y6, cluster = "cluster", print = "opdyke",
                 opdyke.minmax = c(0.45, 0.55), color = "black", style = "bold")

#————————————————————————————————————————————————————————————————————————————
# lavaan Summary of the Estimated Model

# Example 5: lavaan model and summary of the estimated model
mod <- multilevel.invar(Demo.twolevel, y1, y2, y3, y4, cluster = "cluster", output = FALSE)

# lavaan syntax of the metric invariance model
mod$model$metric

# Fitted lavaan object of the metric invariance model
lavaan::summary(mod$model.fit$metric, standardized = TRUE, fit.measures = TRUE)

#—————————————————————————————————————————————————————————————————————————————
# Model Specification Using 'model' for an One- or Multiple-Factor Model

# Example 6a: One-factor model
multilevel.invar(Demo.twolevel, cluster = "cluster", model = c("y1", "y2", "y3", "y4"))

# Example 6b:  Two-factor model
multilevel.invar(Demo.twolevel, cluster = "cluster",
                 model = list(c("y1", "y2", "y3"), c("y4", "y5", "y6")))

#—————————————————————————————————————————————————————————————————————————————
# Write Results

# Example 7a: Write Results into a Excel file
multilevel.invar(Demo.twolevel, y1, y2, y3, y4, cluster = "cluster", print = "all",
                 write = "Multilevel_Invariance.txt")

# Example 7b:  Write Results into a Excel file
multilevel.invar(Demo.twolevel, y1, y2, y3, y4, cluster = "cluster", print = "all",
                 write = "Multilevel_Invariance.xlsx")

## End(Not run)

misty documentation built on Aug. 2, 2026, 9:06 a.m.