xmu_robust_WLS_fit: Robust WLS fit statistics: Satorra-Bentler (2010) and Savalei...

In umx: Structural Equation Modeling and Twin Modeling in R

Robust WLS fit statistics: Satorra-Bentler (2010) and Savalei (2021)

Description

Computes robust fit indices and scaled test statistics for Weighted Least Squares (WLS / DWLS) models fitted in OpenMx. This is the engine behind WLS routing in umxSummary() and umxCompare().

The function intentionally uses two statistic families:

• Display omnibus test (Chi, ChiDoF, p): always Satorra-Bentler (2010) scaled WLS \chi^2, regardless of whether manifests are continuous or ordinal.

• Robust incremental/absolute indices (CFI, TLI, RMSEA): Satorra-Bentler (2010) for continuous WLS; Savalei (2021) catML mean-and-variance corrections for ordinal/categorical WLS.

Independence (null) baseline fit is computed natively in R (not via mxRun) so that asymptotic-covariance-only inputs (e.g. Genomic SEM / summary-statistic pipelines) do not trigger OpenMx validation errors.

Usage

xmu_robust_WLS_fit(model)

Arguments

model

A fitted WLS OpenMx::mxModel() with implied_jacobian.

Details

Prerequisites. The fitted model must expose model@output$implied_jacobian, plus WLS asymCov and useWeight (or equivalent) with consistent moment rownames. Without the Jacobian, the function stops with an error.

Shared pipeline (both branches).

1. Extract raw target WLS \chi^2_{raw}, test df, and implied Jacobian \Delta_{target}.

2. Align \Delta, \Gamma (asymCov), and W (useWeight) to a common moment ordering via xmu_WLS_align_jacobian() and xmu_WLS_align_weight().

3. Build independence Jacobian \Delta_{ind} with xmu_build_independence_jacobian() on the same moment set.

4. Compute native independence discrepancy \chi^2_{ind,raw} = d_{ind}' W d_{ind}, where d_{ind} is the observed summary vector with means, variances, and thresholds zeroed (independence pattern).

5. Scale matrices to sample size n for raw-data models.

6. Compute Satorra-Bentler trace scaling factors

   U = \Gamma W - \Gamma W \Delta (\Delta' W \Delta)^{-1} \Delta' W

   c = \mathrm{tr}(U) / df

   for target (c_{model}) and independence (c_{null}) models.

7. Form display statistics: \chi^2_{SB} = \chi^2_{raw} / c_{model}, with p = 1 - F_{\chi^2_{df}}(\chi^2_{SB}).

Branch A - Continuous WLS (correction = "SB2010"). Detected when no manifest is ordered or factor on raw data (xmu_is_ordinal_WLS() returns FALSE). Robust CFI, TLI, and RMSEA are derived from SB-scaled target and independence \chi^2 and their dfs. Attributes c_model and c_null hold the SB trace factors.

Branch B - Ordinal / categorical WLS (correction = "Savalei2021"). Detected when at least one manifest is ordered or factor. Robust indices use the Brosseau-Liard / Savalei noncentrality form with catML ingredients evaluated at fixed converged WLS estimates (no re-optimization):

catML discrepancy XX_3. xmu_catml_discrepancy_at_WLS() builds a correlation-matrix ML scaffold (xmu_catml_eval_model()), runs reference models, and returns:

• fMlTarget = XX_3 (target minus saturated correlation fit)

• fMlNull = XX_{3,null} (independence minus saturated)

Savalei scaling \hat{c}_3. xmu_savalei_polycor_blocks() assembles OpenMx-native polycor blocks:

V

catML expected information at model-implied correlation (xmu_catml_wls_v()); not asymCov and not solve(useWeight).

\Gamma_{poly}

Sample moment covariance: n^2 \times polycor block of per-observation asymCov.

W_{poly}

WLS weight polycor block at sample scale: n \times per-observation useWeight.

\Delta_{poly}

Polycor rows of aligned implied_jacobian (threshold rows excluded).

E^{-1}

(\Delta_{full}' W_{full} \Delta_{full})^{-1} from the identically scaled full weight matrix.

Then xmu_savalei_scaling_factor() computes

\hat{c}_3 = \frac{\mathrm{tr}(W_i U' V W_i U \, \Gamma_{poly})}{df_3}

with W_i U = I - \Delta_{poly} E^{-1} \Delta_{poly}' W_{poly}, and xmu_savalei_null_scaling_factor() computes \hat{c}_{3,null} = \mathrm{tr}(\Gamma_{poly}) / df_{3,null}.

Degrees of freedom: df_3 = WLS model test df; df_{3,null} = number of polycorrelation moments (length(polyNames)). Jacobian-rank shortcuts (xmu_catml_df3_diagnostic()) are diagnostic only.

Robust indices: xmu_savalei_fit_cfi(), xmu_savalei_fit_tli(), xmu_savalei_fit_rmsea() with XX_3, \hat{c}_3, \hat{c}_{3,null}. CFI is clamped to [0, 1]; TLI may slightly exceed 1 with excellent fit. If Savalei scaling fails, \hat{c}_3 falls back to SB c_{model} (and null analogously).

Cutoff guidance. For ordinal WLS, Hu & Bentler (1999) conventional cutoffs (e.g. CFI \geq 0.95, RMSEA \leq 0.06) apply to the robust CFI/TLI/RMSEA reported here-not to raw WLS \chi^2. Display \chi^2 and p remain SB-scaled WLS omnibus tests.

Software note. Numeric values of \hat{c}_3 may differ from other SEM packages because Jacobians and parameterizations differ across engines; umx uses OpenMx implied_jacobian and native asymCov/useWeight throughout. The goal is statistically correct evaluation under OpenMx, not bitwise replication of external implementations.

Value

A named list designed to patch directly into umxSummary() slots:

CFI, TLI, RMSEA

Robust fit indices (SB2010 or Savalei2021 branch).

Chi

SB-scaled target \chi^2 (display omnibus statistic).

ChiDoF

Target model test degrees of freedom.

p

Two-sided p-value for Chi under \chi^2_{df}.

scalingFactor, scalingFactorNull

SB trace factors c_{model} and c_{null} (always computed).

Attributes (read by umxSummary() for footnotes):

correction

"SB2010" or "Savalei2021".

c_model

Scaling factor used for robust target noncentrality (SB c or Savalei \hat{c}_3).

c_null

Scaling factor for null/independence noncentrality.

fMlTarget, fMlNull

catML XX_3 components when Savalei branch runs; NA_real_ otherwise.

References

• Satorra, A., & Bentler, P. M. (2010). Ensuring positiveness of the scaled difference chi-square test statistic. Psychometrika, 75(2), 243–269.

• Savalei, V. (2021). Improving fit indices in SEM with categorical data. Multivariate Behavioral Research, 56(3), 390–407.

• Brosseau-Liard, P. E., & Savalei, V. (2012). Adjusting incremental fit indices for nonnormality. Multivariate Behavioral Research, 47(5), 647–677.

• Hu, L., & Bentler, P. M. (1999). Cutoff criteria for fit indexes in covariance structure analysis. Structural Equation Modeling, 6, 1–55.

See Also

umxSummary(), umxCompare(), xmu_build_independence_jacobian, xmu_is_ordinal_WLS(), xmu_catml_discrepancy_at_WLS(), xmu_savalei_polycor_blocks()

Other Model Summary and Comparison: umx, umxCompare(), umxEquate(), umxMI(), umxReduce(), umxSetParameters(), umxSummary(), xmu_compare_WLS()

umx documentation built on Oct. 11, 2026, 5:07 p.m.