Changelog
Source:NEWS.md
BayGMST 0.1.0
Initial packaging of the BayGMST model. Previously this repository was a collection of top-level analysis scripts (R_scripts/, utils/) driven by config.yml; this release converts that logic into a documented, installable R package with an explicit function API. The original scripts are preserved under inst/legacy-scripts/ for provenance, changed only where CRAN policy requires (they no longer clear the workspace, and they restore par()).
New
-
transform_forcings()– ported from the normalization block inBayGMST_v1.0.R. -
reduce_proxies()– ported fromutils/PAGES2k_reducedProxy_UNSC.R. Supports"PCR","LASSO","sPCR", and"SPLS"."SIR"is included but marked experimental (see “Known limitations” below). It applies themax_na_fracmissingness screen before zero-filling gaps, the order of Barboza et al.’s original script (PAGES2k_reducedProxy_UNSC_OLD.R). A later edit of that script (PAGES2k_reducedProxy_UNSC.R) zero-filled first, which hid internal gaps from the screen and let sparse records enter the regression mostly as zeros; on large proxy pools that reduced proxy stoppedfit_baygmst()from converging. The output’sproxieselement lists the records each segment used. -
fit_baygmst()– ported from the data-prep andcmdstanrsampling block inBayGMST_v1.0.R. Returns abaygmst_fitobject instead of relying on variables left in the global environment. -
reconstruct()– extracts a tidy reconstructiondata.framefrom abaygmst_fit(equivalent to thegmst_reconstruction_data.csvproduced by the original script), without writing to disk. -
cv_baygmst()– ported from the k-fold loop incv_v0.1.R. -
plot_reconstruction(),plot_trace(),plot_posterior_densities(),plot_cv()– returnggplotobjects instead of callingggsave()as a side effect. -
print.baygmst_fit(),summary.baygmst_fit(),print.baygmst_cv()S3 methods. -
plot.baygmst_fit():plot(fit)reproduces the combined figure of the original script and the PReSto manuscript (reconstruction on top; grouped posterior densities ofalpha1, the forcing sensitivities, and the AR(1) coefficients below). Requires ‘patchwork’ (Suggests). -
as_baygmst_proxy()– normalizes the shapes a reduced/composited proxy series can arrive in (the output ofreduce_proxies(), adata.frame, a bare vector, a time-by-ensemble matrix, or a composite object from another package such as a ‘compositeR’paleoComposite, with ages in yr BP converted to calendar years and ensembles collapsed to a median series) into a year-awarebaygmst_proxyobject.fit_baygmst()andcv_baygmst()accept these objects (or anything coercible) directly and align them toyearsby calendar year; the original bare-vector, positional interface is unchanged. Ensemble inputs are collapsed before fitting in this release (compositing uncertainty is not yet propagated); the object recordsn_ensemblefor a future ensemble-aware pathway. -
reduce_proxies()output now carries classbaygmst_rp(same list structure as before) with aprint()method. -
summary()on a fitted model now reports convergence diagnostics (max_rhat,min_ess_bulk) and its print method warns prominently whenmax_rhat > 1.05(surfaced by a Holocene-scale stress test in which a poorly identified fit previously printed without complaint). -
plot_trace()andplot_posterior_densities()no longer emit “Dropping ‘draws_df’ class” warnings. - New vignette
baygmst-modeldescribing the statistical model (data and process levels, priors, forcing provenance, and the mapping to the Stan code), ported from the hand-typeset draft reference manual’s “Statistical Model” section. It explicitly credits the reduced-proxy Bayesian framework of Barboza et al. (2014, 2019) and Wang (2020).
Fixed relative to the original scripts
-
load_proxies()’smatch.arg()choices omitted"sPCR", even thoughconfig.ymland the bundleddata/barboza_rps/RP_new_All_sPCR.csvboth support it – selectingsPCRvia the original script would error.reduce_proxies(method = "sPCR")now works. - Removed the hardcoded, machine-specific path
/Users/tylerbagwell/Documents/GitHub/BayGMST_R/data/forcings_with_prediction_HanWang.csvfrom the cross-validation logic. That block (Forcings.projections/df_prj) was also dead code in the original script – built but never referenced again – so it was not ported. - Removed the
rm(list = ls())call at the top ofutils/PAGES2k_reducedProxy_UNSC.R. A package function must never clear its caller’s global environment. - Package functions no longer write files (CSV/PNG) by default. Callers decide whether and where to save outputs, per CRAN policy on functions writing to the filesystem.
Modeling decisions and known limitations
The following were reviewed and signed off by the package authors before the first CRAN release:
-
y[NT_mis]/z[NT_mis]indexing, kept as is. Insrc/stan/baygmst.stan, the observed-period fitted-value block uses the countNT_misas a vector index att == 1. Because missing (pre-instrumental) years always occupy positions1:NT_mis, this is numerically equivalent toy[idx_mis[NT_mis]]/z[idx_mis[NT_mis]]and is not a live bug. It would be wrong only if missing and observed years were interleaved, and it affects onlyy_ins_fitted[1], a posterior-predictive diagnostic, not the parameter posteriors or the reconstructiony_mis. -
Instrumental temperature is treated as error-free, as in the models of Barboza et al. (2014) and Wang (2020). See
vignette("baygmst-model"). -
Cross-validation R^2 is the fully Bayesian posterior mean of Stan’s
r2_cv, rather than the plug-in estimate of the originalcv_v0.1.R. The two are close but not identical. -
reduce_proxies(method = "SIR")is experimental and unvalidated and warns on use. The original SIR implementation depended on legacy libraries that are no longer available, so it could not be used as a reference. -
Volcanic forcing coefficient.
vol_coef = 25(W m^-2 per unit AOD) is attributed to Hansen et al. (2005); the value is corroborated via IPCC AR5. - Several packages
library()-loaded by the original scripts (car,fda,ggmap,maps) had no evident corresponding usage in the code as written, so they were not carried intoImports/Suggests. -
data/HadCRUT.5.1.0.0.analysis.anomalies.ensemble_mean.nc(31 MB) was not read by any ported function and has been removed from the repository tree (it remains in git history), along with the compiled CmdStan binaries ininst/legacy-scripts/and theoutputs/build artifacts. The legacyconfig.ymlmoved toinst/legacy-scripts/config.yml; no package function reads it. - The hand-typeset draft reference manual (
reference-manual/) was retired. Its model description lives invignette("baygmst-model"), and the reference manual is the one R builds fromman/.