% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/FFBS-DYNBPS-v2.R
\name{spFFBS}
\alias{spFFBS}
\title{spFFBS: Spatiotemporal Bayesian Pipeline (optimised)}
\usage{
spFFBS(
  Y,
  X,
  D,
  grid = list(tau = NULL, phi = NULL),
  prior,
  G_beta = NULL,
  rho = 1,
  do_BS = FALSE,
  do_forecast = FALSE,
  do_spatial = FALSE,
  L = 200L,
  tnew = NULL,
  X_all = NULL,
  spatial = NULL,
  n_threads = 1L,
  verbose = TRUE
)
}
\arguments{
\item{Y}{Response array, n x q x T.}

\item{X}{Covariate array, n x p x T. Replaces \code{P}.}

\item{D}{n x n spatial distance matrix.}

\item{grid}{List with elements \code{tau} and \code{phi} (numeric vectors).}

\item{prior}{Block-form prior list; see \code{\link{make_prior}}.
Elements: \code{m} ((p+n)xq), \code{C_bb} (pxp), \code{C_bw} (pxn),
\code{C_ww} (nxn), \code{nu} (scalar), \code{Psi} (qxq).
If the old-style full \code{C} is supplied instead of \code{C_bb/C_bw/C_ww},
the wrapper auto-converts using \code{make_prior()}.}

\item{G_beta}{pxp upper-left block of the system matrix G.
Default \code{NULL} = identity.}

\item{rho}{Scalar multiplier for the lower-right nxn identity block of G.
Default 1.}

\item{do_BS}{Logical; run backward sampling? Default FALSE.}

\item{do_forecast}{Logical; run temporal forecast? Default FALSE.}

\item{do_spatial}{Logical; run spatial interpolation? Default FALSE.}

\item{L}{Number of posterior samples. Default 200.}

\item{tnew}{Forecast horizon (required when \code{do_forecast = TRUE}).}

\item{X_all}{nxpx(T+tnew) covariate array for forecasting (required when
\code{do_forecast = TRUE}).}

\item{spatial}{List for spatial interpolation:
\code{list(crd, crdtilde, Xtilde, t)}.
\code{Xtilde} should be a uxp matrix (covariates at prediction sites).}

\item{n_threads}{Number of OpenMP threads. Default 1.}

\item{verbose}{Logical; print progress? Default TRUE.}
}
\value{
A list with (depending on flags):
\describe{
\item{\code{FF}}{Forward filter output from \code{spFF3_v2}.}
\item{\code{Wi}}{nxJ dynamic weight matrix.}
\item{\code{Wglobal}}{Jx1 global (averaged) weight vector.}
\item{\code{BS}}{(if \code{do_BS}) T-list of nxqxL sample cubes.}
\item{\code{forecast}}{(if \code{do_forecast}) List with \code{Y_pred}
array of dimensions nxqxLxT.}
\item{\code{spatial}}{(if \code{do_spatial}) Named list of L-lists of
prediction matrices, one per requested time.}
}
}
\description{
Optimised wrapper for the spFFBS v2 C++ backend. Runs forward
filtering, dynamic stacking weight computation, and optionally backward
sampling, temporal forecasting, and spatial interpolation.
}
\section{Differences from \code{spFFBS} (v1)}{

\itemize{
\item \code{G} is now a \emph{pxp matrix} (\code{G_beta}) plus a scalar
\code{rho}, representing the block-diagonal system matrix
\eqn{G = \mathrm{diag}(G_{\beta},\, \rho I_n)}.
Defaults to the identity (\code{G_beta = NULL, rho = 1}).
\item \code{X} (nxpxT array of covariates) replaces the \code{P} cube.
The observation matrix \eqn{P_t = [X_t \mid I_n]} is formed implicitly
inside C++.
\item \code{prior} should be in block form; use \code{make_prior()}
to convert a full \eqn{C_0} matrix if needed.
}
}

\examples{
\donttest{
set.seed(42)
n <- 50; T <- 10; p <- 2; q <- 2

coords <- matrix(runif(n * 2), ncol = 2)
D      <- as.matrix(dist(coords))
Y      <- array(rnorm(n * q * T), dim = c(n, q, T))
X      <- array(rnorm(n * p * T), dim = c(n, p, T))

prior  <- make_prior(
  m0   = matrix(0, n + p, q),
  C0   = diag(n + p),
  nu0  = 3,
  Psi0 = diag(q),
  p    = p
)

res <- spFFBS(
  Y = Y, X = X, D = D,
  grid  = list(tau = c(0.8, 0.9), phi = c(1, 2)),
  prior = prior,
  L = 50
)
}

}
