% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/build-run.R
\name{build_nimble_bundle}
\alias{build_nimble_bundle}
\title{Build the explicit one-arm NIMBLE bundle}
\usage{
build_nimble_bundle(
  y,
  X = NULL,
  ps = NULL,
  backend = c("sb", "crp", "spliced"),
  kernel,
  GPD = FALSE,
  components = 10L,
  param_specs = NULL,
  mcmc = list(niter = 2000, nburnin = 500, thin = 1, nchains = 1, seed = 1),
  epsilon = 0.025,
  alpha_random = TRUE,
  monitor = c("core", "full"),
  monitor_latent = FALSE,
  monitor_v = FALSE
)
}
\arguments{
\item{y}{Numeric outcome vector.}

\item{X}{Optional design matrix/data.frame (N x p) for conditional variants.}

\item{ps}{Optional numeric vector (length N) of propensity scores. When provided,
augments the design matrix for PS-adjusted outcome modeling.}

\item{backend}{Character; the Dirichlet process representation:
\itemize{
\item \code{"sb"}: stick-breaking truncation
\item \code{"crp"}: Chinese Restaurant Process
}}

\item{kernel}{Character kernel name (must exist in \code{get_kernel_registry()}).}

\item{GPD}{Logical; whether a GPD tail is requested.}

\item{components}{Integer >= 2. Single user-facing truncation parameter:
\itemize{
\item SB: number of mixture components used in stick-breaking truncation
\item CRP: maximum number of clusters represented in the finite NIMBLE model
}}

\item{param_specs}{Optional list with entries \code{bulk} and \code{tail} to override defaults.}

\item{mcmc}{Named list of MCMC settings (niter, nburnin, thin, nchains, seed). Stored in bundle.}

\item{epsilon}{Numeric in [0,1). For downstream summaries/plots/prediction we keep the
smaller k defined by either (i) cumulative mass >= 1 - epsilon or (ii) per-component
weights >= epsilon, then renormalize.}

\item{alpha_random}{Logical; whether the DP concentration parameter \eqn{\kappa} is stochastic.}

\item{monitor}{Character monitor profile:
\itemize{
\item \code{"core"} (default): monitors only the essential model parameters
\item \code{"full"}: monitors all model nodes
}}

\item{monitor_latent}{Logical; if TRUE, include latent cluster labels (\code{z}) in monitors.}

\item{monitor_v}{Logical; if TRUE and backend is SB, include stick breaks (\code{v}) in monitors.}
}
\value{
A named list of class \code{"causalmixgpd_bundle"}. Its primary
components are \code{spec}, \code{code}, \code{constants},
\code{dimensions}, \code{data}, \code{inits}, \code{monitors}, and stored
\code{mcmc} settings.
}
\description{
\code{build_nimble_bundle()} is the detailed constructor behind
\code{\link{bundle}} for one-arm models. It compiles the modeling plan into a
self-contained object holding code-generation inputs, initialization rules,
monitor policy, and stored MCMC defaults.
}
\details{
The returned bundle encodes a finite approximation to a Dirichlet process
mixture using either a stick-breaking (\code{"sb"}) or Chinese restaurant
process / spliced (\code{"crp"} / \code{"spliced"}) representation.

For the bulk-only model, the target likelihood is the DPM predictive law
\deqn{f(y \mid x) = \sum_{k=1}^{K} w_k(x) f_k(y \mid x, \theta_k).}
When \code{GPD = TRUE}, the bundle augments the bulk model with a threshold
\eqn{u(x)} and generalized Pareto tail above that threshold, producing the
spliced predictive distribution described in the manuscript vignette.

This function intentionally stops before model compilation and sampling.
Use \code{\link{run_mcmc_bundle_manual}} or \code{\link{mcmc}} to execute the
stored model definition.

The object contains:
\itemize{
\item compiled model \code{spec}
\item \code{nimbleCode} model code
\item \code{constants}, \code{data}, explicit \code{dimensions}
\item initialization function \code{inits} (stored as a function)
\item monitor specification
\item MCMC settings list (stored but not used for code generation)
}
}
\examples{
\donttest{
y <- abs(rnorm(25)) + 0.1
bundle <- build_nimble_bundle(
  y = y,
  backend = "sb",
  kernel = "normal",
  GPD = FALSE,
  components = 3,
  mcmc = list(niter = 100, nburnin = 50, thin = 1, nchains = 1, seed = 1)
)
bundle
}
}
\seealso{
\code{\link{bundle}}, \code{\link{run_mcmc_bundle_manual}},
\code{\link{predict.mixgpd_fit}}, \code{\link{kernel_support_table}},
\code{\link{get_kernel_registry}}.
}
