% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/wrapper_fa.R
\name{rtmb_fa}
\alias{rtmb_fa}
\title{RTMB-based Factor Analysis Wrapper}
\usage{
rtmb_fa(
  data,
  nfactors = 1,
  rotate = NULL,
  score = FALSE,
  prior = prior_flat(),
  y_range = NULL,
  init = NULL,
  fixed = NULL,
  missing = c("listwise", "fiml"),
  WAIC = FALSE
)
}
\arguments{
\item{data}{Observation data frame or matrix (N x J).}

\item{nfactors}{Number of factors (K).}

\item{rotate}{String specifying the rotation method (e.g., "varimax", "promax", "ssp"). If NULL, no rotation is applied. Specifying "ssp" performs regularized factor analysis.}

\item{score}{Logical; if TRUE, factor scores are calculated in the generate block (default is FALSE).}

\item{prior}{Prior configuration: `prior_flat()`, `prior_normal()`, or `prior_weak()`.
Hyperparameters can be specified within these functions (e.g., `prior_normal(mean_sd = 10, sd_rate = 10)`).
Available parameters for FA: `mean_sd`, `sd_rate`, `loadings_sd`, and `ssp_ratio` (if `rotate = "ssp"`).}

\item{y_range}{A numeric vector of length 2 specifying the theoretical min and max values of the items.
Used to construct weakly informative priors when `prior = prior_weak()`.}

\item{init}{List of initial values.}

\item{fixed}{A named list of parameter values to fix (optional).}

\item{missing}{Missing value handling strategy: "listwise" (default) or "fiml" (Full Information Maximum Likelihood).}

\item{WAIC}{Logical; if TRUE, add pointwise `log_lik` to the generate block for WAIC.}
}
\description{
Performs exploratory factor analysis (EFA) using RTMB. It supports standard
rotation methods (e.g., varimax, promax) as well as regularized factor analysis
using a Spike-and-Slab Prior (SSP) for estimating sparse loading matrices.
}
\examples{

  # Prepare a subset of the BigFive dataset for factor analysis
  data(BigFive, package = "BayesRTMB")
  fa_data <- BigFive[, 1:10]

  # --- 1. Standard Exploratory Factor Analysis (1 Factor) ---
  fit_fa1 <- rtmb_fa(data = fa_data, nfactors = 1)

  # Maximum A Posteriori (MAP) estimation
  map_fa1 <- fit_fa1$optimize()
  map_fa1$summary()



  # --- 2. Factor Analysis with Rotation and Factor Scores (2 Factors) ---
  # Extract 2 factors, apply Promax rotation during model fitting, and calculate factor scores
  fit_fa2 <- rtmb_fa(data = fa_data, nfactors = 2, rotate = "promax", score = TRUE)

  # Setting se_method = "sampling" enables standard errors and 95\% CIs
  # for transformed and generated quantities, such as factor scores and post-hoc rotations.
  # (It uses multivariate normal sampling from the unconstrained parameter space)
  map_fa2 <- fit_fa2$optimize(se_method = "sampling")
  map_fa2$summary()

  # Post-hoc rotation using the fa_rotate() method
  # You can also apply other rotation methods (e.g., "varimax" from the stats package)
  # to the unrotated loading matrix ("L") after estimation.
  map_fa2$fa_rotate(target = "L", rotate = "varimax")

  # The post-hoc rotated loadings are automatically stored with the method's
  # suffix (e.g., "L_varimax")
  map_fa2$summary("L_varimax")



  # --- 3. Regularized Factor Analysis using Spike-and-Slab Prior (SSP) ---
  # Specifying 'rotate = "ssp"' enables sparse loading matrix estimation
  fit_ssp <- rtmb_fa(data = fa_data, nfactors = 2, rotate = "ssp")

  map_ssp <- fit_ssp$optimize()
  map_ssp$summary()
}
