% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/efa.from.keys.R
\name{efa.from.keys}
\alias{efa.from.keys}
\title{Runs an EFA model based on items in 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{
\item{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.}

\item{data}{A dataframe or object coercible to a dataframe.
Data must include all observed variables in any of the keys.}

\item{orthogonal}{Logical.
Sets the \code{orthogonal} parameter, as per lavaan (see \code{\link[lavaan:lavOptions]{lavaan::lavOptions()}}).
\code{TRUE} indicates that unspecified latent variable correlations should be
fixed at 0;
\code{FALSE} indicates that unspecified latent variable correlations should be
freely estimated.
Defaults to \code{FALSE}.}

\item{fit_save}{Logical.
\code{TRUE} indicates model fit measures should be included in the output;
\code{FALSE} indicates model fit measures should not be included in the output.
\code{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,
\verb{lavaan::fitMeasures(fit$fit$[model name])}.}

\item{fit_measures}{A vector of fit measures to save or 'all' to select all fit measures,
as per the \code{fit.measures} parameter from lavaan's \code{\link[lavaan:fitMeasures]{lavaan::fitMeasures()}}
function.
Defaults to 'all'. Irrelevant if \code{fit_save = FALSE}.}

\item{std.lv}{Sets the \code{std.lv} param, as per lavaan (see \code{\link[lavaan:lavOptions]{lavaan::lavOptions()}}).
Defaults to \code{TRUE}.}

\item{miss}{A string.
Sets the \code{missing} parameter, as per lavaan (see \code{\link[lavaan:lavOptions]{lavaan::lavOptions()}}).
Defaults to 'ML'.}

\item{est}{A string.
Sets the \code{estimator} parameter, as per lavaan (see \code{\link[lavaan:lavOptions]{lavaan::lavOptions()}}).
The default ('default') uses the lavaan default for the model being run.}

\item{name}{A string indicating a subdirectory where model outputs will be saved when
\code{save_out = TRUE} and checked against when \code{check = TRUE}.
Defaults to 'efa'.
Irrelevant if both \code{save_out = FALSE} and \code{check = FALSE}.
The name should be unique for each set of models, or outputs from calls with
the same name will be overwritten.}

\item{check}{Logical.
\code{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;
\code{FALSE} indicates that these checks should not be made and the model should
be run regardless of the existence of previous inputs.}

\item{save_out}{Logical.
\code{TRUE} indicates that model code, a hash of the data, important input
parameter values, and output will be saved;
\code{FALSE} indicates that nothing will be saved.
Selecting \code{save_out = TRUE} enables the function to not rerun models next
time if \code{check = TRUE} the next time the code is run and nothing has changed
in the meantime.}
}
\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 \code{std = TRUE});
and, if \code{fit_save = TRUE}, a matrix of fit measures for each model.
}
\description{
\code{efa.from.keys} runs a exploratory factor analysis (EFA) in lavaan with a
rotation targeted based on a keys list.
}
\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 \code{\link[=sem.check]{sem.check()}} for the back-end of running the models.
This enables saving inputs and outputs from model runs
(with \code{save_out = TRUE}) and checking to see if anything has changed from
prior runs before running again (with \code{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 \code{\link[=sem.check]{sem.check()}} function
documentation.
}
\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
}
\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.
}
\seealso{
\code{\link[=sem.check]{sem.check()}}, which \code{efa.from.keys()} uses for all the back-end, and
\code{\link[lavaan:sem]{lavaan::sem()}}, which is used to estimate the models.
}
