sem.check: Runs lavaan models after checking for code or data changes.
In semFromKeys: Run 'lavaan' Models from Keys Lists

View source: R/sem.check.R

sem.check

R Documentation

Runs lavaan models after checking for code or data changes.

Description

sem.check produces outputs from a series of lavaan models. For each model, the code checks for previously saved model code, a hash of data, and important parameter inputs. If they exist and match values for the current code and data, the model is not run, the previous output is loaded instead. If either the code has changed, the hash of the data has changed, or important parameter inputs have change, or any of these do not exist, then the models are run as normal.

Usage

sem.check(
  mods,
  data,
  keys_s = NULL,
  keys_e = NULL,
  fit_save = FALSE,
  fit_measures = "all",
  miss = "ML",
  est = "default",
  std.lv = FALSE,
  std = TRUE,
  orthogonal = FALSE,
  target = NULL,
  name = "sem",
  check = FALSE,
  save_out = FALSE
)

Arguments

`mods`	A named list of lavaan models to run.
`data`	A dataframe or object coercible to a dataframe. Data must include all observed variables used in any of the models.
`keys_s`	A named keys list matching the names and length of mod.
`keys_e`	A named keys list of the factors in an ESEM to be included.
`fit_save`	Logical. `TRUE` indicates model fit measures should be included in the output; `FALSE` indicates model fit measures should not be included in the output. `FALSE` may be desirable when fit measures are of little interest and when they may take a long time to estimate. Fit can still be examined for individual models with, `⁠lavaan::fitMeasures(fit$fit$[model name])⁠`.
`fit_measures`	A vector of fit measures to save or 'all' to select all fit measures, as per the `fit.measures` parameter from lavaan's `lavaan::fitMeasures()` function. Defaults to 'all'. Irrelevant if `fit_save = FALSE`.
`miss`	A string. Sets the `missing` parameter, as per lavaan (see `lavaan::lavOptions()`). Defaults to 'ML'.
`est`	A string. Sets the `estimator` parameter, as per lavaan (see `lavaan::lavOptions()`). The default ('default') uses the lavaan default for the model being run.
`std.lv`	Logical. Sets the `std.lv` parameter, as per lavaan (see `lavaan::lavOptions()`). `TRUE` indicates that factor variances should be fixed to 1. `FALSE` indicates that loadings of the first items of factors should be fixed to 1. Defaults to `FALSE`.
`std`	Logical. `TRUE` indicates that standardised parameter estimates should be saved; `FALSE` indicates that unstandardised parameters estimates should be saved.
`orthogonal`	Logical. Sets the `orthogonal` parameter, as per lavaan (see `lavaan::lavOptions()`). `TRUE` indicates that unspecified latent variable correlations should be fixed at 0; `FALSE` indicates that unspecified latent variable correlations should be freely estimated. Defaults to `FALSE`.
`target`	A matrix indicating a rotation target, as used in the `rotation.args` argument in lavaan (see `lavaan::efa()`. If `NULL` (default), target is not specified and lavaan uses default behaviour. Irrelevant when the model does not include an EFA or ESEM.
`name`	A string indicating a subdirectory where model outputs will be saved when `save_out = TRUE` and checked against when `check = TRUE`. Defaults to "sem". The name should be unique for each set of models or outputs from calls with the same name will be overwritten.
`check`	Logical. `TRUE` indicates that current inputs should be compared to previous inputs if they exist and that the model should not be rerun if nothing has changed; `FALSE` indicates that these checks should not be made and the model should be run regardless of the existence of previous inputs.
`save_out`	Logical. `TRUE` indicates that model code, a hash of the data, important input parameter values, and output will be saved; `FALSE` indicates that nothing will be saved. Selecting `save_out = TRUE` enables the function to not rerun models next time if `check = TRUE` the next time the code is run and nothing has changed in the meantime.

Details

The function is largely intended to be used as a helper function to upstream functions, including cfa.from.keys(), bifactor.from.keys(), efa.from.keys(), and esem.from.mods(). Although it is recommended to use the appropriate upstream function whenever possible, there are not (currently) options to do so when customised lavaan models are required; for example, when allowing two items' residuals to correlate in a CFA. sem.check() can be used in these cases (see example).

Matching the philosophy of the package, the function is designed to run for multiple models with a similar design. If you are using the function for a single model, transform inputs into lists as appropriate.

When save_out = TRUE, if a cache directory has been set, the model will save various inputs and outputs from the function call. When check = TRUE, the model will look for any previously saved outputs from earlier model runs in the same cache directory and only run again if nothing has changed. In cases where something has changed for a subset of models (e.g., a data cleaning mistake might affect only a subset of variables in a subset of models), then the function will only re-run the models where something has changed. Changes to arguments that influence all lavaan model runs (e.g., miss or est) will trigger all models to be re-run.

For either save_out = TRUE or check = TRUE, the function will look for a cache directory set and created by the cache.setup() function. If a cache directory has not been set for the current session, then the function will exit with an error suggesting that either cache.setup() be run or save_out and check set to FALSE.

When the cache directory is found and output from previous runs are detected, the comparisons performed are for: model code; hashes of the data (using openssl::md5()); values of the miss, est, std, std.lv, and orthogonalparameters; the class of model objects (i.e., class lavaan); and the class of parameter estimates (i.e., class lavaan.data.frame).

For most applications, the checking feature can be safely ignored by not saving outputs (i.e., fit_save = FALSE) and not checking for past saves (i.e., check = FALSE, both default). The functionality is intended for a number of very slow models or a very large number of faster models, such that time spent rerunning code would be onerous. However, the functionality can be safely used for faster runs too.

Value

Returns a list of length 2 (if fit_save = FALSE) or 3 (if fit_save = TRUE). The elements of the list are: a list of lavaan model output objects; a list of parameter estimates from the models (standardized if std = TRUE); and, if fit_save = TRUE, a matrix of fit measures for each model.

Examples

# Create CFA keys
keys0 <- c("grit_c", "grit_p", "hope_a", "hope_p")
keys <- sapply(
  keys0, function(x) names(BFIGritHope)[grep(x, names(BFIGritHope))]
)
# Create model code
mods <- mapply(
  x = keys, y = names(keys), SIMPLIFY = FALSE,
  FUN = function(x, y) paste(y, "=~", paste(x, collapse = " + "))
)
# Edit model code to add correlated residuals
mods[[1]] <- paste0(mods[[1]], "\ngrit_c_1 ~~ grit_c_2")
# Estimate the models with sem.check()
cfa_fit <- sem.check(mods, BFIGritHope, keys, name = "cfa", check = FALSE)

semFromKeys documentation built on July 24, 2026, 5:07 p.m.