% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/disaggregate_statespace.R
\name{disaggregate_statespace}
\alias{disaggregate_statespace}
\title{Evidence-based Bayesian disaggregation (state-space; canonical engine)}
\usage{
disaggregate_statespace(
  cpi,
  W,
  years = NULL,
  industries = NULL,
  student_obs = TRUE,
  priors = NULL,
  chains = 4L,
  iter = 2000L,
  warmup = 1000L,
  thin = 1L,
  cores = NULL,
  adapt_delta = 0.95,
  max_treedepth = 12L,
  seed = 1234L,
  init = 0.5,
  keep_fit = TRUE,
  verbose = FALSE
)
}
\arguments{
\item{cpi}{Numeric vector (length \eqn{T}); the observed aggregate index in
levels (e.g. CPI re-indexed to a common base). Strictly positive.}

\item{W}{Numeric matrix (\eqn{T \times K}); the (known) VAB aggregation
weights, rows summing to 1 (small deviations are renormalized). Sector
columns must align with the desired output ordering.}

\item{years}{Optional integer vector (length \eqn{T}); period labels.}

\item{industries}{Optional character vector (length \eqn{K}); sector labels.
Defaults to \code{colnames(W)} when present.}

\item{student_obs}{Logical; if \code{TRUE} (default) the observation is
Student-t (robust to aggregate outliers), otherwise Gaussian.}

\item{priors}{Optional named list overriding \code{\link{disagg_default_priors}}.}

\item{chains, iter, warmup, thin}{Sampler controls (HMC/NUTS). Defaults
\code{4 / 2000 / 1000 / 1}.}

\item{cores}{Integer; parallel chains. Default \code{min(chains, detectCores())}.}

\item{adapt_delta, max_treedepth}{NUTS tuning. Defaults \code{0.95 / 12}.}

\item{seed}{Integer RNG seed. Default \code{1234}.}

\item{init}{Sampler init; a numeric scalar is an init radius (cmdstanr) or is
translated to \code{init_r} (rstan). Default \code{0.5}.}

\item{keep_fit}{Logical; keep the raw Stan fit object in the result. Default
\code{TRUE} (needed to draw further quantities or run LOO).}

\item{verbose}{Logical; print progress. Default \code{FALSE}.}
}
\value{
An object of class \code{"disagg_statespace"}: a list with
  \describe{
    \item{phi_draws}{\code{[T, K, draws]} numeric array of posterior draws of
      \eqn{\varphi} (the multiple-imputation input for the nested OU).}
    \item{phi_summary}{List of \eqn{T \times K} matrices \code{median},
      \code{q2.5}, \code{q97.5} (credible bands per sector and period).}
    \item{agg_summary}{\eqn{T \times 3} matrix: posterior median and 95\% band
      of the fitted aggregate \eqn{\sum_k W\varphi} (against which \code{cpi}
      is the evidence).}
    \item{years, industries}{Period and sector labels.}
    \item{diagnostics}{\code{rhat_max}, \code{divergences}.}
    \item{stan_fit}{The Stan fit (if \code{keep_fit}).}
    \item{config}{Sampler/prior configuration and \code{T}, \code{K}.}
  }
}
\description{
Disaggregates an observed aggregate index (CPI) into \eqn{K} latent sectoral
price indices \eqn{\varphi_{t,k}} with a Bayesian state-space model in which
the aggregate enters as a genuine observation density (not a renormalization
identity). The model couples a random-walk-with-drift transition in
\eqn{\log\varphi} (partial pooling on the drift and the innovation scale), an
estimable cross-sectional concentration, and a Student-t (or Gaussian)
observation \eqn{cpi_t \mid \varphi \sim \mathrm{Student\text{-}t}(\nu,
\sum_k W_{t,k}\varphi_{t,k}, \sigma)}. See \code{vignette("evidence-based-disaggregation")}.
}
\details{
The returned posterior draws of \eqn{\varphi} (a \code{[T, K, draws]} array)
are exactly the multiple-imputation input consumed by
\code{bayesianOU::fit_ou_nested_mi()}, propagating the disaggregation
uncertainty into the downstream nested-OU analysis (Rubin's rule).
}
\examples{
\dontrun{
set.seed(1)
sim <- simulate_disagg(T = 30, K = 4)
fit <- disaggregate_statespace(sim$cpi, sim$W, chains = 2, iter = 800)
dim(fit$phi_draws)            # T x K x draws
}
}
\seealso{
\code{\link{disaggregate_conjugate}} (closed-form Bayesian baseline),
  \code{\link{disaggregate_from_files}}, \code{\link{simulate_disagg}}.
}
