% 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,
  tv_phi = FALSE,
  tv_sigma = FALSE,
  prior_sigma_omega_rate = 0.1,
  prior_tau_phi_rate = 0.025,
  prior_tau_sigma_rate = 0.05,
  tv_sigma_k = 8,
  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}{Latent-innovation marginal specification. A single string
applies the same family to both latent variables. A length-2 character
vector gives a per-variable (mixed) margin (for example
\code{c("normal", "gamma")}). Normal, exponential, skew-normal, and gamma
margins are supported; homogeneous skew-normal/gamma and per-variable specs
route through the generic mixed-margin Stan models under the Gaussian
copula. Applies to both the indicator and naive methods.}

\item{skew_direction}{Integer vector of length 2 of \code{1} (right-skewed) or
\code{-1} (left-skewed). Required whenever any dimension uses an
\code{"exponential"} or \code{"gamma"} margin; only those dimensions consult it.}

\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)}.
For TV SEM fits this is the prior SD for the initial Fisher-z rho.}

\item{tv_phi}{Selects which latent VAR(1) coefficients evolve as random walks
around their baseline. Either a logical scalar or a character selector as in
\code{\link[=dcvar]{dcvar()}}. Time-varying SEM currently requires \code{method = "indicator"}.}

\item{tv_sigma}{Logical; if \code{TRUE}, latent innovation scales evolve as
log-scale random walks. Time-varying SEM currently requires
\code{method = "indicator"}.}

\item{prior_sigma_omega_rate}{Prior mean for the TV SEM Fisher-z rho
random-walk SD.}

\item{prior_tau_phi_rate}{Prior mean for Phi random-walk innovation SDs.}

\item{prior_tau_sigma_rate}{Prior mean for log-scale random-walk innovation
SDs.}

\item{tv_sigma_k}{Soft-barrier sharpness for time-varying exponential/gamma
scales.}

\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. When supplied, it seeds both the Stan sampler and
the default per-chain initial values, so repeated fits are reproducible.}

\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.} SEM fits support normal, exponential, skew-normal, and gamma
latent innovation margins. Exponential and gamma margins use the same shifted
positive-support parameterization as the single-level models and therefore
require \code{skew_direction}. Homogeneous skew-normal/gamma and per-variable
margin specs route to the generic mixed-margins Stan model.

\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.
}
\seealso{
\code{\link[=latent_states]{latent_states()}} for extracting estimated latent states,
\code{\link[=simulate_dcvar_sem]{simulate_dcvar_sem()}} for data generation.
}
