% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/item.dfi.R
\name{item.dfi}
\alias{item.dfi}
\title{Dynamic Fit Index Cutoffs}
\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{
\item{model}{an object of class lavaan, i.e., a fitted CFA measurement
model, an object of class misty of type \code{item.cfa}, or a
character string indicating the lavaan model syntax for
a CFA measurement model.}

\item{data}{a data frame. Note that this argument is needed only when
specifying a character string for the argument \code{model}
while specifying \code{"nnorm"} or \code{"likert"} for the
argument \code{type} as the data frame is extracted from
the fitted model when specifying an object of class
\code{lavaan} or \code{misty} for the argument \code{model}.}

\item{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 \code{model} as the number of observations of the
fitted model is extracted from the fitted model when specifying
an object of class \code{lavaan} or \code{misty} for the
argument \code{model}.}

\item{type}{a character string indicating how data are simulated, i.e.,
\code{"norm"} (default when specifying a character string
for the argument \code{model}) for assuming multivariate
normality across all items, \code{"nnorm"} (default when
specifying an object of class \code{lavaan} or \code{misty}
for the argument  \code{model}) for assuming multivariate
non-normality across all items, \code{"likert"} assuming
discrete likert-type items treated as continuous, or
\code{"categ"} (default when specifying a categorical CFA
model for the argument \code{model}) assuming ordered-categorical
items.}

\item{level}{a numeric vector (default: \code{c(0, 1, 2, 3)}) indicating
the levels of misspecification for which fit index cutoffs
are simulated. Note that \code{0} represents the true model
without any misspecification and always needs to be included
in the argument \code{level}.}

\item{res.cor}{a numeric value (default: \code{0.3}) indicating the magnitude
of the residual correlations between items introduced for
model misspecification in a one-factor CFA model.}

\item{estimator}{a character string indicating the estimator to be used
for simulating fit index cutoffs (see 'Details' in the help
page of the \code{item.cfa()} function). Note that this
argument is needed only when specifying a character string
for the argument \code{model} as the estimator of the
fitted model is extracted from the fitted model when specifying
an object of class \code{lavaan} or \code{misty} for the
argument \code{model}.}

\item{fit.indices}{a character string indicating which version of the CFI, TLI,
and RMSEA to compute for simulating fit index cutoffs, i.e.,
\code{"standard"} for fit indices without any non-normality
correction, \code{"scaled"} for population-corrected robust
fit indices with ad hoc non-normality correction, and
\code{robust} for sample-corrected robust fit indices.}

\item{specific}{a numeric value (default: \code{0.95}) indicating specificity,
i.e., proportions of correct models identified by the cutoffs.}

\item{sensitiv}{a numeric value (default: \code{0.95}) indicating sensitivity,
i.e., proportions of incorrect models identified by the cutoffs.}

\item{nrep}{an integer value (default: \code{500}) indicating the number of
replications in simulating fit index cutoffs.}

\item{seed}{logical: if \code{TRUE} (default), the same seed of the
pseudo-random numbers for simulating fit index cutoffs are
used as in the R package \pkg{dynamic} to reproduce results
provided by the \code{cfaOne}, \code{cfaHB}, \code{nnorOne},
\code{nnorHB}, \code{likertOne}, \code{likertHB2}, \code{catOne},
and \code{catHB} from the \pkg{dynamic} package}

\item{progress}{logical: if \code{TRUE} (default), progress bar will be
displayed while fitting the CFA measurement model to the
simulated samples. Note that a \code{for} loop is used when
\code{progress = TRUE}, while the \code{sapply} function
is used when \code{progress = FALSE}.}

\item{print}{a character string or character vector indicating the
output shown on the console, i.e., \code{"all"} for all
outputs, \code{"summary"} (default) for a summary of the specification
in lavaan for the simulation, \code{"model"} for the lavaan
model syntax for the CFA measurement model for each
misspecification level specified for the simulation,
\code{"cutoff"} (default) for the simulated fit index cutoffs.}

\item{digits}{an integer value (default: \code{3}) indicating the number
of decimal places to be used for displaying fit indices.}

\item{plot}{logical: if \code{TRUE}, distributions of fit indices for
each level of misspecification is plotted.}

\item{filename}{a character string indicating the \code{filename} argument
including the file extension in the \code{ggsave} function.
Note that one of \code{".eps"}, \code{".ps"}, \code{".tex"},
\code{".pdf"} (default), \code{".jpeg"}, \code{".tiff"},
\code{".png"}, \code{".bmp"}, \code{".svg"} or \code{".wmf"}
needs to be specified as file extension in the \code{file}}

\item{width}{a numeric value indicating the \code{width} argument (default:
size of the current graphics device) in the \code{ggsave}
function.}

\item{height}{a numeric value indicating the \code{height} argument (default:
size of the current graphics device) in the \code{ggsave}
function.}

\item{dpi}{a numeric value indicating the \code{dpi} argument
(default: \code{600}) in the \code{ggsave} function.}

\item{write}{a character string naming a file for writing the output
into either a text file with file extension \code{".txt"}
(e.g., \code{"Output.txt"}) or Excel file with file extension
\code{".xlsx"} (e.g., \code{"Output.xlsx"}). If the file
name does not contain any file extension, an Excel file will
be written.}

\item{append}{logical: if \code{TRUE} (default), output will be appended
to an existing text file with extension \code{.txt} specified
in \code{write}, if \code{FALSE} existing text file will be
overwritten.}

\item{check}{logical: if \code{TRUE} (default), argument specification
is checked.}

\item{output}{logical: if \code{TRUE} (default), output is shown.}
}
\value{
Returns an object of class \code{misty.object}, which is a list with following
entries:
\item{\code{call}}{function call}
\item{\code{type}}{type of analysis}
\item{\code{args}}{specification of function arguments}
\item{\code{model}}{object or character string specified in the argument \code{model}}
\item{\code{data}}{a data frame extracted from the object specified in the
                   argument \code{model} or a data frame specified in the
                   argument \code{data}}
\item{\code{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}
\item{\code{plot}}{ggplot2 object when specifying \code{plot = TRUE}}
\item{\code{result}}{list with results, i.e., \code{summary} for the summary
                     of the specification in lavaan for the simulation,
                     \code{summary.empirical} for the summary of the specification
                     in lavaan for the fitted model, \code{fit.sim} for a list
                     with data frames for the simulated fit indices, \code{fit.quant}
                     for a list with data frames with the quantiles for the
                     simulated fit indices, \code{fit.cutoff} for a data frame
                     with the simulated fit index cutoffs and the specificity
                     and sensitivity for each fit index, and \code{fit.emp}
                     for the chi-square value and empirical fit indices of
                     the fitted model.}
}
\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.
}
\note{
This function is based on the functions \code{cfaOne}, \code{cfaHB},
\code{nnorOne}, \code{nnorHB}, \code{likertOne}, \code{likertHB2},
\code{catOne}, and \code{catHB} from the \pkg{dynamic} package by Melissa
Gordon Wolf and Daniel McNeish (2026).
}
\examples{
\dontrun{
# 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(round(HolzingerSwineford1939[, c("x4", "x5", "x6", "x7")]))

# 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(round(HolzingerSwineford1939[, c("x4", "x5", "x6", "x7")]),
                      ordered = TRUE)

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

#————————————————————————————————————————————————————————————————————————————
# 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, nrep = 100)

#————————————————————————————————————————————————————————————————————————————
# 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)
}
}
\references{
Liu, X., & McNeish, D. (2025). Optimal number of replications for obtaining
stable dynamic fit index cutoffs. \emph{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. \emph{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.
\emph{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. \emph{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.
\emph{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
}
\seealso{
\code{\link{item.cfa}}
}
\author{
Takuya Yanagida
}
