% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/define_factor_model.R
\name{define_factor_model}
\alias{define_factor_model}
\title{Define latent factor model structure}
\usage{
define_factor_model(
  n_factors,
  n_types = 1,
  factor_structure = "independent",
  n_mixtures = 1,
  factor_covariates = NULL,
  se_covariates = NULL
)
}
\arguments{
\item{n_factors}{Integer. Number of latent factors (>=0). Use 0 for models without latent factors.}

\item{n_types}{Integer. Number of types (>=1)}

\item{factor_structure}{Character. Structure of factor dependencies. Options:
\itemize{
\item \code{"independent"} (default): Factors are independent
\item \code{"correlation"}: Correlated factors via Cholesky decomposition (2 factors only)
\item \code{"SE_linear"}: Structural equation f_k = alpha + alpha_1*f_1 + ... + epsilon
\item \code{"SE_quadratic"}: Adds quadratic terms: f_k = alpha + alpha_1\emph{f_1 + alpha_q1}f_1^2 + ... + epsilon
}}

\item{n_mixtures}{Integer. Number of discrete mixtures (default = 1, allowed: 1-3)}

\item{factor_covariates}{Character vector. Names of covariates that shift factor means.
When specified, the factor distribution becomes f_i ~ N((X_i - mean(X)) * gamma, Sigma)
where X_i is the covariate vector for observation i and gamma is a matrix of coefficients
(one column per factor). This allows factor means to vary by observed characteristics.
The covariates must be present in the data passed to \code{estimate_model_rcpp()}.
\strong{Note:} All covariates are automatically demeaned internally to ensure the overall
factor mean is zero (required for identification). Including an intercept/constant
has no effect since it becomes zero after demeaning.
For SE_linear/SE_quadratic structures, covariates only affect input factor means
(not the outcome factor which is determined by the structural equation).}

\item{se_covariates}{Character vector. Names of covariates that directly affect the
outcome factor in SE_linear/SE_quadratic models. When specified, the structural
equation becomes f_k = intercept + sum(alpha_j * f_j) + sum(beta_m * X_m) + epsilon.
Only valid for factor_structure = "SE_linear" or "SE_quadratic".
All covariates are automatically demeaned internally for identification.}
}
\value{
An object of class "factor_model"
}
\description{
Creates an object of class \code{"factor_model"} that specifies the structure of the
unobserved latent factors. This includes the number of factors and mixture components.
Loading constraints are specified at the component level via \code{define_model_component()}.
Numerical integration settings (quadrature points) are specified in \code{define_estimation_control()}.
}
\examples{
# Single factor model
fm <- define_factor_model(n_factors = 1)

# Two-factor structural equation model
fm_se <- define_factor_model(n_factors = 2, factor_structure = "SE_linear")
}
