Latent Variable Models Diagnostics

Diagnostics and visualization tools for latent variable models fitted with 'lavaan' (Rosseel, 2012 ). The package provides fast, parallel-safe factor-score prediction (lavPredict_parallel()), data augmentation with model predictions, residuals, delta-method standard errors and confidence intervals (augment()), and model-based latent grids for continuous, ordinal, or mixed indicators (prepare()). It offers item-level empirical versus model curve comparison using generalized additive models for both continuous and ordinal indicators (item_data(), item_plot()) via 'mgcv' (Wood, 2017, ISBN:9781498728331), residual diagnostics including residual correlation tables and plots (resid_cor(), resid_corrplot()) using 'corrplot' (Wei and Simko, 2021 < https://github.com/taiyun/corrplot>), and Q–Q checks of residual z-statistics (resid_qq()), optionally with non-overlapping labels from 'ggrepel' (Slowikowski, 2024 < https://CRAN.R-project.org/package=ggrepel>). Heavy computations are parallelized via 'future'/'furrr' (Bengtsson, 2021 ; Vaughan and Dancho, 2018 < https://CRAN.R-project.org/package=furrr>). Methods build on established literature and packages listed above.

lavDiag

Diagnostics and Visualization for Latent Variable Models

Overview

lavDiag extends the lavaan ecosystem with a suite of diagnostic, visualization, and empirical-fit tools for latent variable models (CFA, SEM, and related frameworks). It provides fast, parallel-safe computation of factor scores, model-based predictions, and empirical versus model fit curves for both continuous and ordinal indicators.

All functions are designed to work seamlessly with single-group and multi-group models, returning tidy tibble outputs ready for plotting or downstream analysis.

Key Features

• 🔹 Fast parallel factor scores lavPredict_parallel() — a robust, ordinal-aware replacement for lavaan::lavPredict().

• 🔹 Augmentation and diagnostics augment() — attaches model predictions, residuals, SEs, and CIs to observed data.

• 🔹 Model-based grids prepare() — generates smooth latent grids and model-based item curves for continuous, ordinal, and mixed indicators.

• 🔹 Empirical vs. model item curves item_data() + item_plot() — compare model-implied and empirical (GAM-based) curves with metrics like R², RMSE, and MAE.

• 🔹 Residual diagnostics

  • resid_cor() — extract residual correlations
  • resid_corrplot() — visualize residual correlation matrices
  • resid_qq() — Q–Q plots of residual z-statistics
  • hopper_plot() — visualize residual “hopper” patterns

• 🔹 Model summaries and estimates model_info() and parameter_estimates() — consistent schema for metadata and estimates.

• 🔹 CFA visualization plot_cfa() — clean diagrams using visNetwork.

Installation

From GitHub

# install.packages("remotes")
remotes::install_github("reckak/lavDiag")

From CRAN (once accepted)

install.packages("lavDiag")

Quick Example

library(lavaan)
library(lavDiag)

# Example CFA
HS.model <- '
  visual  =~ x1 + x2 + x3
  textual =~ x4 + x5 + x6
  speed   =~ x7 + x8 + x9
'

fit <- cfa(HS.model, data = HolzingerSwineford1939, meanstructure = TRUE)

# Augment observed data with model predictions and residuals
aug <- augment(fit)

# Compute and visualize item-level empirical fit
it <- item_data(fit)
item_plot(it)

# Residual correlation plot
resid_corrplot(fit, type = "cor.bentler")

Parallelization

Most computationally intensive functions (e.g., lavPredict_parallel(), item_data(), prepare()) use future and furrr backends for safe parallelism. Backends are configurable via .set_future_plan().

Dependencies

Core dependencies include:

• lavaan, dplyr, tidyr, purrr, tibble
• future, furrr, mgcv, corrplot, ggplot2, visNetwork

All functions use consistent tidy-style output and rlang-safe programming.

Contributing

Issues, pull requests, and feedback are welcome!

• 📬 Report bugs: GitHub Issues
• 💡 Feature requests: open an issue or start a discussion

Citation

If you use lavDiag in your research, please cite it as:

Rečka, K. (2025). lavDiag: Diagnostics and Visualization for Latent Variable Models. GitHub: https://github.com/reckak/lavDiag

License

MIT License © 2025 Karel Rečka