efa.from.keys: Runs an EFA model based on items in a keys list.
In semFromKeys: Run 'lavaan' Models from Keys Lists

View source: R/efa.from.keys.R

efa.from.keys

R Documentation

Runs an EFA model based on items in a keys list.

Description

efa.from.keys runs a exploratory factor analysis (EFA) in lavaan with a rotation targeted based on a keys list.

Usage

efa.from.keys(
  keys,
  data,
  orthogonal = FALSE,
  fit_save = TRUE,
  fit_measures = "all",
  std.lv = TRUE,
  miss = "ML",
  est = "default",
  name = "efa",
  check = FALSE,
  save_out = FALSE
)

Arguments

`keys`	A named list of keys. Names must be factor names, elements must be vectors of items that should be targeted to load on the factor.
`data`	A dataframe or object coercible to a dataframe. Data must include all observed variables in any of the keys.
`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`.
`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`.
`std.lv`	Sets the `std.lv` param, as per lavaan (see `lavaan::lavOptions()`). Defaults to `TRUE`.
`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.
`name`	A string indicating a subdirectory where model outputs will be saved when `save_out = TRUE` and checked against when `check = TRUE`. Defaults to 'efa'. Irrelevant if both `save_out = FALSE` and `check = FALSE`. 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 was designed to streamline running exploratory structural equation models (ESEM) using Burt's (1976) 2-stage procedure to prevent interpretational confounding in the context of ESEM. However, it can also be used to easily run a targeted EFA with only a keys list to avoid having to manually specify the target and model.

The function was designed for use with established multidimensional scales, such that a target is always reasonable. The function does not currently support untargeted rotations.

The model relies on sem.check() for the back-end of running the models. This enables saving inputs and outputs from model runs (with save_out = TRUE) and checking to see if anything has changed from prior runs before running again (with check = TRUE). The functionality was included for a number of very slow models or a lot of faster models, such that time spent rerunning them would be onerous. For further details on how this works, see the sem.check() function documentation.

Value

Returns a list of lists. The elements are a list of lavaan bifactor 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.

References

Burt, R. S. (1976). Interpretational confounding of unobserved variables in Structural Equation Models. Sociological Methods & Research, 5(1), 3-52. https://doi.org/10.1177/004912417600500101.

Examples

# Create EFA keys
# Using only 3 factors to save time
keys_e0 <- paste0("bfi_", c("e", "a", "c"))
# Using less than all items to save time
# (This results in a less than ideal solution but it shouldn't matter for an
# example)
keys_e <- sapply(
  keys_e0,
  function(x) {
    names(BFIGritHope)[grep(paste0(x, "\\d_[1-2]"), names(BFIGritHope))]
  },
  simplify = FALSE
)
# Run model
efa_fit <- efa.from.keys(keys_e, BFIGritHope, check = FALSE, fit_save = TRUE)
# Examine results
summary(efa_fit$fit$efa)                   # Standard lavaan summary
efa_fit$fit_measures[, c("cfi", "rmsea")]  # Fit measures

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