Enhance EPC equivalence fit output and preserve miPowerFit compatibility

semTools/NAMESPACE

@@ -1,5 +1,8 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(print,epcEquivCheckStd)
+S3method(print,summaryEpcEquivFit)
+S3method(summary,epcequivfit.data.frame)
 export(AVE)
 export(PAVranking)
 export(SSpower)
@@ -17,6 +20,8 @@ export(compareFit)
 export(discriminantValidity)
 export(efa.ekc)
 export(efaUnrotate)
+export(epcEquivCheck)
+export(epcEquivFit)
 export(findRMSEApower)
 export(findRMSEApowernested)
 export(findRMSEAsamplesize)
@@ -47,7 +52,6 @@ export(maximalRelia)
 export(measEq.syntax)
 export(measurementInvariance)
 export(measurementInvarianceCat)
-export(miPowerFit)
 export(modificationIndices.mi)
 export(modificationindices.mi)
 export(modindices.mi)
@@ -120,6 +124,7 @@ importFrom(lavaan,lavTestLRT)
 importFrom(lavaan,lavaan)
 importFrom(lavaan,lavaanList)
 importFrom(lavaan,lavaanify)
+importFrom(lavaan,modificationIndices)
 importFrom(lavaan,parTable)
 importFrom(methods,as)
 importFrom(methods,getMethod)

semTools/NEWS.md

@@ -12,7 +12,14 @@
     - `return.df=` argument replaced by `simplify=`
     - Coefficients now returned (by default) in a list, with headers indicating how to appropriately interpret each coefficient. 
       The verbose headers can be suppressed (mimicking old behavior) by setting `simplify = -1L`
-- TODO: Sunthud's update
+- `miPowerFit()` has been renamed to `epcEquivFit()` and its functionality has been substantially extended.
+    - The output of `epcEquivFit()` now has its own class, `epcequivfit.data.frame`. A dedicated `summary()` method is provided, which reports both local classifications of fixed parameters and the resulting global equivalence decision.
+    - By default, `epcEquivFit()` focuses on equivalence testing based on expected parameter changes (EPCs). The Saris, Satorra, and van der Veld (2009) decision rule based on modification indices and power is retained but is no longer treated as the primary result, as simulation results favor the EPC equivalence-testing approach.
+    - The equivalence-testing procedure has been extended to include an underpowered classification when the EPC confidence interval (CI) is wider than the smallest effect size of interest (SESOI) region.
+    - The arguments and the resulting column names with `target.epc` has been renamed to reflect the smallest effect size of interest (SESOI), consistent with terminology in the equivalence-testing literature.
+    - Standardized EPCs for indicator residual covariances are now computed by scaling residual covariances by residual variances, rather than by total indicator variances as in `lavaan` and other SEM packages, providing a more appropriate effect-size representation for residual relationships.
+    - A new function, `epcEquivCheck()`, is introduced to assess whether trivial misspecification is difficult to establish for a given model under the EPC equivalence-testing framework.
+    - Clipboard utilities have been updated to accommodate these changes, and all relevant documentation has been revised to reflect the transition from `miPowerFit()` to `epcEquivFit()`.
 
 ## Bug Fixes:
 

semTools/R/clipboard.R

@@ -18,8 +18,8 @@
 ##'   [FitDiff-class].
 ##' @param what The attributes of the `lavaan` object to be copied in the
 ##'   clipboard. `"summary"` is to copy the screen provided from the
-##'   `summary` function. `"mifit"` is to copy the result from the
-##'   [miPowerFit()] function. Other attributes listed in the
+##'   `summary` function. `"epceqfit"` is to copy the result from the
+##'   [epcEquivFit()] function. Other attributes listed in the
 ##'   `inspect` method in the [lavaan::lavaan-class] could also be
 ##'   used, such as `"coef"`, `"se"`, `"fit"`, `"samp"`, and
 ##'   so on.  Ignored for [FitDiff-class]-class objects.
@@ -33,7 +33,7 @@
 ##' @param writeArgs `list` of additional arguments to be passed to
 ##'   [utils::write.table()]
 ##' @param \dots Additional arguments when passing a `lavaan` object to the
-##'   `summary` or [miPowerFit()] function.
+##'   `summary` or [epcEquivFit()] function.
 ##'
 ##' @return The resulting output will be saved into a clipboard or a file. If
 ##'   using the `clipboard` function, users may paste it in the other
@@ -60,8 +60,8 @@
 ##' # pass additional arguments to summary() method for class?lavaan
 ##' clipboard(fit, rsquare = TRUE, standardized = TRUE, fit.measures = TRUE)
 ##'
-##' # Copy modification indices and fit stats from the miPowerFit() function
-##' clipboard(fit, "mifit")
+##' # Copy the EPC equivalence testing results from the epcEquivFit() function
+##' clipboard(fit, "epceqfit")
 ##'
 ##' # Copy the parameter estimates
 ##' clipboard(fit, "coef")
@@ -78,8 +78,8 @@
 ##' # Save the summary of the lavaan object
 ##' saveFile(fit, "out.txt")
 ##'
-##' # Save modification indices and fit stats from the miPowerFit() function
-##' saveFile(fit, "out.txt", "mifit")
+##' # Save the EPC equivalence testing results from the epcEquivFit() function
+##' saveFile(fit, "out.txt", "epceqfit")
 ##'
 ##' # Save the parameter estimates
 ##' saveFile(fit, "out.txt", "coef")
@@ -162,13 +162,13 @@ saveFileLavaan <- function(object, file, what = "summary", tableFormat = FALSE,
 		  writeArgs$x <- paste(utils::capture.output(summary(object, ...)),
 		                       collapse = "\n")
 		}
-	} else if (what == "mifit") {
+	} else if (what %in% c("epceqfit", "mifit")) { # "mifit" retained for backward compatibility
 		if (tableFormat) {
-		  writeArgs$x <- miPowerFit(object, ...)
+		  writeArgs$x <- epcEquivFit(object, ...)
 		  if (is.null(writeArgs$row.names)) writeArgs$row.names <- FALSE
 		  if (is.null(writeArgs$col.names)) writeArgs$col.names <- TRUE
 		} else {
-		  writeArgs$x <- paste(utils::capture.output(miPowerFit(object, ...)),
+		  writeArgs$x <- paste(utils::capture.output(epcEquivFit(object, ...)),
 		                       collapse = "\n")
 		}
 	} else {

semTools/R/fitIndices.R

@@ -152,8 +152,8 @@
 ##'
 ##' @seealso
 ##' \itemize{
-##' \item [miPowerFit()] For the modification indices and their
-##'        power approach for model fit evaluation
+##' \item [epcEquivFit()] For the equivalence testing based on expected
+##'   parameter changes for model fit evaluation
 ##' \item [nullRMSEA()] For RMSEA of the default independence model
 ##' }
 ##'