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

\item{unit}{output unit. Only \code{"estimate"} is available for LOO-PIT
residuals.}

\item{conditioning_depth}{unused for LOO-PIT residuals. LOO-PIT residuals
always use the estimate-unit LOO target.}

\item{...}{additional arguments (currently ignored)}
}
\value{
A data frame with columns:
\itemize{
\item \code{resid}: Raw residuals
\item \code{se}: Standard errors of the residuals
\item \code{z}: Externally standardized residuals (LOO-PIT)
}
}
\description{
Computes externally standardized residuals (also called
studentized residuals or standardized deleted residuals) from a fitted brma
object using LOO-PIT (Leave-One-Out Probability Integral Transform).
Returns a data frame with raw residuals, standard errors, and standardized
residuals (z-values).
}
\details{
This function returns a data frame with three columns matching the output
of \code{metafor::rstudent}:
\itemize{
\item \code{resid}: LOO predictive residuals (observed - fitted values)
\item \code{se}: LOO predictive standard errors when available
\item \code{z}: Externally standardized residuals (LOO-PIT transformed)
}

LOO-PIT residuals are the Bayesian equivalent of studentized deleted
residuals. They are computed via leave-one-out probability integral
transformation using Pareto smoothed importance sampling. For each
observation, the LOO-weighted CDF is computed and transformed to a
standard normal quantile.

Under a correctly specified model, LOO-PIT residuals should follow a
standard normal distribution. Large absolute values may indicate outliers
or model misspecification.

The \code{z} column is the primary standardized diagnostic. The \code{resid}
and \code{se} columns are raw-scale companions computed from LOO predictive
moments using the normalized PSIS weights. For selection models, these moments
are computed from the fitted selected-normal predictive distribution. For
GLMMs, they are computed on the approximate effect-size scale used by the
LOO-PIT diagnostic; they are not exact PIT diagnostics for the raw count
likelihood.

Unlike \code{\link{rstandard.brma}} (which uses the hat matrix), LOO-PIT
residuals properly account for estimation uncertainty and leverage without
requiring explicit hat matrix computation. This makes \code{rstudent.brma}
suitable for all model types including selection models and GLMMs.
}
\examples{
\dontrun{
if (requireNamespace("metadat", quietly = TRUE)) {
  data(dat.lehmann2018, package = "metadat")
  fit <- brma(yi = yi, vi = vi, data = dat.lehmann2018, measure = "SMD")
  fit <- add_loo(fit)

  # externally standardized residuals
  rstudent(fit)

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

}
\seealso{
\code{\link[=rstandard.brma]{rstandard.brma()}}, \code{\link[=residuals.brma]{residuals.brma()}}, \code{\link[=loo.brma]{loo.brma()}}, \code{\link[=blup.brma]{blup.brma()}}
}
