epcEquivFit: EPC Equivalence Fit Evaluation Using Modification Indices

In semTools: Useful Tools for Structural Equation Modeling

EPC Equivalence Fit Evaluation Using Modification Indices

Description

Evaluates model fit from an equivalence-testing perspective by aggregating local EPC-based diagnostics into a global, fit-style assessment. The procedure combines modification indices (MI), expected parameter changes (EPC), statistical power, and confidence intervals relative to a smallest effect size of interest (SESOI).

Usage

epcEquivFit(lavaanObj, stdLoad = 0.4, cor = 0.1, corLatent = NULL,
  corResidual = NULL, stdBeta = 0.1, stdIntcept = 0.2, stdSesoi = NULL,
  sesoi = NULL, cilevel = 0.9, mialpha = 0.05, mipower = 0.8,
  adjust.method = "none", ...)

## S3 method for class 'epcequivfit.data.frame'
summary(object, ..., top = 5, ssv = FALSE)

Arguments

lavaanObj	A fitted lavaan object used to evaluate model fit.
stdLoad	Standardized factor loading defining the SESOI for loading misspecifications. Default is 0.4.
cor	Default standardized correlation defining the SESOI for covariance misspecifications. Used for both latent and residual covariances unless overridden.
corLatent	Standardized latent factor correlation defining the SESOI for latent covariance misspecifications. If NULL, defaults to cor.
corResidual	Standardized residual correlation defining the SESOI for residual covariance misspecifications. If NULL, defaults to cor.
stdBeta	Standardized regression coefficient defining the SESOI for structural misspecifications. Default is 0.1.
stdIntcept	Standardized intercept (Cohen's d) defining the SESOI for intercept misspecifications. Default is 0.2.
stdSesoi	Optional vector of standardized SESOI values. If provided, overrides operator-specific SESOI definitions.
sesoi	Optional vector of unstandardized SESOI values. If provided, overrides stdSesoi and all operator-specific SESOI arguments.
cilevel	Confidence level for EPC confidence intervals used in CI-based equivalence testing.
mialpha	Significance level used for evaluating modification indices in the power-based decision rule (Method 1). Default is 0.05.
mipower	Desired statistical power for detecting a misspecification of the specified SESOI in the power-based decision rule. Default is 0.80.
adjust.method	Multiplicity adjustment method applied to both modification index tests and EPC confidence intervals. Currently supported options are "none" (no adjustment) and "bonferroni". When "bonferroni" is used, the MI significance level and CI level are adjusted across all evaluated fixed parameters.
...	Additional arguments passed to modificationIndices.
object	An object returned by epcEquivFit.
top	Number of top-ranked EPCs to display.
ssv	Logical; whether to include power-based diagnostics.

Details

Two complementary local decision rules are implemented:

Method 1 (Power-based; Saris, Satorra, & van der Veld, 2009). Modification indices, statistical power, and EPC magnitude are jointly evaluated (the J-rule) to classify fixed parameters as misspecified, not misspecified, or inconclusive.

Method 2 (CI-based equivalence testing). Confidence intervals of EPCs are compared against a trivial misspecification region defined by the SESOI to determine whether fixed parameters are substantially misspecified, trivially misspecified, underpowered, or inconclusive.

The resulting local classifications are returned in a single data frame and can be summarized to yield a global equivalence-style fit evaluation.

This function provides a local-to-global equivalence-based alternative to traditional exact-fit evaluation. It is designed to assess whether fixed parameters are substantively misspecified relative to a SESOI, rather than whether a model fits exactly.

When adjust.method = "bonferroni", familywise error control is applied across all evaluated fixed parameters by adjusting the MI significance threshold and widening EPC confidence intervals.

Models with categorical indicators or unsupported constraints may not be fully supported.

Value

A data frame with one row per fixed parameter, containing:

1. Parameter identifiers: lhs, op, rhs, and group.

2. Modification index (mi) and expected parameter change estimates (epc).

3. Unstandardized and standardized smallest effect size of interest values (sesoi, std.sesoi).

4. Power-based decision (decision.pow) and related diagnostics, including whether the modification index is statistically significant (significant.mi) and whether the misfit at the SESOI has power greater than 0.80 (high.power). Decision labels are: M = Substantially Misspecified, I = Inconclusive, NM = Trivially Misspecified, EPC:M = Substantially Misspecified based on EPC information, EPC:NM = Trivially Misspecified based on EPC information.

5. EPC-related statistics, including the standard error of the EPC (se.epc), confidence interval bounds for the EPC (lower.epc, upper.epc), and confidence interval bounds for the standardized EPC (lower.std.epc, upper.std.epc).

6. Confidence-interval–based equivalence decision (decision.ci), with labels: M = Substantially Misspecified (EPC exceeds the SESOI), I = Inconclusive, NM = Trivially Misspecified, U = Underpowered (CI too wide to evaluate equivalence relative to the SESOI).

References

Saris, W. E., Satorra, A., & van der Veld, W. M. (2009). Testing structural equation models or detection of misspecifications? Structural Equation Modeling, 16(4), 561–582.

See Also

epcEquivCheck

Examples

library(lavaan)

one.model <- ' onefactor  =~ x1 + x2 + x3 + x4 + x5 + x6 + x7 + x8 + x9 '
fit <- cfa(one.model, data = HolzingerSwineford1939)
out <- epcEquivFit(fit)
out
summary(out)

semTools documentation built on Oct. 7, 2026, 5:08 p.m.