ref_adapt

Usage

ref_adapt(
  fit,
  data,
  by = NULL,
  parameters = c("location"),
  location_prior_n = 10,
  scale_prior_n = 25
)

Freezes the shared trajectory and estimates shrunk location (and optionally scale) offsets per group. This is not recalibration (see ref_calibrate()) and not a refit of the shared trajectory.

Arguments

Argument	Description
fit	A ref_fit or ref_dynamics object.
data	Local reference observations.
by	Grouping column (typically site). Rows whose group is not in the adaptation data (or when by is NULL) use the pooled offset.
parameters	Parameters to adapt: "location" and optionally "scale".
location_prior_n	Ridge strength in observation units.
scale_prior_n	Stronger default shrinkage for scale.

Details

Offsets $\delta_\mu$ (units of the fitted scale, that is of transformed outcome when ref_spec() carries one) and $\delta_\sigma$ (log scale) are estimated per outcome and group by penalised maximum likelihood on the reference family’s own density with the shared trajectory frozen, so the estimates are correct for SHASH as well as Gaussian fits. The estimation is in two stages: the location offset with the scale held at the reference’s, then the scale offset given that location. (A joint fit lets the shrunk-away part of the location inflate the scale, which in turn weakens the location likelihood; at small local n that feedback roughly halves the location estimate.) The ridge penalties are worth location_prior_n and scale_prior_n pseudo-observations of Fisher information, giving a shrinkage factor of $n/(n + \text{prior}_n)$ on the location and about $2n/(2n + \text{prior}_n)$ on the log scale. For a Gaussian fit this is the shrunk mean residual and $\tfrac12\log \mathrm{mean}(z^2)$ with $z$ the normal scores under the location-shifted reference; a site drawn from the reference generator has an expected offset of zero. Standard errors come from the penalised Hessian and do not include the shrinkage bias, so with the default priors a large true offset is recovered only as its shrunk value.

Adaptation is applied inside predict.ref_fit(): the location of every predictive distribution (including coefficient draws under uncertainty = "total") is shifted and the scale multiplied by $e^{\delta_\sigma}$. Under uncertainty = "total" the standard error of the location offset is propagated as well: analytically for a Gaussian predictive and as an extra seeded location perturbation per coefficient draw for a draw mixture.

Value

The fit with an adaptation slot (class ref_adaptation) recording the offsets, their standard errors, and local sample sizes.