% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/residuals.R
\name{residuals.brma}
\alias{residuals.brma}
\title{Residuals for brma Objects}
\usage{
\method{residuals}{brma}(
  object,
  type = "outcome",
  unit = "estimate",
  conditioning_depth = "marginal",
  bias_adjusted = FALSE,
  ...
)
}
\arguments{
\item{object}{a fitted brma object}

\item{type}{the type of residuals to compute. Options are:
\itemize{
\item \code{"outcome"} (default): Raw residuals (observed - fitted).
Available for all model types.
\item \code{"pearson"}: Pearson (semi-standardized) residuals, dividing
raw residuals by the marginal standard error \eqn{\sqrt{v_i + \tau^2}}.
Only available for normal outcome models without selection (weightfunction)
bias adjustment.
\item \code{"rstandard"}: Internally standardized residuals, dividing
raw residuals by their standard errors computed using the hat matrix.
Only available for normal outcome models without selection (weightfunction)
bias adjustment.
\item \code{"LOO-PIT"} (alias: \code{"rstudent"}): Leave-one-out probability
integral transform (PIT) residuals computed via Pareto smoothed importance
sampling. The LOO-CDF value for each observation is computed and transformed
to standard normal quantiles via \eqn{\Phi^{-1}(u_i)}. Under a correctly
specified model, these residuals should follow a standard normal distribution.
This is the recommended standardized residual for Bayesian models as it properly
accounts for estimation uncertainty and leverage. Available for all model
types. Note: This requires that the loo has been computed previously (see
\code{add_loo()} function).
}}

\item{unit}{output unit. Only \code{"estimate"} is implemented currently..}

\item{conditioning_depth}{conditioning depth for non-LOO residuals. \code{"marginal"}
uses fixed effects only, \code{"cluster"} conditions on cluster-level random
effects, and \code{"estimate"} conditions on the full estimate-level fitted
value. LOO-PIT residuals always use the estimate-unit LOO target.}

\item{bias_adjusted}{whether residuals should be computed from bias-adjusted
fitted values. Defaults to \code{FALSE}, which means residuals are computed
as the difference between observed values and raw (biased) predictions
including PET/PEESE terms. Set to \code{TRUE} to compute residuals from
bias-corrected fitted values. Applies to outcome and Pearson residuals. Note
that bias-adjusted residuals are not residuals in the traditional sense.}

\item{...}{additional arguments.}
}
\value{
A numeric vector of residual means, one per estimate.
}
\description{
Computes residuals (observed minus fitted values) from a
fitted brma object, with options for standardization.
}
\details{
Raw residuals (\code{type = "outcome"}) are computed as:
\deqn{e_i = y_i - \hat{\mu}_i}
where \eqn{y_i} is the observed effect size and \eqn{\hat{\mu}_i} is the
fitted value (prediction from the fixed effects).

Pearson residuals (\code{type = "pearson"}) divide raw residuals by the
marginal standard error:
\deqn{r_i^{Pearson} = \frac{e_i}{\sqrt{v_i + \tau^2}}}
where \eqn{v_i} is the sampling variance and \eqn{\tau^2} is the
relevant heterogeneity component. Only available for normal outcome models
without selection (weightfunction) bias adjustment.

Standardized residuals (\code{type = "rstandard"}) use the hat matrix to
compute residual standard errors that account for the uncertainty in
estimated coefficients:
\deqn{z_i = \frac{e_i}{\sqrt{[(I-H)M(I-H)']_{ii}}}}
where \eqn{H} is the hat matrix and \eqn{M} is the marginal variance-covariance
matrix. For models without moderators, this simplifies to the Pearson formula.
Only available for normal outcome models without selection (weightfunction)
bias adjustment.

LOO-PIT residuals (\code{type = "LOO-PIT"}) are the Bayesian equivalent of
studentized deleted residuals \insertCite{vehtari2017practical}{RoBMA}. They
are computed via leave-one-out probability integral transformation:
\deqn{r_i = \Phi^{-1}(u_i)}
where \eqn{u_i = \sum_s w_{is} F(y_i | \theta^{(s)})} is the LOO-weighted CDF
value, \eqn{w_{is}} are the normalized PSIS weights, and \eqn{F} is the
cumulative distribution function of the estimate-unit predictive
distribution used by LOO. Under a correctly specified model, LOO-PIT
residuals should follow a standard normal distribution. Unlike traditional
standardized residuals, LOO-PIT residuals properly account for estimation
uncertainty and leverage without requiring a hat matrix. This is the
recommended method for standardized residuals in Bayesian meta-analysis.

For meta-regression models, fitted values incorporate moderator effects.
For models without moderators, all fitted values equal the pooled effect.

For GLMM models (binomial or Poisson), observed effect sizes and their
sampling variances are computed from the raw frequency data using the
same formulas as \code{metafor::escalc} with the default zero-cell
adjustment (adding 0.5 to all cells when any cell is zero). GLMM residuals
and LOO-PIT values are therefore approximate effect-size-scale diagnostics,
not exact PIT diagnostics for the raw count likelihood.

The residuals are computed separately for each posterior sample,
naturally propagating uncertainty in model parameters to the residuals.
}
\examples{
\dontrun{
if (requireNamespace("metadat", quietly = TRUE)) {
  data(dat.lehmann2018, package = "metadat")

  fit <- bPET(
    yi      = yi,
    vi      = vi,
    data    = dat.lehmann2018,
    measure = "SMD",
    seed    = 1,
    silent  = TRUE
  )

  # raw residuals (default)
  residuals(fit)

  # Pearson and internally standardized residuals
  residuals(fit, type = "pearson")
  residuals(fit, type = "rstandard")

  # LOO-PIT residuals require stored LOO
  fit <- add_loo(fit)
  residuals(fit, type = "LOO-PIT")

  # residuals from bias-adjusted predictions
  residuals(fit, bias_adjusted = TRUE)

  # check Pareto k diagnostics
  plot(loo(fit))
}
}

}
\references{
\insertAllCited{}
}
\seealso{
\code{\link[=predict.brma]{predict.brma()}}, \code{\link[=blup.brma]{blup.brma()}}, \code{\link[=pooled_effect]{pooled_effect()}}, \code{\link[=rstandard.brma]{rstandard.brma()}}, \code{\link[=rstudent.brma]{rstudent.brma()}}
}
