% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cfa.from.keys.R
\name{cfa.from.keys}
\alias{cfa.from.keys}
\title{Runs CFA models for multiple scales based on items in a keys list.}
\usage{
cfa.from.keys(
  keys,
  data,
  fit_save = TRUE,
  fit_measures = "all",
  std.lv = TRUE,
  miss = "ML",
  est = "default",
  name = "cfa",
  check = FALSE,
  save_out = FALSE
)
}
\arguments{
\item{keys}{A named list of keys.
Names should be scale names,
elements should a list of items included in each scale.}

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

\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}{Logical.
Sets the \code{std.lv} parameter, as per lavaan (see \code{\link[lavaan:lavOptions]{lavaan::lavOptions()}}).
\code{TRUE} indicates that factor variances should be fixed to 1.
\code{FALSE} indicates that loadings of the first items of factors should be fixed
to 1.
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 'cfa'.
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 length 2 (if \code{fit_save = FALSE}) or
3 (if \code{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 \code{std = TRUE});
and, if \code{fit_save = TRUE}, a matrix of fit measures for each model.
}
\description{
\code{cfa.from.keys} runs a confirmatory factor analysis (CFA) model for each
element of a keys list. The keys list must be a named list of scales, where
each element is an item from the corresponding scale. The function is
designed to streamline running CFA models for all scales in a sample and to
input model outputs into downstream functions.
}
\details{
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.

The function does not provide any warnings for poor fit beyond those provided
by lavaan.
If any CFA models have poor fit, there is currently no capability to update
them beyond removing items by omitting them from the keys.
Any other changes to CFA models have to be made manually currently.
(Note that with \code{save_out = TRUE},
model code is saved in \verb{file.path(out_dir, name, paste0(name, _mod.rds)},
which could help with manually updating models.)
}
\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))]
)
# Run models
cfa_fit <- cfa.from.keys(keys, BFIGritHope, check = FALSE, fit_save = TRUE)
# Examine some results
summary(cfa_fit$fit$grit_c)                # Standard lavaan summary
cfa_fit$fit_measures[, c("cfi", "rmsea")]  # Fit measures
}
\seealso{
\code{\link[=sem.check]{sem.check()}}, which \code{cfa.from.keys()} uses for all the back-end, and
\code{\link[lavaan:sem]{lavaan::sem()}}, which is used to estimate the models.
}
