
The GP and probability model behind calibration
Source:vignettes/calibration-details.Rmd
calibration-details.RmdThis note explains the implementation corresponding to Sections 6 and 7.2 of Banerjee et al. (2025). The offline predictor for autoregressive design rows is an additional approximation used to remove the remaining PDE dependency.
Emulator coefficient sampling
The default sampling method is “marginal”, matching the smoothed-marginal procedure in equation (9) and Algorithm 4 of the paper. For each variance draw, $$ \Theta_e^{(m)}\mid\sigma^{2(m)},\mathcal D \sim MN(h_e,H_e,\sigma^{2(m)}R_{\rm episode}). $$ The coefficients at distinct episodes are sampled independently conditional on the shared variance. The resulting sampling law is $$ q_{\rm marginal}(\Psi\mid\mathcal D) =p(\sigma^2\mid\mathcal D) \prod_e p(\Theta_e\mid\sigma^2,\mathcal D). $$ It reproduces the smoothed marginals and does not retain the full posterior dependence across episode coefficients.
The option sampling = “joint” instead uses the backward conditional law in equation (7). With , it draws $$ \Theta_e^{(m)}\mid\Theta_{e+1}^{(m)},\sigma^{2(m)},\mathcal D \sim MN\left( m_e+B_e(\Theta_{e+1}^{(m)}-a_{e+1}), M_e-B_eA_{e+1}B_e^{\mathsf T}, \sigma^{2(m)}R_{\rm episode} \right). $$ This preserves coefficient dependence and gives the joint posterior sampling law $q_{\rm joint}(\Psi\mid\mathcal D)=p(\Psi\mid\mathcal D)$.
emulator_learn() defaults to marginal sampling. calibration_prepare() inherits the fitted method or resamples with an explicit sampling option. Saved objects record both the method and whether their samples are joint trajectories. The same two method choices are available for inverse-Wishart emulation, although calibration currently requires the scalar covariance model.
Two GP calculations
Let be an training response matrix for episode , and its autoregressive design. For a fixed emulator posterior coefficient sample set , the coefficients are and the variance is .
The first GP predicts the design rows. For time , stack the designs of its episodes, , center the columns by , and scale active parameter coordinates to . Each time has its own anisotropic Matern 5/2 kernel with fitted length scales and nugget,
The hyperparameters
maximize the GP likelihood of the time’s standardized design columns.
With
calibration_prepare(design_kernel = "sqexp", design_groups = "shared")
one squared-exponential kernel,
,
serves all times, as in earlier versions; the formulas below then hold
with a single kernel.
With the vector of covariances to a new input,
Split this row into . At runtime these rows require no PDE solution. The same GP describes their error. At each time all design columns share one kernel, so the errors are jointly Gaussian,
with the maximum-likelihood covariance between the time’s design
columns
,
where
and
.
Column
alone has variance
.
Different times are separate GPs.
calibration_prepare(design_uncertainty = FALSE) keeps only
the mean, as spDBL 1.1.1 did.
The second GP is the emulator’s original residual interpolation. Its exponential kernel uses the original mechanistic input coordinates:
The nugget is independent new-run noise and is excluded from J even at a coincident input. Gaussian conditioning yields
The development name residual_weights means : coefficients over the training parameter inputs, not weights over spatial locations. Shared Cholesky factors are cached; one draw’s residual coefficients are cached at a time.
Spatial recovery and covariance
Each episode is a spatial block at an observation time. The recovery function places each block mean back into its original grid indices. This rearrangement does not estimate correlations. The full-field emulator covariance is supplied separately:
$$ \widetilde\Sigma^{(m)}_t(\eta) =\sigma^{2(m)}q(\eta)R_{\rm field}+v_t(\eta)\,Z_t^{(m)\top}Z_t^{(m)}. $$
The second term propagates the design-row error. is : for each episode observed at time , its block’s columns hold , where are the columns of for episode . Block of this term is therefore , with the matching block of , so sites in different spatial blocks at the same time are correlated. Its rank is at most .
Observed locations select matching entries of the mean and covariance. The recorded kernel scale is preserved: R_field need not have unit diagonal. Its amplitude and nugget must not be silently normalized independently of the emulator variance scale.
The original exact FFBS prediction uses the smoothed coefficient mean. The extended function can instead condition on one fixed coefficient trajectory and return the conditional input covariance. Exact refers to Gaussian conditioning under the chosen surrogate, not an exact PDE solution.
Field-data likelihood
For the observed sites, paper Equation (27) becomes
The matrix U is a positive-definite discrepancy covariance scale; its diagonal need not equal one. Discrepancy increments have covariance tau2[t] * U, while observation errors retain covariance tau2[t] * I. It is distinct from the emulator covariance R_field. Initial states use and . Subsequently , with the shape–scale inverse-gamma convention . Stan samples reciprocal variances using the equivalent shape–rate gamma.
Integrating out the Gaussian emulator field gives
The observed input is z. It is not replaced by the GP prediction. Conditional emulator errors are independent across observation times given the fixed coefficient sample set. The joint sampling option preserves dependence between coefficients from different episodes. The marginal option retains the smoothed marginal distributions conditional on the shared variance.
Marginal discrepancy sampling
The joint Stan program samples discrepancy innovations. The default marginal program integrates discrepancy states out exactly. Starting at , , the Kalman recursion is
Its log likelihood is
Gaussian backward sampling subsequently recovers coherent discrepancy paths. The joint and marginal programs target the same conditional calibration model.
Modular posterior pooling
For emulator parameters and selected sampling law , pooling uses
$$ p_{\rm mod}^{(s)}(\vartheta\mid z,\mathcal D) =\int p(\vartheta\mid z,\Psi,\mathcal D) q_s(\Psi\mid\mathcal D)\,d\Psi \approx \frac1M\sum_m p(\vartheta\mid z,\Psi^{(m)},\mathcal D). $$
Each conditional distribution is normalized separately. Equal numbers of retained samples are pooled. A single model using an averaged likelihood would generally reweight emulator draws according to their field-data evidence and target a different posterior.
Here s denotes the selected emulator sampling method. Joint sampling uses the full emulator posterior in equation (29); marginal sampling uses the product of smoothed conditional marginals defined above. Pooling follows the selected law in both cases.
There are two sampling dimensions: the number of emulator trajectories and the number of calibration transitions conditional on each trajectory. The number of iterations has no default and must be chosen. Chains default to one, warmup to floor(iter / 2), and the retained count to at most 200 available samples per emulator draw. The controls disable adaptation for zero warmup and enable it for positive warmup.
Convergence must be assessed within each conditional fit. One transition from each of 500 initial states is not a converged approximation of this integral.
Uncertainty and limitations
The implementation retains coefficient samples, emulator variance, conditional GP prediction error, dynamic discrepancy, and independent measurement error. For fixed eta before observing field data, emulator uncertainty decomposes as
The design GP’s predictive covariance enters
by default (design_uncertainty = TRUE), but its
hyperparameters are plug-in maximum-likelihood estimates, so their
uncertainty is not represented. Design errors are also treated as
independent across times and independent of the emulator’s residual
error, although the same lagged fields enter the designs of consecutive
times. Both simplifications make calibration intervals somewhat too
narrow.
The initial public calibration interface supports the sigma2R emulator, fixed discrepancy covariance scale, finite complete observation matrices, and subsets of the original time/grid setup. It does not silently convert an inverse-Wishart fit, fill missing observations, or forecast new sites or times.