% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fit-sem.R
\name{dcvar_sem}
\alias{dcvar_sem}
\title{Fit an experimental SEM copula VAR(1) model}
\usage{
dcvar_sem(
  data,
  indicators,
  J = NULL,
  lambda = NULL,
  sigma_e = NULL,
  margins = "normal",
  skew_direction = NULL,
  time_var = "time",
  method = c("indicator", "naive"),
  prior_mu_sd = 0.25,
  prior_phi_sd = 0.5,
  prior_sigma_sd = 0.5,
  prior_rho_sd = 0.75,
  chains = 4,
  iter_warmup = 2000,
  iter_sampling = 4000,
  adapt_delta = 0.95,
  max_treedepth = 13,
  seed = NULL,
  cores = NULL,
  refresh = 500,
  init = NULL,
  stan_file = NULL,
  backend = getOption("dcvar.backend", "auto"),
  ...
)
}
\arguments{
\item{data}{A data frame with time series of indicator variables.}

\item{indicators}{A list of two character vectors, each naming J indicator
columns per latent variable. For example:
\code{list(PA = c("y1_1", "y1_2", "y1_3"), NA_ = c("y2_1", "y2_2", "y2_3"))}.}

\item{J}{Number of indicators per latent variable. If \code{method = "naive"}
and \code{J} is \code{NULL}, it is inferred from \code{indicators}.}

\item{lambda}{Numeric vector of length J with fixed factor loadings.
Required when \code{method = "indicator"}.}

\item{sigma_e}{Fixed measurement error SD (scalar). Required when
\code{method = "indicator"}.}

\item{margins}{Character string specifying the latent innovation margin.
One of \code{"normal"} (default) or \code{"exponential"}.}

\item{skew_direction}{Integer vector of length 2 indicating skew direction
for exponential margins. Each element must be \code{1} (right-skewed) or \code{-1}
(left-skewed). Required when \code{margins = "exponential"}.}

\item{time_var}{Name of the time column (default: \code{"time"}).}

\item{method}{Character string: \code{"indicator"} (default) fits the fixed
measurement model; \code{"naive"} averages indicators within each latent block
and fits the observed score VAR.}

\item{prior_mu_sd}{Prior SD for intercepts: \code{mu ~ normal(0, prior_mu_sd)}.}

\item{prior_phi_sd}{Prior SD for VAR coefficients:
\code{phi ~ normal(0, prior_phi_sd)}.}

\item{prior_sigma_sd}{Prior SD for the lognormal prior on the latent
innovation scale parameter. For normal margins this is applied to
\code{sigma}; for exponential margins it is applied to \code{sigma_exp}.}

\item{prior_rho_sd}{Prior SD for rho_raw:
\code{rho_raw ~ normal(0, prior_rho_sd)}, with \code{rho = 0.97 * tanh(rho_raw)}.}

\item{chains}{Number of MCMC chains.}

\item{iter_warmup}{Warmup iterations per chain.}

\item{iter_sampling}{Sampling iterations per chain.}

\item{adapt_delta}{Target acceptance rate.}

\item{max_treedepth}{Maximum tree depth.}

\item{seed}{Random seed.}

\item{cores}{Number of parallel chains.}

\item{refresh}{How often to print progress.}

\item{init}{Custom init function or \code{NULL}.}

\item{stan_file}{Custom Stan file path or \code{NULL}.}

\item{backend}{Character: \code{"auto"} (default, uses rstan), \code{"rstan"}, or
\code{"cmdstanr"}. Can also be set globally via
\code{options(dcvar.backend = "cmdstanr")}.}

\item{...}{Additional backend-specific sampling arguments.}
}
\value{
A \code{dcvar_sem_fit} object.
}
\description{
Fits a copula VAR(1) model with a fixed measurement model (factor
loadings and measurement error SD are not estimated). Latent innovations
are treated as parameters, making this model computationally intensive
for large T.
}
\details{
\strong{Experimental extension.} This SEM variant supports \code{fitted()} and
\code{predict()}. PSIS-LOO is available for naive score fits. PIT diagnostics are
not yet implemented.

\strong{Boundary constraints.} The SEM model constrains each VAR coefficient
(Phi) to the interval \eqn{[-0.99, 0.99]}, unlike other dcvar models
where Phi is unconstrained. Very strong autoregressive or cross-lag
dynamics near \eqn{\pm 1} cannot be captured by this variant.

The copula correlation \eqn{\rho} is constrained to \eqn{(-0.97, 0.97)}
via \code{rho = 0.97 * tanh(rho_raw)} to avoid boundary singularity in the
Gaussian copula density. Extremely high correlations near \eqn{\pm 1}
are truncated.

\strong{Margins.} The SEM model currently supports normal and exponential latent
innovation margins. Exponential margins use the same shifted-exponential
parameterization as the single-level models and therefore require
\code{skew_direction}. Other non-normal margins are not yet available.

\strong{Post-estimation.} \code{fitted()} and \code{predict()} are available for both the
latent-state scale (\code{type = "link"}) and the observed-indicator scale
(\code{type = "response"}). Use \code{\link[=latent_states]{latent_states()}} when you specifically need the
full posterior summaries of the latent trajectories.
}
\note{
This model currently supports normal and exponential latent margins.
For skew-normal or gamma margins, use \code{\link[=dcvar]{dcvar()}}, \code{\link[=dcvar_constant]{dcvar_constant()}}, or
\code{\link[=dcvar_hmm]{dcvar_hmm()}}.
}
\seealso{
\code{\link[=latent_states]{latent_states()}} for extracting estimated latent states,
\code{\link[=simulate_dcvar_sem]{simulate_dcvar_sem()}} for data generation.
}
