% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods.R
\name{residuals.mixgpd_fit}
\alias{residuals.mixgpd_fit}
\title{Residual diagnostics on the training design}
\usage{
\method{residuals}{mixgpd_fit}(
  object,
  type = c("raw", "pit"),
  fitted_type = c("mean", "median"),
  pit = c("plugin", "bayes_mean", "bayes_draw"),
  pit_seed = NULL,
  ...
)
}
\arguments{
\item{object}{A fitted object of class \code{"mixgpd_fit"} (must have covariates).}

\item{type}{Residual type:
\itemize{
\item \code{"raw"}: observed minus fitted values
\item \code{"pit"}: probability integral transform
residuals (see \code{pit} argument)
}}

\item{fitted_type}{For \code{type = "raw"}, use fitted means or medians.}

\item{pit}{PIT mode for \code{type = "pit"}:
\itemize{
\item \code{"plugin"}: plug-in PIT using the posterior mean CDF.
\item \code{"bayes_mean"}: Bayesian PIT using draw-wise CDFs averaged over draws.
\item \code{"bayes_draw"}: Bayesian PIT using a single draw-wise CDF per observation.
}
Bayesian PIT modes drop invalid posterior draws using the same validation
rules as prediction and attach diagnostics via \code{attr(res, "pit_diagnostics")}.}

\item{pit_seed}{Optional integer seed for reproducible \code{bayes_draw} sampling.}

\item{...}{Unused.}
}
\value{
Numeric vector of residuals with length equal to the training sample
size. PIT variants attach diagnostic metadata as attributes.
}
\description{
\code{residuals.mixgpd_fit()} computes residual diagnostics for conditional
fits on the original training data.
}
\details{
Raw residuals are based on posterior predictive fitted means or medians.
PIT residuals instead assess calibration through the posterior predictive CDF.
The plug-in PIT uses a posterior mean CDF, while the Bayesian PIT variants
work draw by draw.

This method is not available for unconditional models because no training
design matrix is stored for observation-specific fitted values.
}
\examples{
\donttest{
y <- abs(stats::rnorm(25)) + 0.1
X <- data.frame(x1 = stats::rnorm(25), x2 = stats::runif(25))
bundle <- build_nimble_bundle(y = y, X = X, backend = "sb", kernel = "lognormal",
                             GPD = FALSE, components = 3,
                             mcmc = list(niter = 100, nburnin = 50, thin = 1, nchains = 1))
fit <- run_mcmc_bundle_manual(bundle)
pit_plugin <- residuals(fit, type = "pit", pit = "plugin")
pit_bayes_mean <- residuals(fit, type = "pit", pit = "bayes_mean", pit_seed = 1L)
pit_bayes_draw <- residuals(fit, type = "pit", pit = "bayes_draw", pit_seed = 1L)
attr(pit_bayes_draw, "pit_diagnostics")
}
}
\seealso{
\code{\link{fitted.mixgpd_fit}}, \code{\link{predict.mixgpd_fit}},
\code{\link{plot.mixgpd_fitted}}.
}
