clam {clam}

clam

Description

Classical (non-Bayesian) age-depth modelling.

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:

1. linear interpolation between neighbouring levels (1, "int", "inter" or "interp")

2. linear or higher polynomial regression (2, "reg", "regr", "poly" or "polyn", default linear)

3. cubic spline (3, "spl" or "spline")

4. smooth spline (4, "sm" or "smooth", default smoothing 0.3)

5. 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.

1. averages of age-depth model derived ages (default, est=1)

2. midpoints of age-depth model derived age estimates

3. midpoints of calibrated ranges

4. weighted means of calibrated ranges

5. medians of calibrated distributions

6. maximum densities of calibrated distributions

7. 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 <[e-mail]>

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

 clam(, coredir=tempdir()) # Create the example in Cores/Example folder
 clam(, coredir=tempdir(), extradates=470)