ref_calibrate

Usage

ref_calibrate(
  fit,
  data,
  by = NULL,
  uncertainty = c("total", "conditional"),
  n_draw = NULL
)

Maps PIT values through a monotone map estimated on a calibration sample: $F^\star(y\mid x)=G(F_0(y\mid x))$. This targets global (or group-specific) calibration. It does not create full conditional calibration, so pre-calibration diagnostics (the assessment tables, without the per-row scores) are kept in fit$calibration$pre.

Arguments

Argument	Description
fit	A ref_fit.
data	Calibration reference data, not reused for evaluation, or an out-of-fold ref_scores table from ref_crossfit(). Passing the cross-fitted scores calibrates on the reference sample itself without holding any of it out.
by	Optional grouping column (e.g. site). Groups absent from the calibration data fall back to the pooled map. Not available when data is a score table.
uncertainty	Which predictive the calibration data are scored under, as in ref_assess(). A map corrects the predictive it was fitted on, so this should match the uncertainty that predict.ref_fit() will later be asked for. Defaults to "total", matching prediction. A score table supplies this provenance itself.
n_draw	Number of coefficient draws for total uncertainty. This is retained and must match later score predictions.

Details

The map is a sinh-arcsinh reference distribution for the normal score $z_0=\Phi^{-1}(F_0(y\mid x))$, that is $G(u)=P_{\mathrm{SHASH}}(\Phi^{-1}(u))$. Its four parameters move the location, spread, skew, and tail weight of $z$, and it nests the identity ($\mu=0,\sigma=1,\epsilon=0,\delta=1$), so a model that is already calibrated is left alone. It is smooth and strictly monotone on the whole line, so extreme observations keep extreme, finite, correctly ordered scores.

Because $F^\star=G(F_0)$, the whole predictive moves, not just the centile: the density is $f^\star=g(F_0(y))f_0(y)$, so log_density and every density-based score change, and the calibrated median is $Q_0(G^{-1}(1/2))$, so median and residual change as well.

The map is kept only where it earns its place: the fitted parameters are used when their log-likelihood beats the identity’s by more than the four parameters they cost, which is the AIC comparison of the two, and the map falls back to the exact identity when they do not. On calibration scores that are already uniform the fitted map survives that comparison for about 5 percent of samples, and is close to the identity when it does. A map is absent altogether, leaving calibrated = FALSE, only when there are fewer than twenty usable scores or the fit does not converge.

Value

The fit with a calibration slot; predict.ref_fit() applies the map to centile, z, log_density, median, residual, and the tail columns and sets calibrated = TRUE.