% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/causal.R
\name{build_causal_bundle}
\alias{build_causal_bundle}
\title{Build a causal bundle (design + two outcome arms)}
\usage{
build_causal_bundle(
  y,
  X,
  A,
  backend = c("sb", "crp", "spliced"),
  kernel,
  GPD = FALSE,
  components = 10L,
  param_specs = NULL,
  mcmc_outcome = list(niter = 2000, nburnin = 500, thin = 1, nchains = 1, seed = 1),
  mcmc_ps = list(niter = 1000, nburnin = 250, thin = 1, nchains = 1, seed = 1),
  epsilon = 0.025,
  alpha_random = TRUE,
  ps_prior = list(mean = 0, sd = 2),
  include_intercept = TRUE,
  PS = "logit",
  ps_scale = c("logit", "prob"),
  ps_summary = c("mean", "median"),
  ps_clamp = 1e-06,
  monitor = c("core", "full"),
  monitor_latent = FALSE,
  monitor_v = FALSE
)
}
\arguments{
\item{y}{Numeric outcome vector.}

\item{X}{Design matrix or data.frame of covariates (N x P).}

\item{A}{Binary treatment indicator (length N, values 0/1).}

\item{backend}{Character; the Dirichlet process representation for outcome models:
\itemize{
\item \code{"sb"}: stick-breaking truncation
\item \code{"crp"}: Chinese Restaurant Process
\item \code{"spliced"}: CRP with GPD tail splicing
}
If length 2, the first entry is used for treated (\code{A=1}) and the
second for control (\code{A=0}).}

\item{kernel}{Character kernel name for outcome models (must exist in
\code{get_kernel_registry()}). If length 2:
\itemize{
\item first entry: used for treated (\code{A=1})
\item second entry: used for control (\code{A=0})
}}

\item{GPD}{Logical; include GPD tail for outcomes if TRUE. If length 2:
\itemize{
\item first entry: used for treated (\code{A=1})
\item second entry: used for control (\code{A=0})
}}

\item{components}{Integer >= 2; truncation parameter for outcome mixtures. If length 2:
\itemize{
\item first entry: used for treated (\code{A=1})
\item second entry: used for control (\code{A=0})
}}

\item{param_specs}{Outcome parameter overrides (same structure as
\code{build_nimble_bundle()}):
\itemize{
\item a single list: used for both arms
\item a list with \code{con} and \code{trt} entries: arm-specific overrides
}}

\item{mcmc_outcome}{MCMC settings list for the outcome bundles.}

\item{mcmc_ps}{MCMC settings list for the PS model.}

\item{epsilon}{Numeric in [0,1) used by outcome bundles for posterior truncation
summaries. If length 2:
\itemize{
\item first entry: used for treated (\code{A=1})
\item second entry: used for control (\code{A=0})
}}

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

\item{ps_prior}{Normal prior for PS coefficients. List with \code{mean} and \code{sd}.}

\item{include_intercept}{Logical; if TRUE, an intercept column is prepended to \code{X}
in the PS model.}

\item{PS}{Character or logical; controls propensity score estimation:
\itemize{
\item \code{"logit"} (default): Logistic regression PS model
\item \code{"probit"}: Probit regression PS model
\item \code{"naive"}: Gaussian naive Bayes PS model
\item \code{FALSE}: No PS estimation; outcome models use only \code{X}
}
The PS model choice is stored in bundle metadata for downstream use in
prediction and summaries.}

\item{ps_scale}{Scale used when augmenting outcomes with PS:
\itemize{
\item \code{"logit"}: augment on the logit (log-odds) scale
\item \code{"prob"}: augment on the probability scale
}}

\item{ps_summary}{Posterior summary for PS:
\itemize{
\item \code{"mean"}: posterior mean of propensity scores
\item \code{"median"}: posterior median of propensity scores
}}

\item{ps_clamp}{Numeric epsilon for clamping PS values to \eqn{(\epsilon, 1-\epsilon)}.}

\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; whether to monitor latent cluster labels (\code{z}) in outcome arms.}

\item{monitor_v}{Logical; whether to monitor stick-breaking \code{v} terms for SB outcomes.}
}
\value{
A list of class \code{"causalmixgpd_causal_bundle"} containing the
design bundle, two outcome bundles, training data, arm indices, and
metadata required for posterior prediction and causal effect summaries.
}
\description{
\code{build_causal_bundle()} is the detailed constructor behind
\code{\link{bundle}} for causal analyses. It prepares:
\itemize{
\item a propensity score (PS) design block for \eqn{A \mid X},
\item a control-arm outcome bundle for \eqn{Y(0)},
\item a treated-arm outcome bundle for \eqn{Y(1)}.
}
}
\details{
The outcome bundles reuse the one-arm DPM plus optional GPD machinery. The
PS block provides a shared adjustment object used by
\code{\link{run_mcmc_causal}} and
\code{\link{predict.causalmixgpd_causal_fit}}.

The causal bundle encodes the two arm-specific predictive laws
\eqn{F_0(y \mid x)} and \eqn{F_1(y \mid x)}. Downstream causal estimands are
functionals of these two distributions:
\deqn{\mathrm{ATE} = E\{Y(1)\} - E\{Y(0)\}, \qquad
\mathrm{QTE}(\tau) = Q_1(\tau) - Q_0(\tau).}

When \code{PS} is enabled, the package estimates a propensity score model
\eqn{e(x) = \Pr(A = 1 \mid X = x)} and uses a posterior summary of that score
as an augmented covariate in the arm-specific outcome models. This mirrors
the workflow described in the manuscript vignette.
}
\examples{
\donttest{
set.seed(1)
N <- 25
X <- cbind(x1 = rnorm(N), x2 = runif(N))
A <- rbinom(N, 1, plogis(0.3 + 0.5 * X[, 1]))
y <- rexp(N) + 0.1

cb <- build_causal_bundle(
  y = y,
  X = X,
  A = A,
  backend = "sb",
  kernel = "gamma",
  GPD = TRUE,
  components = 3,
  PS = "probit"
)
}
}
\seealso{
\code{\link{bundle}}, \code{\link{run_mcmc_causal}},
\code{\link{predict.causalmixgpd_causal_fit}}, \code{\link{ate}},
\code{\link{qte}}, \code{\link{cate}}, \code{\link{cqte}}.
}
