Generate a Bayesian Reconstruction Age Model (Bacon) and add it into a LiPD object

This is a high-level function that uses Bchron to simulate an age model, and stores this as an age-ensemble in a model in chronData. If needed input variables are not entered, and cannot be deduced, it will run in interactive mode. See Haslett and Parnell (2008) doi:10.1111/j.1467-9876.2008.00623.x for details.

runBchron(
  L,
  chron.num = NA,
  meas.table.num = NA,
  site.name = L$dataSetName,
  model.num = NA,
  cal.curves = NA,
  iter = 10000,
  outlier.probs = 0.05,
  ask = TRUE,
  lab.id.var = "labID",
  age.14c.var = "age14C",
  age.14c.uncertainty.var = "age14CUnc",
  age.var = "age",
  age.uncertainty.var = "ageUnc",
  depth.var = "depth",
  reservoir.age.14c.var = "reservoirAge",
  reservoir.age.14c.uncertainty.var = "reservoirAge14C",
  rejected.ages.var = "rejected",
  depth.units = "cm",
  which.table = NA,
  ...
)

Arguments

L

A LiPD object - an R serialization of a single LiPD file. It's a list, and is typically created by `readLipd()`

chron.num

the number of the chronData object that you'll be working in

meas.table.num

an integer that corresponds to paleo.num measurementTable has the variable you want?

site.name

the name of the site

model.num

chron.numModel do you want to use?

cal.curves

The calibration curves to be used. Enter either "marine20", intcal20", "shcal20" or "normal". Will prompt if not provided.

iter

number of iterations to use in bchron (default = 10000)

outlier.probs

probability of outliers amongst the dates

ask

ask for user input? (True/False)

lab.id.var

Lab Id variable name

age.14c.var

Radiocarbon age variable name

age.14c.uncertainty.var

Radiocarbon age uncertainty variable name

age.var

Calibrated age variable name

age.uncertainty.var

Calibrated age uncertainty variable name

depth.var

Depth variable name

reservoir.age.14c.var

Reservoir age variable name

reservoir.age.14c.uncertainty.var

Reservoir age uncertainty variable name

rejected.ages.var

Rejected ages variable name

depth.units

units for depth

which.table

deprecated. Use meas.table.num instead.

...

Arguments passed on to Bchron::Bchronology

ages: A vector of ages provided in years before 1950.
ageSds: A vector of 1-sigma values for the ages given above
positions: Position values (e.g. depths) for each age. In the case of layers of non-zero thickness, this should be the middle value of the slice
positionThicknesses: Thickness values for each of the positions. The thickness value should be the full thickness value of the slice. By default set to zero.
calCurves: A vector of values containing either intcal20, shcal20, marine20, or normal (older calibration curves are supposed such as intcal13). Should be the same length the number of ages supplied. Non-standard calibration curves can be used provided they are supplied in the same format as those previously mentioned and are placed in the same directory. Normal indicates a normally-distributed (non-14C) age.
ids: ID names for each age
outlierProbs: A vector of prior outlier probabilities, one for each age. Defaults to 0.01
predictPositions: A vector of positions (e.g. depths) at which predicted age values are required. Defaults to a sequence of length 100 from the top position to the bottom position
pathToCalCurves: File path to where the calibration curves are located. Defaults to the system directory where the 3 standard calibration curves are stored.
artificialThickness: Amount to add to the thickness values in the case of equal positions with no positionThicknesses. Bchron may fail if positionThicknesses are zero and some positions are repeated. This value is added on to the zero thicknesses (only in the case of repeated positions) to stop this failure.
allowOutside: Whether to allow calibrations to run outside the range of the calibration curve. By default this is turned off as calibrations outside of the range of the calibration curve can cause severe issues with probability ranges of calibrated dates
iterations: The number of iterations to run the procedure for
burn: The number of starting iterations to discard
thin: The step size for every iteration to keep beyond the burn-in
extractDate: The top age of the core. Used for extrapolation purposes so that no extrapolated ages go beyond the top age of the core. Defaults to the current year
maxExtrap: The maximum number of extrapolations to perform before giving up and setting the predicted ages to NA. Useful for when large amounts of extrapolation are required, i.e. some of the predictPositions are a long way from the dated positions
thetaStart: A set of starting values for the calendar ages estimated by Bchron. If NULL uses a function to estimate the ages. These should be in the same units as the posterior ages required. See example below for usage.
thetaMhSd: The Metropolis-Hastings standard deviation for the age parameters
muMhSd: The Metropolis-Hastings standard deviation for the Compound Poisson-Gamma mean
psiMhSd: The Metropolis-Hastings standard deviation for the Compound Poisson-Gamma scale
ageScaleVal: A scale value for the ages. Bchronology works best when the ages are scaled to be approximately between 0 and 100. The default value is thus 1000 for ages given in years.
positionEps: A small value used to check whether simulated positions are far enough apart to avoid numerical underflow errors. If errors occur in model runs (e.g. missing value where TRUE/FALSE needed increase this value)
positionNormalise: Whether to normalise the position values. Bchronology works best when the positions are normalised to be between 0 and 1 The default value is TRUE

Value

L. The single LiPD object that was entered, with methods, ensembleTable, summaryTable and distributionTable added to the chronData model.

Author

Deborah Khider

Andrew Parnell

Nick McKay

Examples

if (FALSE) { # \dontrun{
#Run in interactive mode:
L = runBchron(L)

#Run in noninteractive mode:
L = runBchron(L,
             chron.num = 1, 
             site.name = "MyWonderfulSite",
             model.num = 3, 
             cal.curves = "marine20") 
} # }