Coerce a reduced-proxy series into BayGMST's input format
Source:R/proxy_input.R
as_baygmst_proxy.RdNormalizes the many shapes a reduced/composited proxy series can arrive
in – the output of reduce_proxies(), a plain data.frame, a bare
vector, a time-by-ensemble matrix, or a composite object from another
package (such as a paleoComposite from the in-development 'compositeR'
package) – into a single, year-aware "baygmst_proxy" object that
fit_baygmst() and cv_baygmst() accept directly and align by calendar
year (rather than by position).
Usage
as_baygmst_proxy(x, ...)
# S3 method for class 'baygmst_proxy'
as_baygmst_proxy(x, ...)
# S3 method for class 'baygmst_rp'
as_baygmst_proxy(x, ...)
# S3 method for class 'numeric'
as_baygmst_proxy(x, years, ...)
# S3 method for class 'matrix'
as_baygmst_proxy(x, years, collapse = c("median", "mean"), ...)
# S3 method for class 'data.frame'
as_baygmst_proxy(x, ...)
# S3 method for class 'list'
as_baygmst_proxy(
x,
age_units = c("BP", "CE"),
collapse = c("median", "mean"),
...
)Arguments
- x
The object to coerce. Supported inputs:
baygmst_rpThe output of
reduce_proxies(); uses its$compositeseries.data.frameMust contain a year column (named
yearorYear) and exactly one other numeric column (e.g. theexample_proxy.csvshipped ininst/extdata, with columnsYear, RP1).numericvectorOne value per element of
years, which must also be supplied.matrix(ordata.frameof ensemble columns)Rows are time steps (matching
years), columns are ensemble members; collapsed to a single series withcollapse.- composite
list Any list with elements
$agesand$composite(rows = time steps of$ages, columns = ensemble members), the shape produced by compositing packages in the LiPD ecosystem (e.g.compositeR::compositeEnsembles2()). Ages are assumed to be in years BP (before present, i.e. before 1950 CE) unlessage_units = "CE". The ensemble is collapsed withcollapse.
- ...
Passed between methods.
- years
Numeric vector of calendar years (CE). Required when
xcarries no time axis of its own (bare vectors and matrices); ignored otherwise.- collapse
How to collapse an ensemble (matrix or composite list) to a single series:
"median"(default) or"mean", taken across ensemble members within each time step, ignoringNAs. Time steps whose collapsed value is not finite (e.g. bins no record covers) are dropped with a message.- age_units
For composite lists only:
"BP"(default; ages are years before 1950 CE and are converted viayear = 1950 - age) or"CE"(ages are already calendar years).
Value
An object of class "baygmst_proxy": a data.frame with
columns year (ascending) and proxy, plus attributes source (a
short label for where the series came from) and n_ensemble (the
number of ensemble members collapsed; 1L for deterministic inputs).
Scale expectations
The BayGMST 'Stan' model regresses the proxy series on temperature with an estimated intercept and slope, so the proxy does not need to be pre-calibrated to temperature units. The (weakly informative) priors do, however, assume the series is on roughly unit scale: a standardized (z-score) composite or a temperature-anomaly-scale series is appropriate; a raw-unit series (per mil, mm, ...) with large numerical magnitude should be standardized first.
Uncertainty
In this version the ensemble dimension is collapsed before fitting, so
compositing/ensemble uncertainty is not propagated into the posterior.
A future release may add an ensemble-aware fitting pathway; the
"baygmst_proxy" object records n_ensemble so existing code will not
need to change shape when it does.
Examples
# from a bare vector
p <- as_baygmst_proxy(rnorm(100), years = 1901:2000)
# from a data.frame like inst/extdata/example_proxy.csv
df <- data.frame(Year = 1901:2000, RP1 = rnorm(100))
p <- as_baygmst_proxy(df)
# from a composite ensemble with ages in yr BP (compositeR-style)
comp <- list(
ages = seq(950, 0, by = -10), # 1000-1950 CE
composite = matrix(rnorm(96 * 20), 96, 20) # 20 ensemble members
)
p <- as_baygmst_proxy(comp)
head(p)
#> <baygmst_proxy>
#> Source: composite (20 members, median; ages BP)
#> Years: 1000 to 1050 CE (n = 6)
#> Ensemble: collapsed from 20 members
#> Range: [-0.422, 0.665]