% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/calibrate.R
\name{et_calibrate}
\alias{et_calibrate}
\title{Assess calibration of posterior predictive intervals}
\usage{
et_calibrate(predictions, observed, response_col = NULL, ci_levels = NULL, ...)
}
\arguments{
\item{predictions}{An \code{et_prediction} or \code{et_prediction_list}.}

\item{observed}{A \code{data.frame} with true response values.  Must have
the same number of rows as \code{predictions$newdata} (rows are matched
positionally) and a column with the true response values.}

\item{response_col}{Character.  Name of the response column in
\code{observed}.  Defaults to the left-hand side of the model formula
if it can be inferred, otherwise must be specified.}

\item{ci_levels}{Numeric vector.  CI levels to assess.  Defaults to all
levels present in the \code{et_prediction} object.}

\item{...}{Unused.}
}
\value{
A \code{data.frame} with columns:
  \describe{
    \item{ci_level}{Nominal CI level.}
    \item{nominal}{Same as ci_level.}
    \item{observed_coverage}{Fraction of true values falling inside the CI.}
    \item{n_obs}{Number of observations used.}
    \item{calibration_error}{Signed difference: observed - nominal.
      Positive = over-coverage (CIs too wide / conservative).
      Negative = under-coverage (CIs too narrow / overconfident).}
    \item{sharpness}{Mean CI width across observations.  Sharpness and
      calibration are complementary: a model can be calibrated but useless
      if sharpness is poor (very wide CIs).}
  }
  For grouped predictions, a \code{group} column is prepended.
}
\description{
Computes observed coverage probability at multiple nominal CI levels.
A well-calibrated Bayesian model should produce 90\% CIs that contain
the true value 90\% of the time, etc.
}
\examples{
\donttest{
set.seed(1)
df  <- data.frame(y = rnorm(20), x1 = rnorm(20))
fit <- et_fit(y ~ x1, data = df,
              chains = 1, iter = 500, warmup = 250,
              cores = 1, refresh = 0)
valid_df <- data.frame(y = rnorm(5), x1 = rnorm(5))
pred <- et_predict(fit, newdata = valid_df,
                   n_draws = 200, n_perturb = 50)
cal <- et_calibrate(pred, observed = valid_df, response_col = "y")
print(cal)
}
}
