% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/control.R
\name{estimate_control}
\alias{estimate_control}
\alias{rotate_control}
\title{Control objects for estimation and rotation settings}
\usage{
estimate_control(
  type = c("EFAtools", "psych", "SPSS", "none"),
  init_comm = NA,
  criterion = NA,
  criterion_type = NA,
  max_iter = NA,
  abs_eigen = NA,
  start_method = "psych",
  fiml_max_iter = 500,
  fiml_tol = 1e-05
)

rotate_control(
  type = c("EFAtools", "psych", "SPSS", "none"),
  normalize = TRUE,
  precision = 1e-05,
  order_type = NA,
  varimax_type = NA,
  p_type = NA,
  k = NA,
  random_starts = 100,
  ...
)
}
\arguments{
\item{type}{character. One of \code{"EFAtools"} (default), \code{"psych"}, \code{"SPSS"}, or
\code{"none"}. Selects the preset that fills the \code{NA}-defaulted knobs below when the
control is used to fit a model.}

\item{init_comm}{character. Method for the initial communalities in principal
axis factoring: \code{"smc"} (squared multiple correlations), \code{"mac"} (maximum
absolute correlations), or \code{"unity"}. \code{NA} (default) resolves from \code{type}.}

\item{criterion}{numeric. The convergence criterion for principal axis
factoring: iteration stops once the change in communalities falls below it. A
single number greater than 0 and smaller than 1; \code{NA} (default) resolves from \code{type}.}

\item{criterion_type}{character. The convergence criterion type for principal
axis factoring: \code{"max_individual"} (the largest change in any communality, as
in SPSS) or \code{"sum"} (the change in the summed communalities, as in
\code{\link[psych:fa]{psych::fa()}}). \code{NA} (default) resolves from \code{type}.}

\item{max_iter}{numeric. The maximum number of principal-axis-factoring
iterations before the procedure is halted with a warning. A single whole
number of at least 1; \code{NA} (default) resolves from \code{type}.}

\item{abs_eigen}{logical. Which algorithm the principal-axis-factoring
iterations use: \code{FALSE} computes the loadings from the eigenvalues (as in
\code{\link[psych:fa]{psych::fa()}}); \code{TRUE} uses the absolute eigenvalues (as in SPSS). \code{NA}
(default) resolves from \code{type}.}

\item{start_method}{character. Starting values for the maximum-likelihood
optimiser: \code{"psych"} (default, the \code{\link[psych:fa]{psych::fa()}} starts) or \code{"factanal"} (the
\code{\link[stats:factanal]{stats::factanal()}} starts); abbreviations are matched. Not governed by \code{type}.
Only maximum likelihood uses it, so \code{NA} leaves it unset and is rejected only by
a fit that is actually run with \code{estimator = "ML"}.}

\item{fiml_max_iter}{numeric. The maximum number of EM iterations used to estimate the
two-stage full-information maximum-likelihood moments from raw data with missing
values (\code{cor_method = "fiml"}); the last iterate is returned, with a warning, if the
cap is reached. A single whole number of at least 1; default \code{500}. Not governed by
\code{type}, and unused by every other correlation method. The EM converges linearly and
needs more iterations the larger the fraction of missing information, so raise it when
a fit reports that the moments did not converge.}

\item{fiml_tol}{numeric. The convergence tolerance of that EM: iteration stops once the
largest change in the standardized moments (the standardized means, log-variances, and
correlations) falls below it, so it does not depend on the variables' measurement
scale. A single number greater than 0 and smaller than 1 (at or above 1 the criterion is
met immediately and the starting moments would be returned as converged); default \code{1e-5}.
Not governed by \code{type}.}

\item{normalize}{logical. If \code{TRUE} (default), a Kaiser normalization is
performed before the rotation. The one knob that is always on unless you turn
it off with \code{FALSE}.}

\item{precision}{numeric. The convergence tolerance of the rotation procedure. A
single number greater than 0 and at most 1; default \code{1e-5}. Each rotation stage
monitors its own quantity, so the same number is not the same tolerance everywhere:
\code{varimax_type = "kaiser"} stops on the \emph{absolute} change in the varimax simplicity
criterion, which is an average over variables (and so does not scale with how many
there are) but rises with the number of factors, roughly toward
\code{1 - 1 / n_factors}, so a fixed value is a relatively weaker tolerance the more
factors are extracted; \code{varimax_type = "svd"} stops on the \emph{relative} change in the
singular values (as in \code{\link[stats:varimax]{stats::varimax()}}); and the criterion rotations fitted by
gradient projection stop when the \emph{projected-gradient norm} falls below it. Promax
inherits whichever of the two varimax tests its \code{varimax_type} selects, because it
rotates a varimax base.}

\item{order_type}{character. How the factors are ordered: \code{"eigen"} (by
descending sum of squared loadings, as in \code{\link[psych:fa]{psych::fa()}}) or \code{"ss_factors"} (by
descending unweighted sum of squared loadings). \code{NA} (default) resolves from
\code{type}.}

\item{varimax_type}{character. The varimax variant used (for the varimax and
promax rotations): \code{"svd"} (as in \code{\link[stats:varimax]{stats::varimax()}}) or \code{"kaiser"} (the SPSS
/ Kaiser (1958) procedure). \code{NA} (default) resolves from \code{type}.}

\item{p_type}{character. How the promax target matrix is computed: \code{"unnorm"}
(the unnormalized target of Hendrickson & White (1964), also used by psych and
stats) or \code{"norm"} (the normalized target used by SPSS). \code{NA} (default)
resolves from \code{type}.}

\item{k}{numeric. The promax power (for the target matrix) or the number of
near-zero loadings for simplimax. A single number greater than 0; \code{NA}
(default) leaves it to the fit (the \code{type}-dependent promax value, or
\code{nrow(loadings)} for simplimax). Simplimax counts loadings, so a fit using it
additionally requires a whole number no larger than the number of loadings in
the solution; promax's power has no such restriction.}

\item{random_starts}{numeric. The number of random starts used by the
criterion-based rotations to guard against local minima. A single whole number
of at least 0, where \code{0} runs the rotation from its warm start only; default
\code{100}. The default suffices for the smooth criteria; \code{simplimax} remains
materially start-dependent at it, so raise it there (see the \emph{Rotations} section
of \code{\link[=efa_fit]{efa_fit()}}).}

\item{...}{Additional arguments forwarded to the rotation engine. Only the names
a rotation engine can consume are accepted: \code{maxit} (a whole number of at least 0
bounding a \emph{single} gradient-projection optimization -- the multi-start search runs
several of them and each is bounded separately, so it is not a budget for the run as a
whole; varimax and promax have no such stage and take only \code{precision}), and the
criterion parameters \code{gam} (oblimin; \code{gam = 0} is the
recommended default, and larger values increasingly reward correlated factors and
can drive the solution toward factor collapse, so inspect \code{Phi} before interpreting
a fit with \code{gam > 0}) and \code{delta} (geomin; a positive number, default \code{0.01});
anything else is rejected as a
misspelling. They are stored in \code{extra_args} and passed on to the rotation engine
when the control is used to fit a model; an extra a given fit's rotation does not
consume is ignored by that fit, so one control can serve fits with different
rotations. An estimation knob (which belongs in \code{\link[=estimate_control]{estimate_control()}}) or one of the
former spellings \code{P_type} and \code{randomStarts} is likewise rejected here, because the
fit would silently drop it.}
}
\value{
\code{estimate_control()} returns a list of class \code{efa_estimate_control} with
the components \code{type}, \code{init_comm}, \code{criterion}, \code{criterion_type}, \code{max_iter},
\code{abs_eigen}, \code{start_method}, \code{fiml_max_iter}, and \code{fiml_tol}.
\code{rotate_control()} returns a list of class
\code{efa_rotate_control} with the components \code{type}, \code{normalize}, \code{precision},
\code{order_type}, \code{varimax_type}, \code{p_type}, \code{k}, \code{random_starts}, and \code{extra_args}
(a named list of any additional arguments forwarded to the rotation engine).
}
\description{
\code{estimate_control()} and \code{rotate_control()} collect the estimation and rotation
\emph{tuning} arguments of a factor analysis into two small, validated objects. They
are a declarative surface over the same settings resolved internally by the
package's estimation and rotation engines, so that a fit's many tuning knobs can
be prepared, inspected, and reused as a single value instead of being passed one
by one.
}
\details{
Each argument that governs a \code{type} preset defaults to \code{NA}, meaning "leave this
knob to the preset". Setting \code{type} to one of \code{"EFAtools"}, \code{"psych"}, or
\code{"SPSS"} fills those knobs from the corresponding preset when the fit is run;
setting \code{type = "none"} requires the relevant knobs to be supplied explicitly.
The control object only records the chosen \code{type} and the knobs you set: the
preset is resolved (and any "argument set alongside \code{type}" warning issued) when
the object is used to fit a model, exactly as it is today, because which preset
applies depends on the estimator and rotation.
}
\examples{
# Estimation knobs taken entirely from a preset:
estimate_control(type = "SPSS")

# A preset with one knob pinned to a non-preset value:
estimate_control(type = "EFAtools", max_iter = 500)

# Every knob supplied explicitly (type = "none"):
estimate_control(type = "none", init_comm = "smc", criterion = 1e-3,
                 criterion_type = "sum", max_iter = 300, abs_eigen = TRUE)


# Rotation knobs taken from a preset:
rotate_control(type = "psych")

# A criterion-specific extra argument, forwarded to the rotation engine:
rotate_control(type = "EFAtools", k = 3, gam = 0.5)

}
\seealso{
\code{\link[=efa_fit]{efa_fit()}}, which takes both controls; \code{\link[=efa_retain]{efa_retain()}}, the retention
criteria, and \code{\link[=efa_schmid_leiman]{efa_schmid_leiman()}}, which take an \code{estimate_control} for the
fits they run.

Other Control functions:
\code{\link{print.efa_control}}
}
\concept{Control functions}
