% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/analyze.R
\name{extract_survey_factors}
\alias{extract_survey_factors}
\title{Extract Survey Factors}
\usage{
extract_survey_factors(
  survey,
  n_factors = NULL,
  rotation = "oblimin",
  min_loading = 0.3,
  fm = "minres",
  plot = FALSE
)
}
\arguments{
\item{survey}{A glint_survey object or data frame containing survey data}

\item{n_factors}{Integer indicating the number of factors to extract. If NULL
(default), will use parallel analysis to determine optimal number of factors}

\item{rotation}{Character string indicating rotation method: "oblimin" (default),
"varimax", "promax", "quartimax", "equamax", or "none"}

\item{min_loading}{Minimum factor loading to display in results (default: 0.3)}

\item{fm}{Character string indicating factoring method: "minres" (minimum
residuals, default), "ml" (maximum likelihood), "pa" (principal axis),
"wls" (weighted least squares), "gls" (generalized least squares), or
"uls" (unweighted least squares)}

\item{plot}{Logical. If \code{TRUE}, prints a factor loading heatmap and
returns the result list invisibly. Requires \pkg{ggplot2}. Default:
\code{FALSE}.}
}
\value{
A list containing:
\describe{
\item{factor_summary}{A tibble with one row per question-factor combination
(filtered to \code{abs(loading) >= min_loading}), containing:
\code{question} (item text), \code{factor} (factor name),
\code{loading} (loading coefficient), \code{loading_label}
("Strong" >= 0.75 / "Medium" 0.60-0.74 / "Weak" < 0.60),
\code{communality} (proportion of item variance explained by all factors),
and \code{factor_variance_pct} (percentage of total variance explained
by this factor). Sorted by factor then descending loading strength.}
\item{fa_object}{Original fa object from psych package for further analysis}
}
When \code{plot = TRUE}, the same list is returned invisibly after printing
the plot.
}
\description{
Performs factor analysis on survey question responses to identify underlying
latent factors. Supports multiple rotation methods with oblique rotation as default.
}
\examples{
survey_path <- system.file("extdata", "survey_export.csv", package = "vivaglint")
survey <- read_glint_survey(survey_path, emp_id_col = "EMP ID")

if (requireNamespace("psych", quietly = TRUE)) {
  # Extract factors with fixed count to keep runtime small
  factors <- extract_survey_factors(survey, n_factors = 1)
  print(factors$factor_summary)

  # Filter to strong loaders only
  strong <- dplyr::filter(factors$factor_summary, loading_label == "Strong")

  # With factor loading heatmap
  if (requireNamespace("ggplot2", quietly = TRUE)) {
    extract_survey_factors(survey, n_factors = 1, plot = TRUE)
  }
}
}
