% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/causal.R
\name{predict.causalmixgpd_causal_fit}
\alias{predict.causalmixgpd_causal_fit}
\title{Predict arm-specific and contrast-scale quantities from a causal fit}
\usage{
\method{predict}{causalmixgpd_causal_fit}(
  object,
  newdata = NULL,
  y = NULL,
  ps = NULL,
  id = NULL,
  type = c("mean", "quantile", "density", "survival", "prob", "sample"),
  p = NULL,
  index = NULL,
  nsim = NULL,
  interval = "credible",
  probs = c(0.025, 0.5, 0.975),
  store_draws = TRUE,
  nsim_mean = 200L,
  ncores = 1L,
  show_progress = TRUE,
  ...
)
}
\arguments{
\item{object}{A \code{"causalmixgpd_causal_fit"} object returned by
\code{run_mcmc_causal()}.}

\item{newdata}{Optional new data. If \code{NULL}, uses training design (if stored).}

\item{y}{Numeric vector of evaluation points (required for \code{type="density"} or \code{"survival"}).}

\item{ps}{Optional numeric vector of propensity scores aligned with
\code{newdata}. When provided, the supplied scores are used instead of
recomputing them from the stored PS model (needed only for custom inputs).}

\item{id}{Optional identifier for prediction rows. Provide either a column name
in \code{newdata} or a vector of length \code{nrow(newdata)}. The id column
is excluded from analysis.}

\item{type}{Prediction type:
\itemize{
\item \code{"mean"}: posterior predictive mean treatment effect
\item \code{"quantile"}: posterior predictive quantile treatment effect
\item \code{"density"}: arm-specific posterior predictive densities
\item \code{"survival"}: arm-specific posterior predictive survival functions
\item \code{"prob"}: arm-specific posterior predictive probabilities
\item \code{"sample"}: paired posterior predictive samples
}}

\item{p}{Numeric vector of probabilities for quantiles (required for \code{type="quantile"}).}

\item{index}{Alias for \code{p}; numeric vector of quantile levels.}

\item{nsim}{Number of posterior predictive samples when \code{type = "sample"}.}

\item{interval}{Character or NULL; type of credible interval:
\itemize{
\item \code{NULL}: no interval
\item \code{"credible"} (default): equal-tailed quantile intervals
\item \code{"hpd"}: highest posterior density intervals
}}

\item{probs}{Quantiles for credible interval bands.}

\item{store_draws}{Logical; whether to store treatment-effect sample draws in
the returned object when \code{type = "sample"}.}

\item{nsim_mean}{Number of posterior predictive samples used by
simulation-based mean targets. Ignored for analytical
\code{type = "mean"}; still used for \code{type = "rmean"}.}

\item{ncores}{Number of CPU cores to use for parallel prediction (if supported).}

\item{show_progress}{Logical; if TRUE, print step messages and render progress where supported.}

\item{...}{Additional arguments forwarded to per-arm
\code{\link{predict.mixgpd_fit}} calls.}
}
\value{
For \code{"mean"} and \code{"quantile"}, a causal prediction object
whose \code{$fit} component reports treated-minus-control posterior
summaries. For \code{"density"}, \code{"survival"}, and \code{"prob"},
the \code{$fit} component contains side-by-side treated and control
summaries evaluated on the supplied \code{y} grid. For \code{"sample"},
the returned object contains paired treated, control, and treatment-effect
posterior predictive samples. Sample outputs also include long-form data
frames \code{$fit_df}, \code{$trt_fit_df}, and \code{$con_fit_df} for
direct extraction.
}
\description{
\code{predict.causalmixgpd_causal_fit()} is the causal counterpart to
\code{\link{predict.mixgpd_fit}}. It coordinates the treated and control arm
predictions so that both sides use the same covariate rows and the same PS
adjustment.
}
\details{
For each prediction row \eqn{x}, the function evaluates arm-specific
posterior predictive quantities based on
\eqn{F_1(y \mid x)} and \eqn{F_0(y \mid x)}. Mean
and quantile outputs are returned on the treatment-effect scale, while
density, survival, and probability outputs retain both arm-specific curves.
For outcome kernels with a finite analytical mean, the mean path uses
analytical per-draw means; restricted means remain simulation-based.

If a PS model is stored in the fit, the same estimated score is supplied to
both arms unless the user overrides it with \code{ps}. This is the main
prediction entry point used internally by \code{\link{ate}}, \code{\link{qte}},
\code{\link{cate}}, and \code{\link{cqte}}.
}
\examples{
\donttest{
N <- 25
X <- data.frame(x1 = stats::rnorm(N))
A <- stats::rbinom(N, 1, 0.5)
y <- abs(stats::rnorm(N)) + 0.1
mcmc_small <- list(niter = 100, nburnin = 50, thin = 1, nchains = 1, seed = 1)
cb <- build_causal_bundle(y = y, X = X, A = A, backend = "sb", kernel = "normal",
                         mcmc_outcome = mcmc_small, mcmc_ps = mcmc_small)
fit <- run_mcmc_causal(cb)
predict(fit, newdata = X[1:10, , drop = FALSE], type = "quantile", index = c(0.25, 0.5, 0.75))
predict(fit, newdata = X[1:10, ], type = "mean", interval = "hpd")  # HPD intervals
predict(fit, newdata = X[1:10, ], type = "mean", interval = NULL)   # No intervals
}
}
\seealso{
\code{\link{predict.mixgpd_fit}}, \code{\link{ate}},
\code{\link{qte}}, \code{\link{cate}}, \code{\link{cqte}}.
}
