item.dfi: Dynamic Fit Index Cutoffs

In misty: Miscellaneous Functions 'T. Yanagida'

Dynamic Fit Index Cutoffs

Description

This function computes simulation-based dynamic fit index cutoffs (McNeish & Wolf, 2022, 2023) for evaluating confirmatory factor models based on multivariate normal, multivariate non-normal, likert-type, and categorical data using the the omitted paths approach.

Usage

item.dfi(model, data = NULL, n = NULL, type = c("norm", "nnorm", "likert", "categ"),
         level = c(0, 1, 2, 3), res.cor = 0.3,   estimator = NULL,
         fit.indices = c("standard", "scaled", "robust"),
         specific = 0.95, sensitiv = 0.95, nrep = 500, seed = TRUE,
         progress = TRUE, print = c("all", "summary", "model", "cutoff"),
         digits = 3, plot = FALSE, filename = NULL, width = NA, height = NA,
         dpi = 600, write = NULL, append = TRUE, check = TRUE, output = TRUE)

Arguments

model	an object of class lavaan, i.e., a fitted CFA measurement model, an object of class misty of type item.cfa, or a character string indicating the lavaan model syntax for a CFA measurement model.
data	a data frame. Note that this argument is needed only when specifying a character string for the argument model while specifying "nnorm" or "likert" for the argument type as the data frame is extracted from the fitted model when specifying an object of class lavaan or misty for the argument model.
n	a numeric value indicating the number of observations for simulating fit index cutoffs. Note that this argument is needed only when specifying a character string for the argument model as the number of observations of the fitted model is extracted from the fitted model when specifying an object of class lavaan or misty for the argument model.
type	a character string indicating how data are simulated, i.e., "norm" (default when specifying a character string for the argument model) for assuming multivariate normality across all items, "nnorm" (default when specifying an object of class lavaan or misty for the argument model) for assuming multivariate non-normality across all items, "likert" assuming discrete likert-type items treated as continuous, or "categ" (default when specifying a categorical CFA model for the argument model) assuming ordered-categorical items.
level	a numeric vector (default: c(0, 1, 2, 3)) indicating the levels of misspecification for which fit index cutoffs are simulated. Note that 0 represents the true model without any misspecification and always needs to be included in the argument level.
res.cor	a numeric value (default: 0.3) indicating the magnitude of the residual correlations between items introduced for model misspecification in a one-factor CFA model.
estimator	a character string indicating the estimator to be used for simulating fit index cutoffs (see 'Details' in the help page of the item.cfa() function). Note that this argument is needed only when specifying a character string for the argument model as the estimator of the fitted model is extracted from the fitted model when specifying an object of class lavaan or misty for the argument model.
fit.indices	a character string indicating which version of the CFI, TLI, and RMSEA to compute for simulating fit index cutoffs, i.e., "standard" for fit indices without any non-normality correction, "scaled" for population-corrected robust fit indices with ad hoc non-normality correction, and robust for sample-corrected robust fit indices.
specific	a numeric value (default: 0.95) indicating specificity, i.e., proportions of correct models identified by the cutoffs.
sensitiv	a numeric value (default: 0.95) indicating sensitivity, i.e., proportions of incorrect models identified by the cutoffs.
nrep	an integer value (default: 500) indicating the number of replications in simulating fit index cutoffs.
seed	logical: if TRUE (default), the same seed of the pseudo-random numbers for simulating fit index cutoffs are used as in the R package dynamic to reproduce results provided by the cfaOne, cfaHB, nnorOne, nnorHB, likertOne, likertHB2, catOne, and catHB from the dynamic package
progress	logical: if TRUE (default), progress bar will be displayed while fitting the CFA measurement model to the simulated samples. Note that a for loop is used when progress = TRUE, while the sapply function is used when progress = FALSE.
print	a character string or character vector indicating the output shown on the console, i.e., "all" for all outputs, "summary" (default) for a summary of the specification in lavaan for the simulation, "model" for the lavaan model syntax for the CFA measurement model for each misspecification level specified for the simulation, "cutoff" (default) for the simulated fit index cutoffs.
digits	an integer value (default: 3) indicating the number of decimal places to be used for displaying fit indices.
plot	logical: if TRUE, distributions of fit indices for each level of misspecification is plotted.
filename	a character string indicating the filename argument including the file extension in the ggsave function. Note that one of ".eps", ".ps", ".tex", ".pdf" (default), ".jpeg", ".tiff", ".png", ".bmp", ".svg" or ".wmf" needs to be specified as file extension in the file
width	a numeric value indicating the width argument (default: size of the current graphics device) in the ggsave function.
height	a numeric value indicating the height argument (default: size of the current graphics device) in the ggsave function.
dpi	a numeric value indicating the dpi argument (default: 600) in the ggsave function.
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 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
args	specification of function arguments
model	object or character string specified in the argument model
data	a data frame extracted from the object specified in the argument model or a data frame specified in the argument data
sim.model	a list of character strings indicating the lavaan model syntax for the CFA measurement model for each misspecification level specified for the simulation
plot	ggplot2 object when specifying plot = TRUE
result	list with results, i.e., summary for the summary of the specification in lavaan for the simulation, summary.empirical for the summary of the specification in lavaan for the fitted model, fit.sim for a list with data frames for the simulated fit indices, fit.quant for a list with data frames with the quantiles for the simulated fit indices, fit.cutoff for a data frame with the simulated fit index cutoffs and the specificity and sensitivity for each fit index, and fit.emp for the chi-square value and empirical fit indices of the fitted model.

Note

This function is based on the functions cfaOne, cfaHB, nnorOne, nnorHB, likertOne, likertHB2, catOne, and catHB from the dynamic package by Melissa Gordon Wolf and Daniel McNeish (2026).

Author(s)

Takuya Yanagida

References

Liu, X., & McNeish, D. (2025). Optimal number of replications for obtaining stable dynamic fit index cutoffs. Educational and Psychological Measurement, 85(3), 539–564. https://doi.org/10.1177/00131644241290172

McNeish, D. (2023). Dynamic fit index cutoffs for categorical factor analysis with Likert-type, ordinal, or binary responses. American Psychologist, 78(9), 1061–1075. https://doi.org/10.1037/amp0001213

McNeish, D. & Wolf, M. G. (2022). Dynamic fit cutoffs for one-factor models. Behavior Research Methods, 55, 1157-1174. https://doi.org/10.3758/s13428-022-01847-y

McNeish, D., & Wolf, M. G. (2023). Dynamic fit index cutoffs for confirmatory factor analysis models. Psychological Methods, 28(1), 61-88. https://doi.org/10.1037/met0000425

McNeish, D. (2024). Dynamic fit index cutoffs for treating likert items as continuous. Psychological Methods. Advance online publication. https://doi.org/10.1037/met0000683

Wolf, M. G., & McNeish, D. (2026). dynamic: DFI Cutoffs for Latent Variable Models. R package version 1.1.0. Retrieved from https://github.com/melissagwolf/dynamic

See Also

item.cfa

Examples

## Not run: 
# Load lavaan package
library(lavaan)

#————————————————————————————————————————————————————————————————————————————
# Object of Class misty

#——————————————————————————————————————
## Multivariate Normality across all Items

# Conduct confirmatory factor analysis: Continuous items
mod1a.fit <- item.cfa(HolzingerSwineford1939, x1:x6, estimator = "ML")

# Example 1a: Simulate DFI cutoffs, multivariate normality
item.dfi(mod1a.fit, type = "norm")

#——————————————————————————————————————
## Multivariate Non-Normality across all Items

# Conduct confirmatory factor analysis: Continuous items
mod1b.fit <- item.cfa(HolzingerSwineford1939, x1:x6)

# Example 1b: Simulate DFI cutoffs, multivariate non-normality (default)
item.dfi(mod1b.fit)

#——————————————————————————————————————
## Likert-Type Items Treated as Continuous

# Conduct confirmatory factor analysis: Likert-type items as continuous
mod1c.fit <- item.cfa(data.items, pitem1, pitem2r, pitem3r, pitem4)

# Example 1c: Simulate DFI cutoffs, Likert-type
item.dfi(mod1c.fit, type = "likert")

#——————————————————————————————————————
## Ordered-Categorical Items

# Conduct confirmatory factor analysis: Ordered-categorical items
mod1d.fit <- item.cfa(data.items, pitem1, pitem2r, pitem3r, pitem4, ordered = TRUE)

# Example 1d: Simulate DFI cutoffs, ordered-categorical
item.dfi(mod1d.fit)

#————————————————————————————————————————————————————————————————————————————
# Object of Class lavaan

# Model specification
mod <- 'f =~ x1 + x2 + x3 + x4 + x5 + x6'

#——————————————————————————————————————
## Multivariate Normality across all Items

# Model estimation
mod2a.fit <- cfa(mod, data = HolzingerSwineford1939, estimator = "ML")

# Example 2a: Simulate DFI cutoffs, multivariate normality
mod2a.dfi <- item.dfi(mod2a.fit, type = "norm")

#——————————————————————————————————————
## Multivariate Non-Normality across all Items

# Model estimation
mod2b.fit <- cfa(mod, data = HolzingerSwineford1939, estimator = "MLR")

# Example 2b: Simulate DFI cutoffs, multivariate non-normality (default)
mod2b.fit <- item.dfi(mod2b.fit)

#——————————————————————————————————————
## Arguments 'print' and 'level'

# Model estimation
mod2c.fit <- cfa(mod, data = HolzingerSwineford1939, estimator = "MLR")

# Example 2c: Simulate DFI cutoffs, print all outputs
mod2c.dfi <- item.dfi(mod2c.fit, print = "all")

# Example 2c: Print model syntax for each misspecification level
print(mod2c.dfi, print = "model")

# Example 2d: Print fit index cutoffs with 5 digits
print(mod2c.dfi, digits = 5)

# Example 2e: Simulate DFI cutoffs, simulate misspecification level 0 only
item.dfi(mod2c.fit, level = 0)

#————————————————————————————————————————————————————————————————————————————
# Character String

# Model specification
mod3 <- 'f =~ 0.42*x1 + 0.21*x2 + 0.20*x3 + 0.85*x4 + 0.85*x5 + 0.84*x6'

# Example 3a: Simulate DFI cutoffs, multivariate normality (default)
item.dfi(mod3, n = 301, estimator = "ML")

# Example 3b: Simulate DFI cutoffs, multivariate non-normality
item.dfi(mod3, n = 301, data = HolzingerSwineford1939, estimator = "MLR")

#————————————————————————————————————————————————————————————————————————————
# Plot

# Conduct confirmatory factor analysis
mod3.fit <- item.cfa(HolzingerSwineford1939, x1:x6)

# Example 4: Plot distributions of fit indices for each level of misspecification
item.dfi(mod3.fit, plot = TRUE)

#————————————————————————————————————————————————————————————————————————————
# Write Results and Save Plot

# Conduct confirmatory factor analysis
mod4.fit <- item.cfa(HolzingerSwineford1939, x1:x6)

# Example 4a: Write Results into a text file
item.dfi(mod4.fit, write = "CFA_DFI.txt")

# Example 4b: Write Results into an Excel file
item.dfi(mod4.fit, write = "CFA_DFI.xlsx")

# Example 4c: Save Plot of distributions of fit indices
item.dfi(mod4.fit, plot = TRUE, filename = "CFA_DFI.png", width = 10, height = 7)

## End(Not run)

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