Package 'clam'

clam

Description

Classical (non-Bayesian) age-depth modelling.

Author(s)

Maintainer: Maarten Blaauw [email protected] (ORCID)

Other contributors:

• J. Andres Christen (ORCID) [contributor]

• Judith Esquivel Vazquez [contributor]

• Simon Goring [contributor]

---

Add dates to age-depth plots

Description

Add dated depths to plots, e.g. to show dates that weren't used in the age-depth model

Usage

add.dates(
  mn,
  sdev,
  depth,
  cc = 1,
  above = 0.001,
  exx = 50,
  normal = TRUE,
  normalise = TRUE,
  t.a = 3,
  t.b = 4,
  age.res = 100,
  times = 20,
  col = rgb(1, 0, 0, 0.5),
  border = rgb(1, 0, 0, 0.5),
  rotate.axes = FALSE,
  mirror = TRUE,
  up = TRUE,
  BCAD = FALSE
)

Arguments

mn	Reported mean of the date. Can be multiple dates.
sdev	Reported error of the date. Can be multiple dates.
depth	Depth of the date.
cc	The calibration curve to use: cc=1 for IntCal20 (northern hemisphere terrestrial), cc=2 for Marine20 (marine), cc=3 for SHcal20 (southern hemisphere terrestrial), cc=0 for none (dates that are already on the cal BP scale).
above	Threshold for plotting of probability values. Defaults to above=1e-3.
exx	Exaggeration of probability distribution plots. Defaults to exx=50.
normal	By default, Bacon uses the student's t-distribution to treat the dates. Use normal=TRUE to use the normal/Gaussian distribution. This will generally give higher weight to the dates.
normalise	By default, the date is normalised to an area of 1 (normalise=TRUE).
t.a	The dates are treated using the student's t distribution by default (normal=FALSE). The student's 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.b	The dates are treated using the student's t distribution by default (normal=FALSE). The student's 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.
age.res	Resolution of the date's distribution. Defaults to date.res=100.
times	The extent of the range to be calculated for each date. Defaults to times=20.
col	The colour of the ranges of the date. Default is semi-transparent red: col=rgb(1,0,0,.5).
border	The colours of the borders of the date. Default is semi-transparent red: border=rgb(1,0,0,0.5).
rotate.axes	The default of plotting age on the horizontal axis and event probability on the vertical one can be changed with rotate.axes=TRUE.
mirror	Plot the dates as 'blobs'. Set to mirror=FALSE to plot simple distributions.
up	Directions of distributions if they are plotted non-mirrored. Default up=TRUE.
BCAD	The calendar scale of graphs is in cal BP by default, but can be changed to BC/AD using BCAD=TRUE.

Details

Sometimes it is useful to add additional dating information to age-depth plots, e.g., to show outliers or how dates calibrate with different estimated offsets.

Value

A date's distribution, added to an age-depth plot.

Author(s)

Maarten Blaauw, J. Andres Christen

Examples

base_temp_dir <- tempdir()
  clam_dir <- file.path(base_temp_dir, "clam_runs")
  dir.create(clam_dir, recursive = TRUE, showWarnings = FALSE)
  clam(, coredir=clam_dir, ask=FALSE)
  add.dates(5000, 100, 60)

---

clam: Classical Age-Depth Modelling of Cores from Deposits

Description

Performs 'classical' age-depth modelling of dated sediment deposits - prior to applying more sophisticated techniques such as Bayesian age-depth modelling. Any radiocarbon dated depths are calibrated. Age-depth models are constructed by sampling repeatedly from the dated levels, each time drawing age-depth curves. Model types include linear interpolation, linear or polynomial regression, and a range of splines. See Blaauw (2010). <doi:10.1016/j.quageo.2010.01.002>.

Produce age-depth models for cores with dated depths.

Usage

clam(
  core = "Example",
  type = 1,
  smooth = NULL,
  prob = 0.95,
  its = 1000,
  coredir = NULL,
  ask = TRUE,
  wghts = 1,
  cc = 1,
  cc1 = "3Col_intcal20.14C",
  cc2 = "3Col_marine20.14C",
  cc3 = "3Col_shcal20.14C",
  cc4 = "mixed.14C",
  postbomb = FALSE,
  pb1 = "postbomb_NH1.14C",
  pb2 = "postbomb_NH2.14C",
  pb3 = "postbomb_NH3.14C",
  pb4 = "postbomb_SH1-2.14C",
  pb5 = "postbomb_SH3.14C",
  ccdir = "",
  outliers = NULL,
  ignore = NULL,
  youngest = NULL,
  extradates = NULL,
  slump = NULL,
  est = 1,
  calibt = FALSE,
  mixed.effect = FALSE,
  dmin = NULL,
  dmax = NULL,
  every = 1,
  yrmin = NULL,
  yrmax = NULL,
  yrsteps = 1,
  pbsteps = 0.01,
  hpdsteps = 1,
  BCAD = FALSE,
  decimals = 0,
  cmyr = FALSE,
  ageofdepth = NULL,
  depth = "cm",
  depthseq = NULL,
  depths.file = FALSE,
  thickness = 1,
  hiatus = NULL,
  remove.reverse = 0.5,
  times = 5,
  sep = ",",
  ext = ".csv",
  runname = NULL,
  storedat = TRUE,
  threshold = 1e-06,
  proxies = FALSE,
  revaxes = FALSE,
  revd = TRUE,
  revyr = TRUE,
  calhght = 0.3,
  maxhght = 0.01,
  mirror = TRUE,
  plotrange = TRUE,
  bty = "l",
  mar = c(3.5, 3, 2, 1),
  mgp = c(2, 1, 0),
  plotpdf = TRUE,
  plotpng = TRUE,
  greyscale = NULL,
  yrlab = NULL,
  dlab = NULL,
  calcol = rgb(0, 0.5, 0.5, 0.5),
  C14col = rgb(0, 0, 1, 0.5),
  outcol = "red",
  outlsize = 1,
  bestcol = "black",
  rangecol = rgb(0, 0, 0, 0.3),
  slumpcol = grey(0.75),
  plotname = TRUE,
  ash = FALSE,
  rule = 1
)

Arguments

core	Name of the core, given using quotes. Defaults to the core provided with clam, core="Example".
type	The type of age-depth model. Five different types are provided: linear interpolation between neighbouring levels (1, "int", "inter" or "interp") linear or higher polynomial regression (2, "reg", "regr", "poly" or "polyn", default linear) cubic spline (3, "spl" or "spline") smooth spline (4, "sm" or "smooth", default smoothing 0.3) locally weighted spline (5, "loess" or "lowess", default smoothing 0.75, cannot extrapolate)
smooth	Degree of smoothing. Gives polynomial degree for model type 2. Not relevant for type=1 or type=3. for type=2: smooth=1 (linear), smooth=2 second-order polynomial, smooth=3 for third-order polynomial, etc. for type=4: smooth=0.3 for type=5: smooth=0.75
prob	Confidence intervals (between 0 and 1), default prob=0.95 or 95%.
its	Amount of age-model iterations; defaults to its=1000.
coredir	The directory where core runs are stored (each core in its own directory named after the core's name).
ask	By default, and as per R rules, clam will ask if it is OK to make or write to a directory. Defaults to coredir="clam_runs", or to coredir="Cores" if this folder exists where R is working.
wghts	Weights can be applied to dated depths as follows: 0 no weighting 1 weighted to calibrated probabilities of sampled calendar years (default, wghts=1). 2 weighted to (inverse squared) errors of the dates.
cc	calibration curve for C14 dates (1, 2 or 3).
cc1	For terrestrial, northern hemisphere C14 dates.
cc2	For marine C14 dates.
cc3	For southern hemisphere C14 dates.
cc4	For mixed terrestrial/marine C14 dates.
postbomb	Use a postbomb curve for negative (i.e. postbomb) 14C ages. 0 = none, 1 = NH1, 2 = NH2, 3 = NH3, 4 = SH1-2, 5 = SH3. See http://calib.org/CALIBomb/.
pb1	For Northern hemisphere region 1 postbomb C14 dates.
pb2	For Northern hemisphere region 2 postbomb C14 dates.
pb3	For Northern hemisphere region 3 postbomb C14 dates.
pb4	For Southern hemisphere regions 1-2 postbomb C14 dates.
pb5	For Southern hemisphere region 3 postbomb C14 dates.
ccdir	Directory where the calibration curves for C14 dates cc are located. By default ccdir="". For example, use ccdir="." to choose current working directory, or ccdir="Curves/" to choose sub-folder Curves/.
outliers	The number of any dates to be considered outlying, e.g. c(5,6) for the fifth and sixth dated depth counting from the top of a core.
ignore	The number of any dates that should be ignored, e.g., c(5,6) for the fifth and sixth date counting from the top of a core.
youngest	The age beyond which dates should be truncated (e.g., youngest=-60 if the core was sampled in -60 cal BP or AD 2010).
extradates	Depths of any additional dates with their files of ages and probabilities.
slump	Upper and lower depths of sections of abrupt accumulation that should be excised, e.g., c(600, 550, 120, 100) for two sections of 600-550 and 120-100 cm depth.
est	Which point estimate to use as 'best' age. It is highly recommended to not only use these 'best' point estimates, as chronological uncertainties are often considerable and should not be ignored. averages of age-depth model derived ages (default, est=1) midpoints of age-depth model derived age estimates midpoints of calibrated ranges weighted means of calibrated ranges medians of calibrated distributions maximum densities of calibrated distributions midpoints of entire calibrated distributions (including years outside the calibrated ranges)
calibt	Calibration based on the student-t distribution. By default, the Gaussian distribution is used (calibt=FALSE). To use the student-t distribution, provide two parameters such as calibt=c(3,4).
mixed.effect	Set to TRUE to activate mixed-effect modelling.
dmin	Minimum depth of age-depth model (e.g., extrapolate).
dmax	Maximum depth of age-depth model (e.g., extrapolate).
every	Resolution at which (ages for) depths are calculated.
yrmin	Minimum of calendar axis of age-depth plot (calculate automatically by default).
yrmax	Maximum of calendar axis of age-depth plot (calculated automatically by default).
yrsteps	Temporal resolution at which calibrated ages are calculated (in calendar years).
pbsteps	Temporal resolution at which postbomb C14 ages are calibrated (in calendar years).
hpdsteps	Temporal resolution at which highest posterior density ranges are calibrated (in calendar years).
BCAD	Use BC/AD or cal BP scale.
decimals	Amount of decimals for rounding.
cmyr	Accumulation rates can be provided as yr/cm (default, cmyr=TRUE, more accurately named deposition times) or cm/yr (cmyr=FALSE).
ageofdepth	Calculate age estimates of a specific depth.
depth	Depth units.
depthseq	Sequence of depths for which age estimates are to be calculated (default: from dmin to dmax with steps of size every)
depths.file	Use a file with depths for depthseq.
thickness	Thickness of the dated samples.
hiatus	Depths of any hiatuses, e.g., c(500, 300). Each sub-section must have at least 2 dates (4 for smoothing spline; does not work with loess as it cannot extrapolate).
remove.reverse	Proportion of age-models with reversals that can be removed before prompting a warning. Set at FALSE to avoid removing models with reversals.
times	Half-range of calibration curve used to calibrate dates (multiplication factor for the dates' errors).
sep	Separator between the fields of the plain text file containing the dating information.
ext	Extension of the file containing the dating information.
runname	Text to add to the core name for specific runs, e.g., "MyCore_Test1"
storedat	Store the dates and age-model within R after a clam run. Defaults to storedat=TRUE.
threshold	Below which value should probabilities be excluded from calculations.
proxies	Set to TRUE to plot proxies against age after the run.
revaxes	Set to TRUE to plot ages on the vertical axis and depth on the horizontal axis.
revd	Plot depth axis in reverse.
revyr	Plot age axis in reverse.
calhght	Heights of the calibrated distributions in the age-depth plot.
maxhght	Maximum height of age probability distributions.
mirror	Plot the age distributions in "mirror" style (above and below depth).
plotrange	Plot the confidence ranges of the age-model.
bty	Type of box to be drawn around plots. Draw a box around the graph ("n" for none, and "l", "7", "c", "u", "]" or "o" for correspondingly shaped boxes).
mar	Plot margins (amount of white space along edges of axes 1-4).
mgp	Axis text margins (where should titles, labels and tick marks be plotted).
plotpdf	Produce a pdf file of the age-depth plot.
plotpng	Produce a png file of the age-depth plot.
greyscale	Produce a grey-scale representation of all age-models (number gives resolution, e.g., 500 bins; will cancel plotting of the confidence intervals).
yrlab	Label of the calendar axis. Defaults to either cal BP or BC/AD. Alternative names can be provided.
dlab	Label of the depth axis. Defaults to dlab="Depth (cm)" (assuming depth="cm"), but alternative names can be provided.
calcol	Colour of the calibrated distributions in the age-depth plot.
C14col	Colour of the calibrated ranges of the dates.
outcol	Colour of outlying dates.
outlsize	Size of symbols outlying dates.
bestcol	Colour of the "best" age-depth model (based on chosen value for est).
rangecol	Colour of plotted confidence ranges.
slumpcol	Colour of slump.
plotname	Print the core name on the graph.
ash	Plot all distributions at the same height.
rule	How should R's approx function deal with extrapolation. If rule=1, the default, then NAs are returned for such points and if it is 2, the value at the closest data extreme is used.

Details

Cores containing several 14C and/or other dates can be processed semi-automatically in order to obtain age-depth models. In the process, any 14C dates are calibrated, and age-depth curves are repeatedly drawn through point estimates sampled from the dates. Age-depth models can be based on linear interpolation, linear/polynomial regression, or cubic, smooth or locally weighted splines. For each date, the probability of a calendar year being sampled is proportionate to its calibrated probability (see Blaauw, 2010). Uncertainty ranges as well as a 'best' age-model are calculated.

Additional cores should be put in a comma-separated file in a sub-folder of the directory where the cores are stored. By default this parent folder is called coredir="clam_runs" (if no folder called "Cores" already exists). If your core is called MyCore1, save MyCore1.csv as clam_runs/MyCore1/MyCore1.csv. Ensure that the names of the core's folder and filename's root (the part before .csv) match, e.g., using exactly similar upper- and lower case letters.

Avoid the use of spaces or non-standard (non-ASCII) characters within the file or in folder or file names. The plain text file should consist of 6 or 7 columns (also called fields), containing in the following exact order (see the example below):

1. Identification labels (e.g. 14C lab codes)

2. 14C ages for 14C-dated depths; leave empty for non-14C dated depths

3. cal BP ages (for any non-14C dates such as the core surface; leave empty for levels with 14C dates)

4. errors (reported 1 standard deviation errors. This column should never be left empty. Errors should always be larger than 0)

5. age offsets if known (otherwise leave empty)

6. depths (depths in the sequence were the dated samples were taken, default unit depth="cm"; this column should never be left empty)

7. thicknesses of the sampled slices (optional column; leave empty for default of 1)

Add a final empty line to your core's .csv file by pressing 'Enter' after the file's last value.

These files can be made in spreadsheet software such as MS-Excel, but it is always a good idea to check the file's formatting in a plain-text editor such as WordPad. Remove any lines which contain only commas, and it is also recommended to remove quotes ()\" or \') in the headers or elsewhere.

Age-models for the core can then be produced by typing, e.g., clam("MyCore1").

By default the northern hemisphere terrestrial calibration curve is used (cc=1, cc1="3Col_intcal20.14C"). To use alternative curves, change cc to cc=2 (cc2="3Col_marine20.14C"), cc=3 (cc3="3Col_shcal20.14C"), cc=4 (cc4="mixed.14C"). You can also provide custom-built calibration curves, indicating its location using ccdir.

The provided example (default core="Example") is core Quilichao-1 which was sampled from a Colombian lake (Berrio et al., 2002). This core was chosen because it was dated at a rather high resolution, and appears to contain a hiatus (e.g., try hiatus=450 for a hiatus at 450 cm depth).

Each clam run will produce a range of files within the core's folder. One, ending with "_calibrated.txt" contains the calibrated age ranges of the 14C and other dates. The others will be named according to the core's name followed by the model type, and contain the age estimates for all depths (files ending with "_ages.txt"), settings (files ending with "_settings.txt") and graphs (files ending with ".pdf" and ".png"). The file containing the age estimates has 5 columns; first the depths, then the minima and maxima of the confidence intervals, then a "best" estimate, and finally the reconstructed accumulation rates. The reported values are rounded to 0 decimals by default (decimals=0). Accumulation rates are in yr/cm ("deposition time") by default (cmyr=FALSE), but can be reported in cm/yr (cmyr=TRUE).

see Blaauw 2010 (Quaternary Geochronology 5: 512-518).

Value

Age model construction together with a text output and files saved to a folder in the coredir/core directory.

Author(s)

Maarten Blaauw <[email protected]>

Maarten Blaauw

References

Berrio, J.C., Hooghiemstra, H., Marchant, R., Rangel, O., 2002. Late-glacial and Holocene history of the dry forest area in the south Colombian Cauca Valley. Journal of Quaternary Science 17, 667-682

Blaauw, M., 2010. Methods and code for 'classical' age-modelling of radiocarbon sequences. Quaternary Geochronology 5, 512-518 doi:10.1016/j.quageo.2010.01.002

Examples

base_temp_dir <- tempdir()
  clam_dir <- file.path(base_temp_dir, "clam_runs")
  dir.create(clam_dir, recursive = TRUE, showWarnings = FALSE)
  clam(, coredir=clam_dir, ask=FALSE) 
  clam(, coredir=clam_dir, ask=FALSE, extradates=470)

---

Calculates the slope of a straight curve at the desired age.

Description

Calculates *for each iteration* the slope of a straight curve between depths above and below the desired age. Requires sufficiently dense density of depths, e.g. steps=1.

Usage

deptime.age(age, yrcm = TRUE, prob = 0.95)

Arguments

age	Age to calculate deposition time (years per cm).
yrcm	Calculate in years per cm, or alternatively in cm per yr.
prob	Probability level at which to calculate the ranges.

Details

To calculate deposition times at an age. Before doing this, run your core in clam and store the data, so, make sure the option storedat=TRUE. Renamed from previous accrate.age function to avoid confusion with accrate.age function of rbacon.

Value

Returns (invisibly) the modelled deposition times at a specific age, a histogram and confidence ranges.

Author(s)

Maarten Blaauw

Examples

base_temp_dir <- tempdir()
  clam_dir <- file.path(base_temp_dir, "clam_runs")
  dir.create(clam_dir, recursive = TRUE, showWarnings = FALSE)
  clam(coredir=clam_dir, storedat=TRUE)
  dp <- deptime.age(5000)
  summary(dp)
  deptime.age(5000, yrcm=FALSE) # to calculate sedimentation times in cm/yr, so accumulation rates

---

Calculates *for each iteration* the slope of a straight curve between depths just above and below the desired point.

Description

Calculates *for each iteration* the slope of a straight curve between depths above and below the desired point. Requires sufficiently dense density of depths, e.g. yrsteps=1.

Usage

deptime.depth(depth, yrcm = TRUE, prob = 0.95)

Arguments

depth	The depth for which accumulation rate estimates should be calculated.
yrcm	Calculate in years per cm, or alternatively in cm per yr.
prob	Probability level at which to calculate the ranges.

Details

To calculate sedimentation times at a depth. Before running this, run your core in clam and store the data, so, make sure to set storedat=TRUE. Renamed from previous accrate.depth function to avoid confusion with accrate.depth function of rbacon.

Value

Returns (invisibly) the modelled deposition times for a specific depths, a histogram and confidence ranges.

Author(s)

Maarten Blaauw

Examples

base_temp_dir <- tempdir()
  clam_dir <- file.path(base_temp_dir, "clam_runs")
  dir.create(clam_dir, recursive = TRUE, showWarnings = FALSE)
  clam(coredir=clam_dir, storedat=TRUE)
  dp <- deptime.depth(20)
  summary(dp)
  deptime.depth(20, FALSE) # to calculate accumulation rates in cm/yr

---

Produce a plot of proxy values against calendar age.

Description

Produce a plot of proxy values against calendar age.

Usage

plot_proxies(prox, errors = TRUE, proxcol = grey(0.5), revyr = TRUE)

Arguments

prox	Position of the proxy that should be plotted, e.g. 1 for the first proxy in the file.
errors	Plot an error envelope.
proxcol	Colour of the error envelope.
revyr	Direction of the calendar scale (revyr=TRUE will reverse the calendar scale from the default FALSE).

Details

Only works after running clam on the core using proxies=TRUE. Requires a file containing the core depths as the first column, and any proxy values on subsequent columns. Values should be separated by comma's. The file should be stored as a .csv file in the core's directory.

Value

A plot of the age model function with proxies.

Author(s)

Maarten Blaauw

Examples

base_temp_dir <- tempdir()
  clam_dir <- file.path(base_temp_dir, "clam_runs")
  dir.create(clam_dir, recursive = TRUE, showWarnings = FALSE)
  clam(coredir=clam_dir, proxies=TRUE)
  plot_proxies(3)
  plot_proxies(3, revyr=FALSE)

---