Introduction to BayGMST

This vignette walks through the full BayGMST workflow end to end, using small example datasets bundled with the package (trimmed subsets of the data used in Bagwell et al., in prep.; see system.file("extdata", package = "BayGMST")). It replaces the config.yml-driven scripts the package was originally built from – see NEWS.md and system.file("legacy-scripts", package = "BayGMST").

library(BayGMST)

1. Load example data

proxy_matrix <- read.csv(
  system.file("extdata", "example_proxy_matrix.csv", package = "BayGMST")
)
forcing_raw <- read.csv(
  system.file("extdata", "example_forcing.csv", package = "BayGMST")
)
instrumental_raw <- read.csv(
  system.file("extdata", "example_instrumental_temperature.csv", package = "BayGMST")
)
# read.csv() mangles "Time"/"Anomaly (deg C)" headers via make.names(); give
# them stable names instead of relying on the mangled spelling.
colnames(instrumental_raw)[1:2] <- c("Time", "Anomaly")

years <- forcing_raw$year
head(proxy_matrix)
#>   year SAm_030  SAm_026 SAm_025 Ocn_095 NAm_186 NAm_104
#> 1 1700  9.2943 -20.9760   0.463 -4.5324   0.652   1.021
#> 2 1701  9.2947 -18.8329   0.474 -4.6960   0.577   0.941
#> 3 1702  9.2951 -18.7600   0.660 -4.6556   0.831   0.982
#> 4 1703  9.2955 -19.9733   0.980 -4.3724   1.045   0.994
#> 5 1704  9.2959 -19.9486   0.735 -4.4295   0.876   0.973
#> 6 1705  9.2963 -21.1983  -0.357 -4.6110   0.672   0.990

2. Reduce the proxy network to a single representative series

calib_years <- instrumental_raw$Time

rp <- reduce_proxies(
  proxy_matrix = proxy_matrix[, -1],
  years        = proxy_matrix$year,
  temp_calib   = instrumental_raw$Anomaly,
  calib_years  = calib_years,
  method       = "PCR",
  # `chunk` must be large enough that every segment (including the last,
  # shortest one) still fully contains the calibration window (1850-2000,
  # 151 years). This toy example only has 301 years total, so we use a
  # single segment (chunk >= length(years)) rather than the package
  # default of 250, which would create a too-short trailing segment here.
  chunk        = nrow(proxy_matrix)
)
rp
#> <baygmst_rp>
#>   Method:   PCR
#>   Years:    1700 to 2000 (n = 301)
#>   Segments: 1
#>   Proxies per segment: 6
#>   Pass to fit_baygmst() directly, or use x$composite$RP1.

rp can be passed to fit_baygmst() directly (it is aligned to the model’s year grid by calendar year, via as_baygmst_proxy()); the raw series lives in rp$composite$RP1 if you need it. You do not have to use reduce_proxies() at all – any reduced or composited proxy series works here; see “Using composites from other packages” below.

3. Transform the radiative forcings

forcing <- transform_forcings(
  G = forcing_raw$CO2,
  V = forcing_raw$volcanic,
  S = forcing_raw$solar
)

4. Align everything onto the common year grid and fit the model

The proxy series is aligned automatically (by calendar year) when you pass the reduce_proxies() output itself; the instrumental series still needs aligning onto years by hand, with NA marking the pre-instrumental years the model will reconstruct:

instrumental_T <- instrumental_raw$Anomaly[match(years, instrumental_raw$Time)]

Fitting requires a working CmdStan installation (via / ); see vignette("cmdstanr", package = "cmdstanr") if you don’t have one yet. The chunk below is skipped if none is found.

fit <- fit_baygmst(
  proxy          = rp,
  instrumental_T = instrumental_T,
  forcing_G      = forcing$G,
  forcing_V      = forcing$V,
  forcing_S      = forcing$S,
  years          = years,
  chains         = 2,
  parallel_chains = 2,
  iter_warmup    = 300,
  iter_sampling  = 1000,
  seed           = 1
)
#> Running MCMC with 2 parallel chains...
#> 
#> Chain 1 Iteration:    1 / 1300 [  0%]  (Warmup) 
#> Chain 2 Iteration:    1 / 1300 [  0%]  (Warmup) 
#> Chain 1 Iteration:  100 / 1300 [  7%]  (Warmup) 
#> Chain 1 Iteration:  200 / 1300 [ 15%]  (Warmup) 
#> Chain 2 Iteration:  100 / 1300 [  7%]  (Warmup) 
#> Chain 1 Iteration:  300 / 1300 [ 23%]  (Warmup) 
#> Chain 1 Iteration:  301 / 1300 [ 23%]  (Sampling) 
#> Chain 2 Iteration:  200 / 1300 [ 15%]  (Warmup) 
#> Chain 1 Iteration:  400 / 1300 [ 30%]  (Sampling) 
#> Chain 2 Iteration:  300 / 1300 [ 23%]  (Warmup) 
#> Chain 2 Iteration:  301 / 1300 [ 23%]  (Sampling) 
#> Chain 1 Iteration:  500 / 1300 [ 38%]  (Sampling) 
#> Chain 2 Iteration:  400 / 1300 [ 30%]  (Sampling) 
#> Chain 2 Iteration:  500 / 1300 [ 38%]  (Sampling) 
#> Chain 1 Iteration:  600 / 1300 [ 46%]  (Sampling) 
#> Chain 2 Iteration:  600 / 1300 [ 46%]  (Sampling) 
#> Chain 1 Iteration:  700 / 1300 [ 53%]  (Sampling) 
#> Chain 2 Iteration:  700 / 1300 [ 53%]  (Sampling) 
#> Chain 1 Iteration:  800 / 1300 [ 61%]  (Sampling) 
#> Chain 2 Iteration:  800 / 1300 [ 61%]  (Sampling) 
#> Chain 1 Iteration:  900 / 1300 [ 69%]  (Sampling) 
#> Chain 2 Iteration:  900 / 1300 [ 69%]  (Sampling) 
#> Chain 1 Iteration: 1000 / 1300 [ 76%]  (Sampling) 
#> Chain 2 Iteration: 1000 / 1300 [ 76%]  (Sampling) 
#> Chain 1 Iteration: 1100 / 1300 [ 84%]  (Sampling) 
#> Chain 2 Iteration: 1100 / 1300 [ 84%]  (Sampling) 
#> Chain 1 Iteration: 1200 / 1300 [ 92%]  (Sampling) 
#> Chain 2 Iteration: 1200 / 1300 [ 92%]  (Sampling) 
#> Chain 1 Iteration: 1300 / 1300 [100%]  (Sampling) 
#> Chain 1 finished in 2.7 seconds.
#> Chain 2 Iteration: 1300 / 1300 [100%]  (Sampling) 
#> Chain 2 finished in 2.8 seconds.
#> 
#> Both chains finished successfully.
#> Mean chain execution time: 2.8 seconds.
#> Total execution time: 2.9 seconds.
summary(fit)
#> Posterior parameter summary:
#>    variable         mean      median          sd         mad          q5
#> 1    alpha0 -0.064974395 -0.06476506 0.012303891 0.012365870 -0.08435527
#> 2    alpha1  0.260156393  0.25947782 0.040732141 0.038997932  0.19289423
#> 3     phi_R  0.418938425  0.41853092 0.057452342 0.056247746  0.32780297
#> 4     phi_T  0.564013796  0.56378831 0.067352862 0.066312139  0.45015466
#> 5     beta0 -0.200368374 -0.20087299 0.034411254 0.033956121 -0.25571501
#> 6     betaG  0.270303591  0.27044588 0.051025865 0.052653442  0.18570099
#> 7     betaS -0.007486763 -0.00730473 0.049062765 0.049040934 -0.08831079
#> 8     betaV  0.060768307  0.06050239 0.017862082 0.017837068  0.03258731
#> 9   sigma_y  0.103874864  0.10365184 0.006215775 0.005982958  0.09417302
#> 10  sigma_z  0.112679176  0.11251385 0.004904413 0.004887977  0.10507218
#>            q95      rhat  ess_bulk  ess_tail
#> 1  -0.04466562 0.9998980 2959.7516 1663.3157
#> 2   0.32960355 1.0012745 1036.8408 1295.7040
#> 3   0.51393069 1.0002138 1300.0730 1523.2904
#> 4   0.67525349 1.0051176  691.2671  875.7668
#> 5  -0.14149558 1.0060919  648.4494  989.5173
#> 6   0.35689154 1.0019895 1089.0862 1411.9967
#> 7   0.07214319 0.9999605 1124.0602 1370.4275
#> 8   0.09078282 0.9992912 1017.2628 1445.9431
#> 9   0.11462814 1.0022676  931.3388 1353.7862
#> 10  0.12124433 1.0018390 2639.1287 1472.1516
#> 
#> Instrumental-period fit performance:
#>       RMSE       MAE        Bias Correlation        R2 R2_detrended
#>  0.1308372 0.1068036 -0.03238583   0.8539404 0.7292143     0.349227

5. Visualize the reconstruction

plot() on a fitted model draws the summary figure used in the PReSto manuscript: the reconstruction on top and the posterior densities of the model parameters below (this needs the ‘patchwork’ package).

plot(fit)

The panels are also available individually:

plot_reconstruction(fit)

plot_trace(fit)

plot_posterior_densities(fit)

6. Cross-validate

cv <- cv_baygmst(
  proxy          = rp,
  instrumental_T = instrumental_T,
  forcing_G      = forcing$G,
  forcing_V      = forcing$V,
  forcing_S      = forcing$S,
  years          = years,
  nfold          = 3,
  chains         = 2,
  parallel_chains = 2,
  iter_warmup    = 300,
  iter_sampling  = 1000,
  seed           = 1
)
#> Running MCMC with 2 parallel chains...
#> 
#> Chain 1 Iteration:    1 / 1300 [  0%]  (Warmup) 
#> Chain 2 Iteration:    1 / 1300 [  0%]  (Warmup)
#> Chain 2 Informational Message: The current Metropolis proposal is about to be rejected because of the following issue:
#> Chain 2 Exception: normal_lpdf: Scale parameter is 0, but must be positive! (in '/var/folders/cm/mzqsdnws41z8tlsr8zcjk6xm0000gq/T/RtmpCbf1Fn/model-10087505c9096.stan', line 75, column 2 to column 40)
#> Chain 2 If this warning occurs sporadically, such as for highly constrained variable types like covariance matrices, then the sampler is fine,
#> Chain 2 but if this warning occurs often then your model may be either severely ill-conditioned or misspecified.
#> Chain 2
#> Chain 1 Iteration:  100 / 1300 [  7%]  (Warmup) 
#> Chain 2 Iteration:  100 / 1300 [  7%]  (Warmup) 
#> Chain 1 Iteration:  200 / 1300 [ 15%]  (Warmup) 
#> Chain 2 Iteration:  200 / 1300 [ 15%]  (Warmup) 
#> Chain 1 Iteration:  300 / 1300 [ 23%]  (Warmup) 
#> Chain 1 Iteration:  301 / 1300 [ 23%]  (Sampling) 
#> Chain 2 Iteration:  300 / 1300 [ 23%]  (Warmup) 
#> Chain 2 Iteration:  301 / 1300 [ 23%]  (Sampling) 
#> Chain 1 Iteration:  400 / 1300 [ 30%]  (Sampling) 
#> Chain 1 Iteration:  500 / 1300 [ 38%]  (Sampling) 
#> Chain 2 Iteration:  400 / 1300 [ 30%]  (Sampling) 
#> Chain 1 Iteration:  600 / 1300 [ 46%]  (Sampling) 
#> Chain 2 Iteration:  500 / 1300 [ 38%]  (Sampling) 
#> Chain 1 Iteration:  700 / 1300 [ 53%]  (Sampling) 
#> Chain 2 Iteration:  600 / 1300 [ 46%]  (Sampling) 
#> Chain 1 Iteration:  800 / 1300 [ 61%]  (Sampling) 
#> Chain 1 Iteration:  900 / 1300 [ 69%]  (Sampling) 
#> Chain 2 Iteration:  700 / 1300 [ 53%]  (Sampling) 
#> Chain 1 Iteration: 1000 / 1300 [ 76%]  (Sampling) 
#> Chain 2 Iteration:  800 / 1300 [ 61%]  (Sampling) 
#> Chain 1 Iteration: 1100 / 1300 [ 84%]  (Sampling) 
#> Chain 1 Iteration: 1200 / 1300 [ 92%]  (Sampling) 
#> Chain 2 Iteration:  900 / 1300 [ 69%]  (Sampling) 
#> Chain 1 Iteration: 1300 / 1300 [100%]  (Sampling) 
#> Chain 1 finished in 2.9 seconds.
#> Chain 2 Iteration: 1000 / 1300 [ 76%]  (Sampling) 
#> Chain 2 Iteration: 1100 / 1300 [ 84%]  (Sampling) 
#> Chain 2 Iteration: 1200 / 1300 [ 92%]  (Sampling) 
#> Chain 2 Iteration: 1300 / 1300 [100%]  (Sampling) 
#> Chain 2 finished in 3.9 seconds.
#> 
#> Both chains finished successfully.
#> Mean chain execution time: 3.4 seconds.
#> Total execution time: 3.9 seconds.
#> 
#> Running MCMC with 2 parallel chains...
#> 
#> Chain 1 Iteration:    1 / 1300 [  0%]  (Warmup) 
#> Chain 2 Iteration:    1 / 1300 [  0%]  (Warmup)
#> Chain 2 Informational Message: The current Metropolis proposal is about to be rejected because of the following issue:
#> Chain 2 Exception: normal_lpdf: Scale parameter is 0, but must be positive! (in '/var/folders/cm/mzqsdnws41z8tlsr8zcjk6xm0000gq/T/RtmpCbf1Fn/model-10087505c9096.stan', line 75, column 2 to column 40)
#> Chain 2 If this warning occurs sporadically, such as for highly constrained variable types like covariance matrices, then the sampler is fine,
#> Chain 2 but if this warning occurs often then your model may be either severely ill-conditioned or misspecified.
#> Chain 2
#> Chain 2 Iteration:  100 / 1300 [  7%]  (Warmup) 
#> Chain 2 Iteration:  200 / 1300 [ 15%]  (Warmup) 
#> Chain 1 Iteration:  100 / 1300 [  7%]  (Warmup) 
#> Chain 2 Iteration:  300 / 1300 [ 23%]  (Warmup) 
#> Chain 2 Iteration:  301 / 1300 [ 23%]  (Sampling) 
#> Chain 2 Iteration:  400 / 1300 [ 30%]  (Sampling) 
#> Chain 1 Iteration:  200 / 1300 [ 15%]  (Warmup) 
#> Chain 1 Iteration:  300 / 1300 [ 23%]  (Warmup) 
#> Chain 1 Iteration:  301 / 1300 [ 23%]  (Sampling) 
#> Chain 2 Iteration:  500 / 1300 [ 38%]  (Sampling) 
#> Chain 1 Iteration:  400 / 1300 [ 30%]  (Sampling) 
#> Chain 1 Iteration:  500 / 1300 [ 38%]  (Sampling) 
#> Chain 2 Iteration:  600 / 1300 [ 46%]  (Sampling) 
#> Chain 1 Iteration:  600 / 1300 [ 46%]  (Sampling) 
#> Chain 1 Iteration:  700 / 1300 [ 53%]  (Sampling) 
#> Chain 2 Iteration:  700 / 1300 [ 53%]  (Sampling) 
#> Chain 1 Iteration:  800 / 1300 [ 61%]  (Sampling) 
#> Chain 1 Iteration:  900 / 1300 [ 69%]  (Sampling) 
#> Chain 2 Iteration:  800 / 1300 [ 61%]  (Sampling) 
#> Chain 1 Iteration: 1000 / 1300 [ 76%]  (Sampling) 
#> Chain 2 Iteration:  900 / 1300 [ 69%]  (Sampling) 
#> Chain 1 Iteration: 1100 / 1300 [ 84%]  (Sampling) 
#> Chain 1 Iteration: 1200 / 1300 [ 92%]  (Sampling) 
#> Chain 2 Iteration: 1000 / 1300 [ 76%]  (Sampling) 
#> Chain 1 Iteration: 1300 / 1300 [100%]  (Sampling) 
#> Chain 2 Iteration: 1100 / 1300 [ 84%]  (Sampling) 
#> Chain 1 finished in 2.2 seconds.
#> Chain 2 Iteration: 1200 / 1300 [ 92%]  (Sampling) 
#> Chain 2 Iteration: 1300 / 1300 [100%]  (Sampling) 
#> Chain 2 finished in 2.7 seconds.
#> 
#> Both chains finished successfully.
#> Mean chain execution time: 2.4 seconds.
#> Total execution time: 2.8 seconds.
#> 
#> Running MCMC with 2 parallel chains...
#> 
#> Chain 1 Iteration:    1 / 1300 [  0%]  (Warmup) 
#> Chain 2 Iteration:    1 / 1300 [  0%]  (Warmup)
#> Chain 2 Informational Message: The current Metropolis proposal is about to be rejected because of the following issue:
#> Chain 2 Exception: normal_lpdf: Scale parameter is 0, but must be positive! (in '/var/folders/cm/mzqsdnws41z8tlsr8zcjk6xm0000gq/T/RtmpCbf1Fn/model-10087505c9096.stan', line 75, column 2 to column 40)
#> Chain 2 If this warning occurs sporadically, such as for highly constrained variable types like covariance matrices, then the sampler is fine,
#> Chain 2 but if this warning occurs often then your model may be either severely ill-conditioned or misspecified.
#> Chain 2
#> Chain 1 Iteration:  100 / 1300 [  7%]  (Warmup) 
#> Chain 2 Iteration:  100 / 1300 [  7%]  (Warmup) 
#> Chain 1 Iteration:  200 / 1300 [ 15%]  (Warmup) 
#> Chain 2 Iteration:  200 / 1300 [ 15%]  (Warmup) 
#> Chain 1 Iteration:  300 / 1300 [ 23%]  (Warmup) 
#> Chain 1 Iteration:  301 / 1300 [ 23%]  (Sampling) 
#> Chain 2 Iteration:  300 / 1300 [ 23%]  (Warmup) 
#> Chain 2 Iteration:  301 / 1300 [ 23%]  (Sampling) 
#> Chain 1 Iteration:  400 / 1300 [ 30%]  (Sampling) 
#> Chain 2 Iteration:  400 / 1300 [ 30%]  (Sampling) 
#> Chain 1 Iteration:  500 / 1300 [ 38%]  (Sampling) 
#> Chain 2 Iteration:  500 / 1300 [ 38%]  (Sampling) 
#> Chain 1 Iteration:  600 / 1300 [ 46%]  (Sampling) 
#> Chain 2 Iteration:  600 / 1300 [ 46%]  (Sampling) 
#> Chain 2 Iteration:  700 / 1300 [ 53%]  (Sampling) 
#> Chain 1 Iteration:  700 / 1300 [ 53%]  (Sampling) 
#> Chain 2 Iteration:  800 / 1300 [ 61%]  (Sampling) 
#> Chain 1 Iteration:  800 / 1300 [ 61%]  (Sampling) 
#> Chain 2 Iteration:  900 / 1300 [ 69%]  (Sampling) 
#> Chain 1 Iteration:  900 / 1300 [ 69%]  (Sampling) 
#> Chain 2 Iteration: 1000 / 1300 [ 76%]  (Sampling) 
#> Chain 1 Iteration: 1000 / 1300 [ 76%]  (Sampling) 
#> Chain 2 Iteration: 1100 / 1300 [ 84%]  (Sampling) 
#> Chain 1 Iteration: 1100 / 1300 [ 84%]  (Sampling) 
#> Chain 2 Iteration: 1200 / 1300 [ 92%]  (Sampling) 
#> Chain 1 Iteration: 1200 / 1300 [ 92%]  (Sampling) 
#> Chain 2 Iteration: 1300 / 1300 [100%]  (Sampling) 
#> Chain 2 finished in 3.3 seconds.
#> Chain 1 Iteration: 1300 / 1300 [100%]  (Sampling) 
#> Chain 1 finished in 3.5 seconds.
#> 
#> Both chains finished successfully.
#> Mean chain execution time: 3.4 seconds.
#> Total execution time: 3.6 seconds.
cv
#> <baygmst_cv>
#>   Folds:  3
#>   R2 (posterior mean, per fold): -3.76, 0.25, -0.24
#>   Median R2: -0.24
plot_cv(cv)

7. Using composites from other packages

reduce_proxies() is one way to produce the model’s proxy input, but not the only one. fit_baygmst()’s proxy equation estimates its own intercept and slope against temperature, so any reduced or composited proxy series on a reasonable scale works – a standardized (z-score) composite or a temperature-anomaly-scale series is appropriate; a raw-unit series with large numerical magnitude should be standardized first.

as_baygmst_proxy() normalizes the common shapes such a series arrives in. In particular, it accepts composite objects of the shape produced by compositing packages in the LiPD ecosystem (such as the in-development compositeR package, whose compositeEnsembles2() is the intended primary pathway for building BayGMST inputs from paleoclimate data): a list carrying $ages (in years BP, i.e. before 1950 CE) and $composite (rows = time steps, columns = ensemble members). Here is a synthetic stand-in:

set.seed(1)
composite_ens <- list(
  ages      = seq(250, -50, by = -1),               # 1700-2000 CE, in yr BP
  composite = matrix(rnorm(301 * 50, sd = 0.2), 301, 50) +
    seq(-0.2, 0.4, length.out = 301)                # 50 ensemble members
)

proxy_input <- as_baygmst_proxy(composite_ens)
proxy_input
#> <baygmst_proxy>
#>   Source:  composite (50 members, median; ages BP)
#>   Years:   1700 to 2000 CE (n = 301)
#>   Ensemble: collapsed from 50 members
#>   Range:   [-0.247, 0.487]

Ages are converted to calendar years and the ensemble is collapsed to its median series (compositing uncertainty is therefore not yet propagated into the posterior; the object records n_ensemble so this can become an ensemble-aware pathway in a future release). The result can be passed straight to fit_baygmst(proxy = proxy_input, ...), which aligns it to years by calendar year and errors informatively if any requested year is not covered. Bare numeric vectors, data.frames with year and value columns, and time-by-ensemble matrices work the same way – see ?as_baygmst_proxy.

Known limitations

See NEWS.md for the modeling decisions and known limitations of this release (for example, reduce_proxies(method = "SIR") is experimental). The data in this vignette are synthetic, so its reconstructions should not be over-interpreted.