% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/define_dynamic_measurement.R
\name{define_dynamic_measurement}
\alias{define_dynamic_measurement}
\title{Define a dynamic measurement system for longitudinal factor models}
\usage{
define_dynamic_measurement(
  data,
  items,
  period_prefixes,
  model_type = "linear",
  n_categories = NULL,
  covariates = "intercept",
  evaluation_indicator = NULL
)
}
\arguments{
\item{data}{Wide-format data frame. Must contain a column named
\code{paste0(prefix, item)} for every combination of
\code{period_prefixes} and \code{items}, plus any columns named in
\code{covariates} and \code{evaluation_indicator}.}

\item{items}{Character vector of item names (e.g.,
\code{c("m1", "m2", "m3")}).}

\item{period_prefixes}{Character vector of column prefixes, one per
period. Column names are assembled as \code{paste0(prefix, item)}.
E.g., \code{c("Y_t1_", "Y_t2_")} yields data columns \code{"Y_t1_m1"},
\code{"Y_t2_m1"}, etc. Length of \code{period_prefixes} determines
the number of latent factors in Stage 1 (one per period).}

\item{model_type}{One of \code{"linear"}, \code{"oprobit"},
\code{"probit"}, \code{"logit"}. The same type is used for every
item and every period.}

\item{n_categories}{Required for \code{model_type = "oprobit"}; the
number of ordered categories (shared across items and periods).}

\item{covariates}{Character vector of covariate column names; default
\code{"intercept"}. Same covariates for every component.}

\item{evaluation_indicator}{Name of a column with 0/1 values
indicating which observations contribute to each component's
likelihood; \code{NULL} to use all rows.}
}
\value{
An object of class \code{"dynamic_measurement"}: a list with
\itemize{
\item \code{model_system}: a \code{model_system} object ready to
pass to \code{\link{estimate_model_rcpp}}.
\item \code{factor_model}: the underlying \code{factor_model}.
\item \code{items}, \code{period_prefixes}, \code{model_type},
\code{n_categories}, \code{covariates},
\code{evaluation_indicator}: the inputs, kept for use by
\code{\link{build_dynamic_previous_stage}}.
}
}
\description{
Builds a Stage 1 measurement model for a single latent construct
observed at two or more time points. Measurement invariance is imposed
on loadings and residual sigmas (tied across periods via
\code{equality_constraints}), while measurement intercepts are left
period-specific. This is the recommended Stage 1 setup for an SE_linear
or SE_quadratic structural model in the second stage.
}
\details{
Why period-specific intercepts? Under the usual factor-model
identification convention \code{E[f_k] = 0} for every factor \code{k},
pooling measurement intercepts across periods biases them by
\eqn{\lambda_m \cdot E[f_2]/2} when the period-mean drifts between
waves, an artefact that propagates into an under-estimate of
\code{se_intercept} in Stage 2. Leaving the intercepts period-specific
and carrying the wave-1 intercepts into Stage 2 (via
\code{\link{build_dynamic_previous_stage}}) sidesteps the bias.
}
\examples{
\donttest{
# Simulate a simple dynamic single-factor model
set.seed(1); n <- 500
f1 <- rnorm(n); eps <- rnorm(n, 0, sqrt(0.5))
f2 <- 0.4 + 0.6 * f1 + eps
dat <- data.frame(
  intercept = 1, eval = 1L,
  Y_t1_m1 = 1.5 + f1 + rnorm(n, 0, 0.7),
  Y_t1_m2 = 1.0 + 0.9 * f1 + rnorm(n, 0, 0.75),
  Y_t1_m3 = 0.8 + 1.1 * f1 + rnorm(n, 0, 0.65),
  Y_t2_m1 = 1.5 + f2 + rnorm(n, 0, 0.7),
  Y_t2_m2 = 1.0 + 0.9 * f2 + rnorm(n, 0, 0.75),
  Y_t2_m3 = 0.8 + 1.1 * f2 + rnorm(n, 0, 0.65)
)
dyn <- define_dynamic_measurement(
  data = dat, items = c("m1", "m2", "m3"),
  period_prefixes = c("Y_t1_", "Y_t2_"),
  model_type = "linear", evaluation_indicator = "eval"
)
ctrl <- define_estimation_control(n_quad_points = 8, num_cores = 1)
s1 <- estimate_model_rcpp(dyn$model_system, dat, control = ctrl,
                          optimizer = "nlminb", parallel = FALSE,
                          verbose = FALSE)
prev <- build_dynamic_previous_stage(dyn, s1, dat)   # Stage 2 input
}
}
\seealso{
\code{\link{build_dynamic_previous_stage}} constructs the
Stage 2 \code{previous_stage} object from the Stage 1 estimation
result.
}
