
Fit modular calibration conditional on emulator posterior draws
Source:R/calibration_fit.R
calibration_fit.RdTargets one conditional posterior per fixed emulator coefficient set and pools equal numbers of samples. The emulator is not updated by field observations. Gaussian emulator fields are integrated out. By default discrepancy states are also integrated out using a Kalman filter.
Usage
calibration_fit(
object,
z,
U,
locations = seq_len(object$S),
backend = "rstan",
draws = seq_len(object$M),
chains = 1L,
iter,
warmup = iter%/%2L,
draws_per_emulator = min(200L, chains * (iter - warmup)),
n0 = 30,
d0 = 2,
discount = 1,
m0 = rep(0, length(locations)),
M0 = diag(length(locations)),
seed = 1234L,
cores = 1L,
marginal_discrepancy = TRUE,
keep_predictions = FALSE,
keep_discrepancy = TRUE,
control = if (warmup == 0L) list(adapt_engaged = FALSE, stepsize = 0.001, max_treedepth
= 12L) else list(adapt_delta = 0.95, max_treedepth = 12L),
refresh = 100L,
checkpoint_dir = NULL,
cache = TRUE,
cache_dir = NULL,
compiled_model = NULL,
init = "mode",
mode_starts = 20L,
parallel_draws = 1L
)Arguments
- object
Prepared emulator from
calibration_prepare().- z
Finite time-by-observed-location matrix of field observations.
- U
Full-grid symmetric positive-definite discrepancy covariance scale. Correlation matrices are supported, but the diagonal need not equal one. Discrepancy increments have covariance tau2t * U; observation errors retain covariance tau2t * I.
- locations
Ordered original-grid indices corresponding to columns of z.
- backend
Currently "rstan".
- draws
Emulator draw indices to use, without duplicates.
- chains, iter, warmup
Number of chains, total iterations per chain, and warmup iterations for each emulator-conditional fit.
iterhas no default and must be given. For inference use several chains and enough iterations, for examplechains = 4, iter = 2000;iter = 1(with no warmup) is a quick execution check, not inference.chainsdefaults to one andwarmuptofloor(iter / 2).- draws_per_emulator
Equal number of retained samples per conditional. Defaults to the smaller of 200 and the available post-warmup samples.
- n0, d0
Positive inverse-gamma shape and scale hyperparameters.
- discount
Calibration variance discount factor in (0, 1].
- m0, M0
Initial discrepancy mean and covariance scale at observed sites.
- seed
Nonnegative integer RNG seed, local to the function call.
- cores
Positive number of parallel chains. Defaults to one.
- marginal_discrepancy
Whether to integrate out discrepancy states.
- keep_predictions, keep_discrepancy
Whether to recover and retain latent fields, replicated observations, and discrepancy states.
- control
Named list passed to rstan sampling. With zero warmup the defaults disable adaptation and use stepsize = 0.001. With warmup they use adapt_delta = 0.95. Both use max_treedepth = 12.
- refresh
Stan progress reporting interval.
- checkpoint_dir
Optional directory for completed conditional fits. Each fit is saved as it completes; a fit already saved there with the same data, settings, seed and Stan program is reused instead of refitted, so an interrupted calibration resumes where it stopped.
- cache, cache_dir
Whether to reuse compiled models and optional user cache directory. Installed package files are never modified.
- compiled_model
Optional compatible compiled Stan model for advanced use.
- init
Starting values of the free parameters for every chain.
"mode"(the default) runs L-BFGS (rstan::optimizing()) frommode_startsrandom starts in each conditional fit and starts every chain, slightly jittered, at the optimum with the highest log posterior density, with the precisions of that optimum. Chains started far from the main mode can settle in local modes of negligible posterior mass, which this avoids; the optima found are recorded indiagnostics[[j]]$mode_search."random"draws each chain's start uniformly within the bounds, reproducibly fromseed, so that \(\hat R\) can reveal chains that settle in different modes;"midpoint"starts every chain at the centre of the bounds; or give a numeric vector of parameter values in training-column order (named vectors are matched by name), strictly inside the bounds of the free parameters. Values given for fixed parameters are ignored. Each conditional fit starts afresh; except for"mode", precisions start at n0 / d0.- mode_starts
Number of random starts of the mode search for
init = "mode".- parallel_draws
Number of conditional fits (one per emulator draw) run at the same time, in forked processes. Each forked fit runs its chains one after another, so
coresis then not used andparallel_drawsprocesses run at once. With a multithreaded BLAS (for example oneMKL or OpenBLAS), start R withOMP_NUM_THREADS=1: forking after the BLAS has used several threads can leave the forked fits hung, andcalibration_fit()warns when it detects that setup. Results do not depend on it: every fit draws its random numbers from its own seeds, and rstan's draws do not depend on the number of cores. Forking is unavailable on Windows, where fits run one after another. Defaults to one.
Value
An ordinary serializable list of class spDBL_calibration containing samples, per-conditional diagnostics, settings, and prediction context. No compiled Stan model is stored in the result.
Details
Requires the suggested package rstan and a C++ toolchain on first
compilation. One iteration per emulator draw is an execution experiment,
not converged posterior inference; its samples stay near init. When the
midpoint of the bounds is close to the true value, as in dt_calibration,
use init = "random" to check that results do not depend on the start. Missing observations and new time/grid
locations are not supported in this initial interface.
Examples
if (FALSE) { # interactive() && requireNamespace("rstan", quietly = TRUE)
data("dt_calibration")
d <- dt_calibration
em <- emulator_learn(d$training$input, d$training$responses, d$Nx, d$Ny,
covariance = "sigma2R", episode_window = 2, nsam = 3,
seed = 1)
cal <- calibration_prepare(em, d$lower, d$upper)
fit <- calibration_fit(cal, d$field$z, d$field$U,
locations = d$field$locations, draws = 1:2,
chains = 1, iter = 200, seed = 1)
summary(fit)
}