`R/run.bchron.LiPD.R`

`runBchron.Rd`

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,
...
)
```

- 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`

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

```
if (FALSE) {
#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")
}
```