nomo_cfa() fits a researcher-specified confirmatory factor model with
lavaan::cfa() and adds a transparent guidance layer around estimator
choice, convergence, standardized loadings, global fit, local residuals,
Heywood diagnostics, and modification indices.
Usage
nomo_cfa(
model,
data,
ordered = NULL,
estimator = NULL,
missing = NULL,
std.lv = FALSE,
control = NULL,
modification_indices = TRUE,
mi_top = 10L,
guidance = nomo_defaults()
)Arguments
- model
A researcher-specified
lavaanmeasurement-model syntax string or an object created bynomo_model().- data
A data frame containing the model indicators.
- ordered
Optional character vector naming binary/ordinal indicators. When supplied and
estimator = NULL,nomo_cfa()explicitly requestsWLSMV.- estimator
Optional
lavaanestimator. For continuous indicators, leaving this asNULLpreserveslavaan::cfa()'s default. Robust ML variants such as"MLR"remain explicit researcher choices.- missing
Optional
lavaanmissing-data option such as"fiml"for continuous ML models or"pairwise"where supported.- std.lv
Logical. Passed directly to
lavaan::cfa().- control
Optional named list passed to lavaan's optimizer through
lavaan::cfa(control = ...). This is an advanced troubleshooting/reproducibility option; non-default optimizer controls are recorded in the decision log.- modification_indices
Logical; if
TRUE, compute modification indices as quarantined diagnostics. They never trigger automatic respecification.- mi_top
Number of largest modification indices to retain in the compact
$top_modification_indicesview. The full table remains available in$modification_indices.- guidance
Guidance settings from
nomo_defaults().
Value
A nomo_cfa object. The fields to read are:
fit: the unchangedlavaanfit, for anything elselavaanreports.model: the model syntax fitted.converged,estimator,data_n,n_used, andsample_summary.fit_evidence: global fit indices with their teaching references.standardized_loadings: one row per loading, with its interval, flag, and explanation.factor_correlations: latent correlations with intervals.heywood: improper-solution signals, if any.parameter_estimatesandstandardized_solution:lavaan's parameter tables, as tibbles.residual_matrixandresidual_pairs: residual correlations, the pairs largest first.modification_indicesandtop_modification_indices: diagnostics only; nothing is freed.engine_warnings: warningslavaanraised.decision_log.
Other fields record the call, the settings used, and intermediate engine
results. They may change between releases and are not part of the stable
interface (see ?nomologR).
Details
The fitted lavaan object is retained unchanged in $fit. nomologR does
not free parameters, add residual covariances, delete indicators, or refit a
different model in response to fit statistics or modification indices.
References
Historical foundations:
Bentler, P. M., & Bonett, D. G. (1980). Significance tests and goodness of fit in the analysis of covariance structures. Psychological Bulletin, 88(3), 588-606. doi:10.1037/0033-2909.88.3.588
Jöreskog, K. G. (1969). A general approach to confirmatory maximum likelihood factor analysis. Psychometrika, 34(2), 183-202. doi:10.1007/BF02289343
Fit evaluation:
Bentler, P. M. (1990). Comparative fit indexes in structural models. Psychological Bulletin, 107(2), 238-246. doi:10.1037/0033-2909.107.2.238
Browne, M. W., & Cudeck, R. (1992). Alternative ways of assessing model fit. Sociological Methods & Research, 21(2), 230-258. doi:10.1177/0049124192021002005
Hu, L., & Bentler, P. M. (1999). Cutoff criteria for fit indexes in covariance structure analysis: Conventional criteria versus new alternatives. Structural Equation Modeling, 6(1), 1-55. doi:10.1080/10705519909540118
Marsh, H. W., Hau, K.-T., & Wen, Z. (2004). In search of golden rules: Comment on hypothesis-testing approaches to setting cutoff values for fit indexes and dangers in overgeneralizing Hu and Bentler's (1999) findings. Structural Equation Modeling, 11(3), 320-341. doi:10.1207/s15328007sem1103_2
Estimation, respecification, and improper solutions:
Flora, D. B., & Curran, P. J. (2004). An empirical evaluation of alternative methods of estimation for confirmatory factor analysis with ordinal data. Psychological Methods, 9(4), 466-491. doi:10.1037/1082-989X.9.4.466
Kolenikov, S., & Bollen, K. A. (2012). Testing negative error variances: Is a Heywood case a symptom of misspecification? Sociological Methods & Research, 41(1), 124-167. doi:10.1177/0049124112442138
MacCallum, R. C., Roznowski, M., & Necowitz, L. B. (1992). Model modifications in covariance structure analysis: The problem of capitalization on chance. Psychological Bulletin, 111(3), 490-504. doi:10.1037/0033-2909.111.3.490
Rhemtulla, M., Brosseau-Liard, P. É., & Savalei, V. (2012). When can categorical variables be treated as continuous? A comparison of robust continuous and categorical SEM estimation methods under suboptimal conditions. Psychological Methods, 17(3), 354-373. doi:10.1037/a0029315
Rosseel, Y. (2012). lavaan: An R package for structural equation modeling. Journal of Statistical Software, 48(2), 1-36. doi:10.18637/jss.v048.i02
Examples
model <- '
visual =~ x1 + x2 + x3
textual =~ x4 + x5 + x6
speed =~ x7 + x8 + x9
'
out <- nomo_cfa(model, data = lavaan::HolzingerSwineford1939)
summary(out)
#> <nomo_cfa summary> Confirmatory factor analysis
#> Cases: 301 of 301 used | Estimator: ML | Converged: yes
#>
#> Global fit
#> chi-square(24) = 85.31, p < .001
#> Index Value 90% CI Reference
#> CFI 0.931 0.950
#> TLI 0.896 0.950
#> RMSEA 0.092 [0.071, 0.114] 0.060
#> SRMR 0.065 0.080
#> References are teaching values for review, not cutoffs.
#>
#> Standardized loadings
#> Factor Item Loading SE 95% CI Flag
#> visual x1 0.772 0.055 [0.664, 0.880]
#> visual x2 0.424 0.060 [0.307, 0.540] review
#> visual x3 0.581 0.055 [0.473, 0.689]
#> textual x4 0.852 0.023 [0.807, 0.896]
#> textual x5 0.855 0.022 [0.811, 0.899]
#> textual x6 0.838 0.023 [0.792, 0.884]
#> speed x7 0.570 0.053 [0.465, 0.674]
#> speed x8 0.723 0.051 [0.624, 0.822]
#> speed x9 0.665 0.051 [0.565, 0.765]
#>
#> Flagged loadings
#> - x2 on visual (review): Absolute standardized loading is below the
#> configured teaching reference of 0.5; inspect item content, precision, and
#> model specification.
#>
#> Factor correlations
#> Factor 1 Factor 2 r 95% CI
#> visual textual 0.459 [0.334, 0.584]
#> visual speed 0.471 [0.328, 0.613]
#> textual speed 0.283 [0.148, 0.418]
#>
#> Improper solutions
#> No improper-solution signal, such as a negative residual variance, was
#> detected.
#>
#> Largest residual correlations
#> Item 1 Item 2 Residual
#> x7 x2 -0.189
#> x5 x3 -0.151
#> x9 x1 0.149
#> x9 x3 0.147
#> x7 x1 -0.140
#>
#> Modification indices (diagnostic only)
#> Parameter MI EPC Std. EPC
#> visual =~ x9 36.41 0.577 0.515
#> x7 ~~ x8 34.15 0.536 0.859
#> visual =~ x7 18.63 -0.422 -0.349
#> x8 ~~ x9 14.95 -0.423 -0.805
#> textual =~ x3 9.15 -0.272 -0.238
#> Modification indices locate strain. They do not authorize freeing a
#> parameter, and nomologR never does so automatically.
#>
#> Global fit, local strain, and parameter estimates are evidence to interpret
#> together; no single cutoff establishes model validity.
# \donttest{
# Declared ordered indicators request WLSMV rather than ML
ordinal_model <- nomo_model(list(
A = c("a1", "a2", "a3", "a4", "a5"),
B = c("b1", "b2", "b3", "b4", "b5")
))
out_ord <- nomo_cfa(
ordinal_model,
data = nomo_demo_ordinal,
ordered = names(nomo_demo_ordinal)
)
out_ord$fit_evidence
#> # A tibble: 9 × 7
#> metric value variant reference direction attention explanation
#> <chr> <dbl> <chr> <dbl> <chr> <chr> <chr>
#> 1 chi_square 93.5 chisq.s… NA informat… info Descriptiv…
#> 2 df 34 df.scal… NA informat… info Descriptiv…
#> 3 p_value 0.000000188 pvalue.… NA informat… info Descriptiv…
#> 4 CFI 0.971 cfi.rob… 0.95 higher info At or abov…
#> 5 TLI 0.961 tli.rob… 0.95 higher info At or abov…
#> 6 RMSEA 0.0535 rmsea.r… 0.06 lower info At or belo…
#> 7 RMSEA_CI_lower 0.0348 rmsea.c… NA informat… info Descriptiv…
#> 8 RMSEA_CI_upper 0.0719 rmsea.c… NA informat… info Descriptiv…
#> 9 SRMR 0.0475 srmr 0.08 lower info At or belo…
# }