R/bacon.lipd.R
runBacon.RdThis is a high-level function that uses Bacon 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 Blaauw and Christen (2011) doi:10.1214/11-BA618 for details.
runBacon(
L,
chron.num = NA,
meas.table.num = NA,
bacon.dir = NA,
site.name = L$dataSetName,
model.num = NA,
remove.rejected = TRUE,
overwrite = TRUE,
cc = NA,
max.ens = 1000,
use.marine = NULL,
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",
ask.reservoir = TRUE,
bacon.thick = NA,
bacon.acc.mean = NA,
...
)a LiPD object
the number of the chronData object that you'll be working in
an integer that corresponds to paleo.num measurementTable has the variable you want?
the directory where Bacon is installed on this computer.
the name used for the bacon model (and directories)
chron.numModel do you want to use?
don't write out dates that are marked as rejected
overwrite files and directories
An integer, or vector of integers corresponding to age that describes the calibration curve. You can specify here (see below) or if it's NA the code will guess based on archiveType
cc=1 IntCal20
cc=2 MarineCal20
cc=3 SHCal20
the maximum number of ensembles to load in (default = 1000)
use the marine 13C curve? (yes or no, or NULL to choose)
Lab Id variable name
Radiocarbon age variable name
Radiocarbon age uncertainty variable name
Calibrated age variable name
Calibrated age uncertainty variable name
Depth variable name
Reservoir age variable name
Reservoir age uncertainty variable name
Rejected ages variable name
ask about reservoir corrections
thickness parameter to pass to bacon (How thick is each chunk to model)
prior mean accumulation rate estimate for bacon
Arguments passed on to rbacon::Bacon
coreName of the core, given using quotes. Defaults to one of the cores provided with rbacon, core="MSB2K".
An alternative core provided with this package is RLGH3 (Jones et al., 1989).
To run your own core, produce a .csv file with the dates as outlined in the manual, add a folder with the core's name to the default directory for cores (see coredir), and save the .csv file there. For example, the file's location and name could be Bacon_runs/MyCore/MyCore.csv. Then run Bacon as follows: Bacon("MyCore")
thickBacon will divide the core into sections of equal thickness specified by thick (default thick=5).
coredirFolder where the core's files core are and/or will be located. This will be a folder with the core's name, within either the folder coredir='Bacon_runs/', or the folder Cores/ if it already exists within R's working directory, or a custom-built folder. For example, use coredir="." to place the core's folder within the current working directory, or coredir="F:" if you want to put the core's folder and files on a USB drive loaded under F:.
Thinner (and thus more) sections will result in smoother age-models, but too many sections can cause `run-away' models.
probConfidence interval to report. This should lie between 0 and 1, default 0.95 (95 %).
d.minMinimum depth of age-depth model (use this to extrapolate to depths higher than the top dated depth).
d.maxMaximum depth of age-depth model (use this to extrapolate to depths below the bottom dated depth).
add.bottomAdd a model section at the bottom of the core, in order to ensure the bottommost date is taken into account. Default add.bottom=TRUE. This is a new option and can cause age-models to differ from previous version. Please re-run the model if in doubt.
d.byDepth intervals at which ages are calculated. Defaults to d.by=1. Please ensure that the value of d.by is smaller than that of 'thick', otherwise plots might turn out wrong.
seedSeed used for C++ executions. If it is not assigned (seed=NA; default) then the seed is set by system.
depths.fileBy default, Bacon will calculate the ages for the depths d.min to d.max in steps of d.by.
If depths.file=TRUE, Bacon will read a file containing the depths for which you require ages.
This file, containing the depths in a single column without a header, should be stored within coredir,
and its name should start with the core's name and end with `_depths.txt'. Then specify depths.file=TRUE (default FALSE). See also depths.
depthsBy default, Bacon will calculate the ages for the depths d.min to d.max in steps of d.by.
Alternative depths can be provided as, e.g., depths=seq(0, 100, length=500) or as a file, e.g., depths=read.table("CoreDepths.txt". See also depths.file.
depth.unitUnits of the depths. Defaults to depth.unit="cm".
age.unitUnits of the ages. Defaults to age.unit="yr".
unitDeprecated and replaced by depth.unit.
acc.shapeThe prior for the accumulation rate consists of a gamma distribution with two parameters.
Its shape is set by acc.shape (default acc.shape=1.5; higher values result in more peaked shapes).
acc.meanThe accumulation rate prior consists of a gamma distribution with two parameters. Its mean is set by acc.mean (default acc.mean=20 yr/cm (or whatever age or depth units are chosen),
which can be changed to, e.g., 5, 10 or 50 for different kinds of deposits). Multiple values can be given in case of hiatuses or boundaries, e.g., Bacon(hiatus.depths=23, acc.mean=c(5,20))
mem.strengthThe prior for the memory (dependence of accumulation rate between neighbouring depths) is a beta distribution, which looks much like the gamma distribution.
but its values are always between 0 (no assumed memory) and 1 (100% memory). Its default settings of mem.strength=10
(higher values result in more peaked shapes) allow for a large range of posterior memory values. Please note that the default memory prior has been updated from rbacon version 2.5.1 on, to repair a bug.
mem.meanThe prior for the memory is a beta distribution, which looks much like the gamma distribution but
its values are always between 0 (no assumed memory) and 1 (100% memory). Its default settings of mem.mean=0.5
allow for a large range of posterior memory values. Please note that the default memory prior has been updated from rbacon version 2.5.1. on, to repair a bug.
boundaryThe assumed depths of any boundary, which divides sections of different accumulation rate regimes (e.g., as indicated by major change in the stratigraphy). No hiatus is assumed between these sections, and memory is reset crossing the boundary. Different accumulation priors can be set for the sections above and below the boundary, e.g., acc.mean=c(5, 20). See also hiatus.depths, mem.mean, acc.mean and acc.shape. Setting many boundaries might not work, and having more than one boundary per model section (see 'thick') might not work either.
hiatus.depthsThe assumed depths for any hiatus should be provided as, e.g.,
hiatus.depths=20 for one at 20cm depth, and hiatus.depths=c(20,40) for two hiatuses at 20 and 40 cm depth.
hiatus.maxThe prior for the maximum length of the hiatus. Hiatus length is a uniform distribution, with equal probabilities between 0 and hiatus.max yr (or whatever other age.unit is chosen).
addAdd a value to the maximum hiatus length if a boundary is chosen. Defaults to 100 yr (or whatever other age unit is chosen). Can be adapted if Bacon complains that the parameters are out of support.
afterSets a short section above and below hiatus.depths within which to calculate ages. For internal calculations - do not change.
cc1For northern hemisphere terrestrial 14C dates (IntCal20).
cc2For marine 14C dates (Marine20).
cc3For southern hemisphere 14C dates (SHCal20).
cc4Use an alternative curve (3 columns: cal BP, 14C age, error, separated by white spaces and saved as a plain-text file). See cc.dir.
cc.dirDirectory where the calibration curves for C14 dates cc are located. By default uses the location of the rintcal package which provides the calibration curves. If you want to use custom-made calibration curves, first set up a new folder using the function new.ccdir() in the rintcal package, e.g., new.ccdir="MyCurves", then place the custom curve in that folder using mix.ccurves(, cc.dir="MyCurves", save=TRUE).
postbombUse a postbomb curve for negative (i.e. postbomb) 14C ages. 0 = none, 1 = NH1, 2 = NH2, 3 = NH3, 4 = SH1-2, 5 = SH3
delta.RMean of core-wide age offsets (e.g., regional marine offsets).
delta.STDError of core-wide age offsets (e.g., regional marine offsets).
t.aThe dates are treated using the t distribution (Christen and Perez 2009) by default (normal=FALSE).
This t-distribution has two parameters, t.a and t.b, set at 3 and 4 by default (see Christen and Perez, 2010).
If you want to assign narrower error distributions (more closely resembling the normal distribution), set t.a and t.b at for example 33 and 34 respectively (e.g., for specific dates in your .csv file).
For symmetry reasons, t.a must always be equal to t.b-1.
t.bThe dates are treated using t distribution by default (normal=FALSE).
The t-distribution has two parameters, t.a and t.b, set at 3 and 4 by default (see Christen and Perez, 2009).
If you want to assign narrower error distributions (more closely resembling the normal distribution), set t.a and t.b at for example 33 and 34 respectively (e.g., for specific dates in your .csv file).
For symmetry reasons, t.a must always be equal to t.b-1.
normalBy default, Bacon uses the t-distribution to treat the dates. Use normal=TRUE to use the normal/Gaussian distribution. This will generally give higher weight to the dates.
suggestIf initial analysis of the data indicates abnormally slow or fast accumulation rates, Bacon will suggest to change the prior.
accept.suggestionsAutomatically accept the suggested values. Use with care. Default accept.suggestions=FALSE.
Also, if the length of the core would cause too few or too many sections with the default settings, Bacon will suggest an alternative section thickness thick.
Accept these suggested alternative settings by typing "y" (or "yes please" if you prefer to be polite), or leave as is by typing "n" (or anything else, really). To get rid of these suggestions, use suggest=FALSE.
reswarnBacon will warn you if the number of sections lies outside the safe range (default between 10 and 200 sections;
reswarn=c(10,200)). Too few sections could lead to an `elbowy' model while with too many sections the modelling process can get lost,
resulting in age-models far away from the dated depths.
rememberBacon will try to remember which settings you have applied to your cores (default remember=TRUE). If you run into inconsistencies or other problems,
try running your core again with remember=FALSE, or, start cleanly by typing Bacon.cleanup().
askBy default Bacon will ask you to confirm that you want to run the core with the provided settings. Disable this using ask=FALSE (e.g., for batch runs).
runIn order to load an existing Bacon run instead of producing a new one, you can use run=FALSE.
defaultsName of the file containing settings for the core. For internal use only - do not change.
sepSeparator between the fields of the plain text file containing the dating information. Default sep=",".
decCharacter for decimal points. Default to dec=".".
runnameText to add to the corename for specific runs, e.g., runname="MyCore_Test1".
slumpUpper and lower depths of any sections of assumed abrupt accumulation, that require excising before age-modelling (and adding after age-modelling). Requires pairs of depths, e.g., slump=c(10,15,60,67) for slumps at 67-60 and 15-10 cm core depth.
removeWhether or not to remove depths within slumps. Defaults to remove=FALSE.
BCADThe calendar scale of graphs and age output-files is in cal BP (calendar or calibrated years before the present, where the present is AD 1950) by default, but can be changed to BC/AD using BCAD=TRUE.
ssizeThe amount of iterations to store at the end of the MCMC run. Default 4000; decrease for faster (but less reliable) runs or increase for cores where the MCMC mixing (panel at upper-left corner of age-model graph) appears problematic.
th0Starting years for the MCMC iterations. These are randomly chosen by default.
burninAmount of initial, likely sub-optimal MCMC iterations that will be removed.
youngest.ageMinimum age limit for Bacon runs, default at current year in cal BP. To set plot limits, use age.min instead.
oldest.ageMaximum age limit for Bacon runs, default at 1,000,000 cal BP. To set plot limits, use age.max instead.
MinAgeDeprecated - use youngest.age instead.
MaxAgeDeprecated - use oldest.age instead.
cutoffAvoid plotting very low probabilities of date distributions (default cutoff=0.001).
plot.pdfProduce a pdf file of the age-depth plot. Defaults to plot.pdf=TRUE after a Bacon run.
darkDarkness of the greyscale age-depth model. The darkest grey value is dark=1 by default.
Lower values will result in lighter grey but values >1 are not allowed.
date.resDate distributions are plotted using date.res=100 segments by default.
age.resResolution or amount of greyscale pixels to cover the age scale of the age-model plot. Default yr.res=200.
yr.resDeprecated - use age.res instead
close.connectionsInternal option to close connections after a run. Default close.connections=TRUE.
older.thanan option to enable dates at the limit of C-14 dating. If there are older.than dates, they tell us that the core should be older than a certain age at that depth. For example, if the 7th and 8th dates in the core's .csv file are older-than dates, use as older.than=c(7,8). The MCMC run could be problematic if the older-than ages do not fit with the other information.
younger.thanan option to provide younger-than ages, for example a historical pollen marker. If there are younger-than dates, they tell us that the core should be younger than a certain age at that depth. For example, if the 7th and 8th dates in the core's .csv file are younger.than dates, use as younger.than=c(7,8). The MCMC run could be problematic if the younger.than ages do not fit with the other information.
save.elbowagesIf you want to have a file with the MCMC-derived ages for all the age-depth model's elbows, set save.elbowages=TRUE and a file with the ages will be saved in the core's folder, starting with the core name, followed by its number of sections, d.min, and section thickness, and ending in "_elbowages.txt".
verboseProvide feedback on what is happening (default verbose=TRUE).
L The single LiPD object that was entered, with methods, ensembleTable, summaryTable and distributionTable added to the chronData model.
Other Bacon:
getBaconDir(),
loadBaconOutput(),
sampleBaconAges(),
setBaconDir(),
writeBacon()
if (FALSE) { # \dontrun{
#Run in interactive mode:
L = runBacon(L)
#Run in noninteractive mode, describing everything:
L = runBacon(L,chron.num = 1,
meas.table.num = 1,
model.num = 3,
bacon.dir = "~/Bacon/",
site.name = "MSB2K",
cc = 1)
} # }