% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spBPS_new.R
\name{spBPS}
\alias{spBPS}
\title{Unified spatial BPS workflow (multivariate path, works for q = 1)}
\usage{
spBPS(
  data,
  priors,
  coords,
  hyperpar,
  subset_size = 500L,
  K = NULL,
  cv_folds = 5L,
  rp = 1,
  combine_method = c("bps", "pseudoBMA"),
  draws = 0L,
  newdata = NULL,
  include_latent = FALSE,
  n_cores = 1L,
  pred_batch_size = 200L
)
}
\arguments{
\item{data}{List with matrices \code{Y} (response, n x q) and \code{X} (covariates, n x p).}

\item{priors}{List of priors for the multivariate model: \code{mu_B} (p x q mean
matrix), \code{V_r} (p x p covariance), \code{Psi} (q x q scale), \code{nu} (degrees of
freedom).}

\item{coords}{Matrix of observation coordinates (n x d).}

\item{hyperpar}{List with elements \code{alpha} and \code{phi} (vectors allowed); defines
the grid of models over which stacking weights are computed.}

\item{subset_size}{Target subset size when \code{K} is not provided. Default 500.}

\item{K}{Optional number of subsets. When \code{NULL}, computed as
\code{ceiling(nrow(Y) / subset_size)} and lower-bounded at 1.}

\item{cv_folds}{Number of folds for local cross-validation. Default 5.}

\item{rp}{Fraction of rows used when recomputing global stacking weights
(passed to \code{BPS_combine}). Ignored when \code{combine_method = "pseudoBMA"}.}

\item{combine_method}{Global combination method: Bayesian Predictive Stacking
(\code{"bps"}) or pseudo-BMA (\code{"pseudoBMA"}).}

\item{draws}{Number of posterior/predictive draws to return (0 to skip
sampling). When positive and \code{newdata} is supplied, joint posterior and
predictive draws are returned. When positive and \code{newdata} is \code{NULL},
only posterior draws (beta, sigma) are returned.}

\item{newdata}{Optional list with \code{X} (u x p) and \code{coords} (u x d) for
prediction locations. Required when \code{draws > 0} and predictions are desired.
For large \code{u}, use \code{pred_batch_size} to control memory usage.}

\item{include_latent}{Unused; kept for compatibility.}

\item{n_cores}{Number of cores for parallel computation. Controls both the
local weight estimation (parallel over K subsets) and predictive sampling.
Default 1.}

\item{pred_batch_size}{Batch size for streaming prediction. Controls the
maximum number of prediction sites processed at once, hence the peak memory
usage. Default 200. Rule of thumb: peak RAM (MB) ? batch_size x q x draws x 8 / 1e6.
Set \code{NULL} for automatic selection (min(200, u)).}
}
\value{
Object of class \code{"spBPS"} ? a list with components:
\describe{
\item{subsets}{Partition information: Y_list, X_list, crd_list.}
\item{weights_global}{K-vector of global stacking weights.}
\item{weights_local}{K-list of local stacking weight vectors.}
\item{epd}{K-list of n_k x J log-density matrices.}
\item{priors, hyperpar}{Stored for use by \code{\link{predict.spBPS}}.}
\item{timings}{Named numeric vector: fitting, combination, sampling (seconds).}
\item{posterior}{(if draws > 0) List with three-dimensional arrays:
\code{beta} (p x q x R), \code{sigma} (q x q x R), \code{model} (R).}
\item{predictive}{(if draws > 0 and newdata supplied) List with
three-dimensional arrays: \code{Wu}, \code{Yu}, \code{MY} (each u x q x R).}
}
}
\description{
Orchestrates subsetting, local stacking weight estimation, global stacking combination, and optional posterior or predictive simulation using Double Bayesian Predictive Stacking for latent spatial regression. Works for both multivariate outcomes and the univariate case via \code{q = 1}.
}
\examples{
\donttest{
n <- 1000
p <- 2
q <- 1

Y <- matrix(rnorm(n * q), ncol = q)
X <- matrix(rnorm(n * p), ncol = p)
coords <- matrix(runif(n * 2), ncol = 2)

data    <- list(Y = Y, X = X)
priors  <- list(mu_B = matrix(0, nrow = p, ncol = q),
                V_r  = diag(10, p),
                Psi  = diag(1, q),
                nu   = 3)
hyperpar <- list(alpha = 0.5, phi = 1)

res <- spBPS(data, priors, coords, hyperpar, subset_size = 200)
}

}
\seealso{
\code{\link{predict.spBPS}} for generating predictions on new data
after fitting.
}
