% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cache.setup.R
\name{cache.setup}
\alias{cache.setup}
\title{Sets up a cache directory for storing model inputs and outputs}
\usage{
cache.setup(location = "user", interactive = TRUE)
}
\arguments{
\item{location}{The cache location to save model objects to to enable checking.
If \code{location = "user"} (default, recommended if unsure),
then the system's default cache location is used.
If any other string is used a folder will be created within either the
\code{\link[=getwd]{getwd()}} directory or,
if available, within the directory identified by \code{\link[here:here]{here::here()}}.
If using an RStudio project, these will create the directory in the
project directory.}

\item{interactive}{Logical.
\code{TRUE} indicates that confirmation will be required before a cache directory
is set \emph{if} the default location is not used.
\code{FALSE} indicates that a cache directory will be set without confirmation.
Irrelevant if \code{location = "user"}.
It is recommended to use \code{TRUE}.
Defaults to \code{TRUE}.}
}
\value{
The cache directory path (invisibly).
Primarily called to set up the cache configuration.
}
\description{
Using \code{save_out = TRUE} or \code{check = TRUE} from
\code{\link[=cfa.from.keys]{cfa.from.keys()}}, \code{\link[=bifactor.from.keys]{bifactor.from.keys()}}, \code{\link[=efa.from.keys]{efa.from.keys()}}, or
\code{\link[=esem.from.mods]{esem.from.mods()}} requires a cache directory to save model objects to or
to check against.
By default, \code{cache.setup} uses the system's default cache location,
otherwise a location within the current working directory or project can be
selected.
The function needs to be run once after the environment is cleared whenever
a cache directory is required.
}
\details{
Saving outputs to save time running identical models more than once requires
files to be saved on your computer.
To avoid writing to your computer without your permission,
you are required to run this function first to ensure that you know \emph{that}
files are being saved and \emph{where} files are being saved.
The function temporarily sets a hidden environment variable '.cache_env'
(with, if empty,
\code{assign(".cache_env", new.env(parent = emptyenv()), envir = parent.frame(1))}
and with
\code{assign("cache_dir", cache_dir, envir = get(".cache_env", envir = parent.frame(1)))},
if not), which will be removed whenever the environment is cleared.

By default, the function creates the cache directory in the standard place
for the operating system being used, appended by \verb{semFromKeys/[projectname]},
if a project is being used and the \code{rstudioapi} is available.
If a project is not being used or the \code{rstudioapi} package is not available,
then the relative path with be \code{semFromKeys}.

In the later case, if two function calls include the same \code{name} assignment,
then outputs from one will overwrite the other. Therefore, it is recommended
to either set the cache directory to something other than the default or use
the default within a project with the \code{rstudioapi} package installed.
Obviously this latter option will likely not work outside of RStudio,
so, in that case, it is recommended to use a custom location.

To ensure that R knows what the cache directory is,
a hidden environment variable containing the information---\code{.cache_env}---is
saved within the working environment.
Other functions from the package will look for and use \code{.cache_env} to
identify the cache directory.
As a result, whenever the working environment is cleared
(e.g., upon closing RStudio) or whenever the \code{.cache_env} is otherwise
removed,
the \code{cache.setup} function will need to be re-run before the cache
functionality will work,
regardless of the status of the any recently used cache directories.

The function relies on code that was unavailable in versions of R prior to
version 4.0,
so anyone using an earlier version of R will either have to update R or forgo
the caching functionality.

\code{semFromKeys} has no way to know what directories you have specified as the
cache in the past and cannot clean up unknown former cache directories.
Therefore, it is recommended that you use either the default location or
the same location for all models within the same project.
Either of these will enable easy detection, so that unneeded cached files
can be found and deleted.

Functions that directly or indirectly might require a cache directory are:
\code{\link[=cfa.from.keys]{cfa.from.keys()}}, \code{\link[=bifactor.from.keys]{bifactor.from.keys()}}, \code{\link[=efa.from.keys]{efa.from.keys()}},
\code{\link[=esem.from.mods]{esem.from.mods()}}, and \code{\link[=sem.check]{sem.check()}}.
}
\examples{
\dontrun{
  # Setup a cache directory
  cache.setup()
  # Now code with check = TRUE or save_out = TRUE will work, e.g.,
  # 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, fit_save = TRUE, check = TRUE, save_out = TRUE
  )
  # Check that models are not run again.
  cfa_fit <- cfa.from.keys(
    keys, BFIGritHope, fit_save = TRUE, check = TRUE, save_out = TRUE
  )
}
}
\seealso{
\code{\link[=cfa.from.keys]{cfa.from.keys()}}, \code{\link[=bifactor.from.keys]{bifactor.from.keys()}}, \code{\link[=efa.from.keys]{efa.from.keys()}},
\code{\link[=esem.from.mods]{esem.from.mods()}}, and \code{\link[=sem.check]{sem.check()}} for dependent functions;
\code{\link[tools:R_user_dir]{tools::R_user_dir()}} for default cache directories;
\code{\link[here:here]{here::here()}} for project-based cache directory setting; and
\code{\link[=cache.clean]{cache.clean()}} for a function to clean cache.
}
