% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fix_factor_param.R
\name{fix_factor_param}
\alias{fix_factor_param}
\title{Fix a factor-distribution parameter at model-definition time}
\usage{
fix_factor_param(factor_model, name, value = NULL)
}
\arguments{
\item{factor_model}{A \code{factor_model} object from \code{define_factor_model()}.}

\item{name}{Either a single character string naming the factor-distribution
parameter to fix, or a character vector of names paired element-wise with
\code{value}, or a named numeric vector whose names are the parameter names
and whose values are the fixed values (in which case \code{value} must be
omitted).}

\item{value}{Numeric. The value to fix the parameter to. Pass \code{NA} to
release a previously fixed parameter (unfix). Length must match \code{name}
(length 1 is recycled).}
}
\value{
The modified \code{factor_model} object. The fix is stored in
\code{factor_model$fixed_params} as a named numeric vector.
}
\description{
Constrains a parameter in the latent-factor distribution (factor variance,
SE-equation slope / intercept / residual variance, type-probability
intercept, type-probability loading, factor-mean covariate coefficient,
or SE covariate coefficient) to a fixed value. The parameter will be held
at that value during estimation, excluded from the optimizer's free vector,
and reported in \code{result$estimates} with \code{result$std_errors == 0} and
\code{result$param_table$fixed == TRUE}.
}
\details{
Use this for substantive restrictions known at model-definition time, e.g.,
setting a \verb{type_<t>_loading_<k>} to 0 when factor \code{k} is known not to enter
the type-probability model. Estimating such a loading free can leak
identification, push the optimizer along a flat ridge, and inflate the
standard errors of the remaining type-model parameters.
}
\section{Conflicts with \code{previous_stage} / \code{free_params}}{

When \code{define_model_system(previous_stage = ..., free_params = ...)} is
used, \code{fix_factor_param()} always wins. The user-fixed value is the
binding constraint; any value for the same name in \code{previous_stage$ estimates} is ignored, and inclusion of the same name in \code{free_params}
is silently honoured (the parameter stays fixed regardless). A warning
is emitted once per conflict so accidental misuse surfaces during
debugging without spamming routine workflows.
}

\section{Auto-fixed slots}{

For SE structures, \verb{type_<t>_loading_<n_factors>} (the type loading on
the outcome factor) is auto-fixed at 0 because the type probability
model must depend only on input factors. Calling
\code{fix_factor_param(fm, "type_<t>_loading_<n_factors>", 0)} is a no-op.
Calling it with any non-zero value is an error.

When a factor variance is non-identified (no measurement component
fixes a non-zero loading on that factor), it is normally auto-fixed at
its initial value of 1. An explicit
\code{fix_factor_param(fm, "factor_var_<k>", v)} overrides the auto-fix and
uses the user-supplied value.
}

\examples{
fm <- define_factor_model(n_factors = 3, n_types = 2,
                          factor_structure = "SE_linear")

# Single fix
fm <- fix_factor_param(fm, "type_2_loading_2", 0.0)

# Batch via named numeric
fm <- fix_factor_param(fm, c(type_2_loading_2 = 0.0,
                             type_2_loading_3 = 0.0))

# Unfix
fm <- fix_factor_param(fm, "type_2_loading_2", NA_real_)

}
