% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods.R
\name{predict.mixgpd_fit}
\alias{predict.mixgpd_fit}
\title{Posterior predictive summaries from a fitted one-arm model}
\usage{
\method{predict}{mixgpd_fit}(
  object,
  newdata = NULL,
  y = NULL,
  ps = NULL,
  id = NULL,
  type = c("density", "survival", "quantile", "sample", "mean", "rmean", "median", "fit"),
  p = NULL,
  index = NULL,
  nsim = NULL,
  level = 0.95,
  interval = "credible",
  probs = c(0.025, 0.5, 0.975),
  store_draws = TRUE,
  nsim_mean = 200L,
  cutoff = NULL,
  ncores = 1L,
  show_progress = TRUE,
  ndraws_pred = NULL,
  chunk_size = NULL,
  parallel = FALSE,
  workers = NULL,
  ...
)
}
\arguments{
\item{object}{A fitted object of class \code{"mixgpd_fit"}.}

\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 for conditional prediction.
Used when the model was fit with propensity score augmentation.}

\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{"density"}: Posterior predictive density f(y | x, data)
\item \code{"survival"}: Posterior predictive survival S(y | x, data) = 1 - F(y | x, data)
\item \code{"quantile"}: Posterior predictive quantiles Q(p | x, data)
\item \code{"sample"}: Posterior predictive samples Y^rep ~ f(y | x, data)
\item \code{"mean"}: Posterior predictive mean E(Y | x, data) (averaged over posterior parameter uncertainty)
\item \code{"rmean"}: Posterior predictive restricted mean \eqn{E[\min(Y, cutoff) \mid x, data]}
\item \code{"median"}: Posterior predictive median (quantile at p=0.5)
\item \code{"fit"}: Per-observation posterior predictive draws
}
Note: \code{type="mean"} returns the posterior predictive mean, which integrates over
parameter uncertainty. This differs from the mean of a single model distribution.}

\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 (for \code{type="sample"}).}

\item{level}{Credible level for credible intervals (default 0.95 for 95 percent intervals).}

\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 all posterior draws (for \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{cutoff}{Finite numeric cutoff for \code{type="rmean"} (restricted mean).}

\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{ndraws_pred}{Optional integer subsample of posterior draws for prediction speed.
If NULL and \code{nrow(newdata) > 20000}, defaults to 200.}

\item{chunk_size}{Optional row chunk size for large \code{newdata} prediction.
If NULL and \code{nrow(newdata) > 20000}, defaults to 10000.}

\item{parallel}{Logical; if TRUE, enable parallel prediction (alias for setting \code{ncores > 1}).}

\item{workers}{Optional integer worker count (alias for \code{ncores}).}

\item{...}{Unused.}
}
\value{
A list with elements:
\itemize{
\item \code{fit}: numeric vector/matrix for \code{type = "sample"}, otherwise a data frame with
\code{estimate}/\code{lower}/\code{upper} columns (posterior means over draws) plus any index
columns (e.g. \code{id}, \code{y}, \code{index}).
\item \code{fit_df}: a machine-readable data frame view of the prediction output. For
non-sample types this aliases \code{fit}; for \code{type = "sample"} it is a long-form
data frame with draw indices and sampled values.
\item \code{lower}, \code{upper}: reserved for backward compatibility (typically \code{NULL}).
\item \code{type}, \code{grid}: metadata.
}
}
\description{
\code{predict.mixgpd_fit()} is the central distributional prediction method
for fitted one-arm models.
}
\details{
The method works with posterior predictive functionals rather than raw model
parameters. Supported output types include:
\itemize{
\item \code{"density"} for \eqn{f(y \mid x)},
\item \code{"survival"} for \eqn{S(y \mid x) = 1 - F(y \mid x)},
\item \code{"quantile"} for \eqn{Q(\tau \mid x)},
\item \code{"mean"} for \eqn{E(Y \mid x)},
\item \code{"rmean"} for \eqn{E\{\min(Y, c) \mid x\}},
\item \code{"sample"} and \code{"fit"} for draw-level predictive output.
}

For spliced models these predictions integrate over both the DPM bulk and
the GPD tail using component-specific tail parameters, including link-mode
tail coefficients when present. For kernels with a finite analytical mean,
\code{type = "mean"} computes the posterior-draw mean analytically and then
summarizes those draw-level means across the posterior. The
\code{type = "rmean"} path remains a separate posterior predictive
simulation pipeline.

For kernels with an analytical mean, \code{type = "mean"} is computed
analytically within each posterior draw and then summarized over draws. For
GPD-tail fits this analytical path is used when the tail shape parameter
satisfies \eqn{\xi < 1}. If the mean does not exist analytically for the
chosen kernel or if any required GPD tail has \eqn{\xi \ge 1}, the ordinary
mean is undefined and the function errors with a message directing you to
\code{type = "rmean"} or other summaries that remain well defined.
}
\examples{
\donttest{
y <- abs(stats::rnorm(25)) + 0.1
bundle <- build_nimble_bundle(y = y, backend = "sb", kernel = "normal",
                             GPD = TRUE, components = 3,
                             mcmc = list(niter = 100, nburnin = 50, thin = 1, nchains = 1))
fit <- run_mcmc_bundle_manual(bundle)
pr <- predict(fit, type = "quantile", p = c(0.5, 0.9))
pr_surv <- predict(fit, y = sort(y), type = "survival")
pr_cdf <- list(fit = 1 - pr_surv$fit)
# HPD intervals
pr_hpd <- predict(fit, type = "quantile", p = c(0.5, 0.9), interval = "hpd")
# No intervals
pr_none <- predict(fit, type = "quantile", p = c(0.5, 0.9), interval = NULL)
# Restricted mean (finite under heavy tails)
pr_rmean <- predict(fit, type = "rmean", cutoff = 10, interval = "credible")
}
}
\seealso{
\code{\link{summary.mixgpd_fit}}, \code{\link{fitted.mixgpd_fit}},
\code{\link{residuals.mixgpd_fit}}, \code{\link{predict.causalmixgpd_causal_fit}}.
}
