Clam (Blaauw, 2010) was written to perform 'classic' age-depth modelling - prior to applying more sophisticated techniques such as Bayesian age-depth modelling. A recent version of the free open-source statistical software R (at least version 4.1.0; R Development Core Team, 2021) should also be installed on your computer. You can download clam within R, by typing install.packages("clam") followed by library(clam). Help can be obtained by typing, for example, ?clam.
Please do cite clam (Blaauw, 2010) in your work, as well as its version (most recent 2.4.0), calibration curve(s) used (e.g., Reimer et al., 2020) and the settings applied to obtain the age-models.
| to top of page |
Radiocarbon dates need to be calibrated so that they can be placed onto a calendar year time-scale. Clam's default calibration curve is the northern hemisphere terrestrial curve IntCal20.14C (cc=1) from Reimer et al. (2020). This can be changed to Marine20 (Reimer et al., 2020; cc=2) or SHCal20 (Hogg et al., 2020; cc=3). You can also provide an alternative curve (which must be present within the folder specified by ccdir, e.g., ccdir="."), change the default name of cc1, cc2 or cc3 to that alternative curve, and set cc to the desired curve. See later for special cases such as mixed marine/terrestrial dates.
Negative radiocarbon ages are calibrated with one of the postbomb curves from Hua et al. (2013), but the user needs to inform clam which one should be used. Three postbomb curves are provided for different regions of the northern hemisphere (check the map of Hua et al. (2013) or calibomb), while there are two curves for the southern hemisphere. For example, to use the first of the three northern hemisphere curves with clam and/or calibrate, provide the option postbomb=1, while for southern hemisphere samples, use postbomb=4 for SH zones 1-2 or postbomb=5 for SH zone 3. Clam will provide a warning if no such option is provided with negative radiocarbon ages.
The clam functions to calibrate 14C dates are similar to that of standard calibration approaches such as used in Calib (Stuiver and Reimer, 1993) or OxCal (Bronk Ramsey, 2013). In short, for all calendar ages θ in a wide range, the corresponding 14C ages μ of the calibration curve μ(θ) can be looked up, and compared with the measurement's 14C age y and reported error sd. The probability for each calendar year can then be expressed using the normal function:
y|θ ~ N(μ(θ), σ),
[eq.1]
where σ is a combination of the error of the measurement and that of the calibration curve,
σ2 = sd2 + σ(θ)2.
Since 14C measurements are 14C/C ratios, which decrease exponentially with 14C time, the normal distributions on the 14C scale should in fact be slightly asymmetric (the older end having longer tails). Therefore, just like OxCal (Bronk Ramsey, 2013) clam does not calculate directly on the 14C scale, but instead first converts all 14C ages to their fractions, F14C (Reimer et al., 2004). As an example, check the result of calibrate(20000, 2000).
By default, the dates are calibrated assuming a Gaussian distribution. However, as discussed by Christen and Perez (2009), since the reported errors of radiocarbon dates are estimates of the true error only, this error could be under- or over-estimated. Therefore, instead of using just a single value for the error, Christen and Perez (2009) propose to use a distribution for the error size. This student-t distribution has two parameters, a and b, and to maintain symmetry, a should always equal b-1. As said above, the default is not to use this alternative calibration model (calibt=FALSE). For student-t calibration, provide two parameters instead, e.g., calibt=c(3,4). This will result in distributions very similar to those using the default Gaussian, but with longer tails. Try the clam function student.t() to see the difference between Gaussian and student-t calibration.
Postbomb dates are frequently reported as pMC (percentage modern carbon, normalised to 100%) or F14C (normalised to 1; Reimer et al., 2004). Equivalent radiocarbon ages can be calculated using the function pMC.age, e.g., for a pMC of 130±2, pMC.age(130, 2) results in a 14C age of -2108±123 (the default is to round to zero decimal places, decimals=0). Similarly, 14C ages can be turned into pMC using, for example, age.pMC(-2108, 123), or to F14C using age.pMC(-2108, 123, 1) (here by default rounded to three significant digits, decimals=3).
In some cases, there's a need to mix calibration curves. For example, a 14C date from a northern hemisphere animal with a 30% marine diet should probably be calibrated using a curve that consists of 30% Marine13 and 70% IntCal13. To do so, use mix.curves(0.7), which will produce a curve (by default named "mixed.14C"; name="mixed.14C). The two curves to be mixed are cc1="IntCal13.14C" and cc2="Marine13.14C" by default, and this can be changed by supplying alternative names for cc1 and/or cc2. In case of a regional marine reservoir effect (see the Marine Reservoir Correction database), provide its average and error as, e.g., mix.curves(offset=c(100,50)) if the regional offset is 100 +- 50 C14 yr. Subsequently use this custom-built curve by setting cc=4 in the functions clam() and calibrate() (see below).
| to top of page |
In clam, single 14C dates can be calibrated using several options. Type ?calibrate to see explanations of all options. Typing calibrate() will show the calibration of a date of 2450 ± 50 14C BP (the calibration curve happens to show a plateau around this 14C age). A graph of the raw and calibrated date will be drawn, and the calibrated ranges will be printed. To calibrate a different date, provide its mean and error as follows: calibrate(mean, error), e.g., for a date of 130 ± 20 14C BP, type calibrate(cage=130, error=20) or, shorter, calibrate(130,20). As this date will fall partly beyond the younger extreme of the calibration curve, a warning will be given (similar warnings will be given for too old dates).
In case the date has a reservoir effect or age offset, e.g. of 100 14C years, provide this as follows: calibrate(130,20,reservoir=100). If you want to include an uncertainty for this offset, provide this as follows, e.g., for an uncertainty of 50yr, calibrate(130,20,reservoir=c(100, 50)). The uncertainty for the age offset will then be added to the error (by taking the square root of the sum of the squared error and the squared offset uncertainty). If the carbon of your sample has mixed marine/terrestrial sources, instead apply the marine offset using mix.curves (see above), and calibrate the date using that custom-built curve.
If you prefer to work with, e.g., 68% as opposed to the default 95% confidence intervals, type: calibrate(130, 20, prob=0.68) or calibrate(130,20,,.68) (the commas between the brackets indicate the position of the option; the standard deviation is the fourth option of the calibrate function). Clam calculates the calibrated distribution for every single calendar year (yrsteps=1) within a wide range of the 14C date (default but adaptable times=5 standard deviations or 99.999999% of its probability distribution). This range can also be adapted by changing the option expand (default expand=0.1). Probabilities below a threshold (default threshold=1e-6) will be neglected.
By default the northern hemisphere terrestrial calibration curve is used (cc=1, cc1="IntCal13.14C"). To use alternative curves, change cc to 2 (cc2="Marine13.14C"), 3 (cc3="SHCal13.14C"), 4 (cc4="mixed.14C"), or change the file names of cc1, cc2, cc3 or cc4.
Clam works in cal BP (calendar years before AD 1950) by default, but can work with cal BC/AD through the option BCAD=TRUE.
By default the Gaussian distribution is used to calibrate dates. For use of the student-t distribution instead, provide two sensible values, e.g., calibt=c(3,4).
Calibrated distributions are usually reduced to their 68% or 95% calibrated ranges, taking into account the asymmetric and multi-peaked shape of these distributions. In clam, this is done by calculating the highest posterior density (hpd): i) the probability distribution (see above) is normalised to 100%, ii) the calendar years are ranked according to their probabilities, iii) those calendar ages with a cumulative sum at or below the desired probability threshold (default 95%) are retained, and iv) the extremes and probabilities of any sub-ranges within these calendar ages are reported. Calibrated ranges at 68% will obviously result in narrower confidence intervals, and a perceived higher precision, than 95% ranges. However, given the often asymmetric and multi-modal nature of calibrated distributions, the probability that the 'true' calendar date lies outside the 1 sd hpd ranges is considerable (c. 32%). Therefore the use of 95% calibrated ranges is preferable, and default in clam. The hpd ranges are calculated at yearly resolution by default (hpdsteps=1).
Negative radiocarbon ages are calibrated with postbomb curves, but the user needs to tell clam which curve to use. For example, to use the first of the three northern hemisphere curves, provide the option postbomb=1, while for southern hemisphere samples, use postbomb=4. Default curves can be changed; currently they are pb1="postbomb_NH1.14C", pb2="postbomb_NH2.14C", pb3="postbomb_NH3.14C", pb4="postbomb_SH1-2.14C" and pb5="postbomb_SH3.14C" . If no postbomb option is provided for negative radiocarbon ages, clam will not calibrate the date. Given the sub-year resolution of postbomb-curves, hpd ranges are calculated at high resolution by default (pbsteps=0.01). Chose alternative values with care as they may cause unexpected results.
Generally the calculations are removed from memory after calibration; if you want to have them stored (say for subsequent manipulations), provide the option storedat=TRUE. Alternatively, store the information by naming a variable, for example dat = calibrate(130, 30). After this, dat can be manipulated, e.g., plot(dat$calib, type="l").
A graph of the calibration is produced by default (graph=TRUE), and it can be adapted in several ways. The limits of the horizontal (calendar scale) and vertical (14C scale) axes are calculated automatically but can be changed by providing alternative values for the options yrmin, yrmax, minC14 and maxC14, respectively. The titles of both axis can be changed by providing alternative titles to xlab and/or ylab, and also the top title can be adapted using title. The heights of the distributions of the 14C and calibrated ages can be set to alternative values using calheight (default 0.3). Parameters for white space around the graph can be changed (default mar=c(3.5, 2, 2, 1) for spacing below, to the left, above and to the right respectively), as can the spacing for the axis labels (mgp=c(2,1,0)). By default, the axes are connected at the lower left, bty="l". Check the R documentation of par() for more options.
The colours of the 14C date, the calibration curve, the entire distributions, as well as of the highest posterior density (hpd) ranges, can be changed by providing an alternative colour in date.col, cc.col, dist.col, and/or sd.col, respectively. The default colours are transparent grey for the date's probability distributions (dist.col=rgb(0,0,0, 0.3) and sd.col=rgb(0,0,0, 0.5); change the last value of rgb for different greyscale values), red for the uncalibrated mean and error bars (date.col="red"), and transparent green for the calibration curve (cc.col=rgb(0, 0.5, 0, 0.7)). R's rgb() function expects values between 0 and 1 for red, green and blue, respectively, followed by a value for the semi-transparency (also between 0 and 1). Some graphic devices such as postscript are unable to use transparency; in that case provide different colours or leave the fourth value empty.
| to top of page |
Cores containing several 14C and/or other dates can be processed semi-automatically in order to obtain age-depth models. In the process, the 14C dates are calibrated, after which 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 above and 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 Cores or clam_runs folder, e.g., clam\Cores\MyCore1\MyCore1.csv if your core is called MyCore1. An alternative folder can be provided using, e.g., ccdir="E:\". You can make subfolders within your file browser (Windows: Windows explorer, within the clam/Cores folder click File, Folder, or right-click, New, Folder. Mac: in Finder, within the clam/Cores folder, click File, Folder). Ensure that the names of the core's folder and root-filename match, e.g., using exactly similar upper- and lower case letters. Add a final empty line to the .csv file by pressing 'Enter' after the file's last value. Avoid the use of spaces or non-standard characters in 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):
depth="cm"; this column should never be left empty)
Age-models for the core can then be produced by typing, e.g., clam("MyCore1").
When more information is available for an age-model (e.g., the surface of a core could be of known age, or a tephra layer or change in the pollen spectrum could be related to a historical event), such information can be included as extra data points in the first (identifying label), third (cal_age), fourth (error), sixth (depth) and seventh (thickness; optional) columns. In such case, the second column for 14C ages should be left empty.
The comma-separated files (.csv, default extension ext=".csv", default field separator sep=",", default decimal point separator dec=".") can be produced in a spreadsheet program such as Excel by providing the relevant data in the six or seven columns (not providing commas after the values), leaving any non-relevant cells empty, and saving/exporting as .csv. Names for the columns should be provided on the first line (best avoid using spaces). This will produce a plain text file with commas separating the fields (NB: for localized versions of Excel that use ';' as separator, set sep=";", and similarly check that the correct decimal points are used in dec). None of the columns, except the first one, should contain text characters, e.g., avoid stating "AD 1900" or "1900-1950" for a calendar age. Clam will complain upon finding letters in these fields. Also check that all information is provided in the exact order as described above. Please order the dates according to their depths, starting with the highest dates and working downwards. Each dated level should contain one date only, either in the C14 column or the calendar column; clam will warn if it finds duplicate entries. The first column, the one identifying the dates, should never be named "ID" because this could hang older versions of MS-Excel!
Inspection of the files in a text editor such as Wordpad is highly recommended, for example to remove excessive commas, text or spaces. Make sure that files are saved as *.csv, and not with an additional .txt extension (Windows has a tendency to do so automatically). In case clam finds files with a *.csv.txt extension, it will remove the .txt extension. Experience learns that after having produced several csv-files, the user will often find it easier to avoid the spreadsheet stage and produce them by typing/pasting values directly into a plain-text editor.
Contents of Example.csv:
| lab_ID, | C14_age, | cal_age, | error, | reservoir, | depth |
|---|---|---|---|---|---|
| surface, | , | -55, | 1, | , | 0 |
| GR0001, | 95, | , | 37, | , | 31 |
| GR0002, | 410, | , | 45, | , | 135 |
| GR0003, | 1502, | , | 37, | , | 298 |
| GR0004, | 2167, | , | 42, | , | 365 |
| GR0005, | 2700, | , | 46, | , | 445 |
| GR0006, | 7890, | , | 70, | , | 485 |
| GR0007, | 9440, | , | 60, | , | 537 |
| GR0008, | 9860, | , | 70, | , | 559 |
| GR0009, | 13150, | , | 60, | , | 673 |
The provided example (default name="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), which forms an interesting challenge for age-modelling software.
For a list of available cores, type cores. This list can also be used to avoid typing a core name, e.g., to calculate default age-depth models for cores 1 to 10 in the list, type for(i in cores[1:10]) clam(i).
Dates could suffer from systematic 14C age offsets (reservoir effect) or could show individual offsets (outliers, e.g. outliers=6 if the sixth date in the list is considered to be outlying). In case several dates appear to be outlying, their positions in the dat-file should be given as a combination (e.g., outliers=c(3,7) if the third and seventh date counting from the top of a sequence are outlying). By default, outliers are plotted as red (outcol="red") crosses of default size (outlsize=1), and they are not taken into account within the age-model. If, for whatever reason, certain dates need to be temporally ignored instead, this can be done using the option ignore (e.g., to ignore the fifth date in a core, add ignore=5).
By default the northern hemisphere terrestrial calibration curve is used (cc=1, cc1="IntCal13.14C"). To use alternative curves, change cc to 2 (cc2="Marine13.14C"), 3 (cc3="SHCal13.14C"), 4 (cc4="mixed.14C"), or 5 (cc5="gluedHemispheres.14C"), or alternatively change the file names of cc1, cc2, cc3, cc4 or cc5.
Negative radiocarbon ages are calibrated using postbomb curves, but the user needs to inform clam which curve to use. For example, to use the first of the three northern hemisphere curves, provide the option postbomb=1, and for southern hemisphere samples, use postbomb=4. Default curves are pb1="postbomb_NH1.14C", pb2="postbomb_NH2.14C", pb3="postbomb_NH3.14C", pb4="postbomb_SH1-2.14C" and pb5="postbomb_SH3.14C". If no postbomb option is provided for cores with negative radiocarbon ages, clam will not produce a chronology. Given the sub-year resolution of postbomb-curves, hpd ranges are calculated at high resolution by default (pbsteps=0.01).
Calibration (using eq.1 on the F14C scale) is performed at yearly resolution by default (yrsteps=1), and using a wide range of calendar ages to encompass most of the calibrated distribution (times=5). Although the dates are calibrated using the Guassian distribution by default, the student-t distribution will be used if two parameters are provided, e.g., calibt=c(3,4). Default steps for calculating highest posterior densities are at hpdsteps=1. The calibration range is constructed by encompassing all C14 ages of the calibration curve that fall within a range of +times*error and -times*error, default times=5. Years with probabilities below a threshold are neglected (default threshold=1e-6). The calendar scale is in cal BP by default (BCAD=FALSE), but this can be changed to cal BC/AD.
Radiocarbon dates which fall partly or entirely beyond the range of the calibration curve are truncated resp. removed with a warning.
In case you have information that no date should be younger than a certain threshold, this can be provided as, for example, youngest=-50.
Sometimes there could be additional dating information that cannot be added in the ways described above. For example, a non-14C date on the cal BP or BC/AD scale might have a non-normal distribution, or one of the 14C dates needs to be calibrated using a different calibration curve than the other ones in a core. In that case, produce a plain text file with the calendar years and their probabilities for that date in two columns, and save it within the core's folder. Separate the columns using spaces or tabs, and don't use any headers. The files should have at least two entries for the date's ages and their probabilies. Provide the dates on the time scale you will be using, i.e., either as cal BP or BC/AD. The file name should start with the core's name, then a lower dash, then its depth and finally the ".txt" extension. For example if you've got such dating information at 470 cm depth in core MyCore1, save the file as "Cores/MyCore1/MyCore1_470.txt"). Then run clam with the option extradates=470. Multiple dates (at distinct depths) can be provided, producing files as explained above and providing the multiple depths as for example extradates=c(90, 470).
Having established the information about the individual dating points, the next step is to provide age estimates for all depths in a sequence. This is done by imposing a relationship between depth and age, or in other words, modelling the accumulation of the sequence through time. The user will have to decide on the most likely age-depth model, e.g., a deposit in a stable environment will probably have accumulated with fewer events of hiatuses or accumulation rate changes than one from a more variable environment, and should thus be modelled using a smoother age-depth model. Please remember to also try other, more sophisticated age-depth models such as Bacon (R package rbacon) or BChron (also an R package).
Several types of age-models can be chosen in order to estimate the ages of the non-dated levels (Bennett, 1994): linear interpolation between neighbouring levels (default, type=1), linear regression (type=2), higher polynomial regression (type=2 with smooth=3 for third order, smooth=4 for fourth order, etc.), cubic spline (type=3), smooth spline (type=4, default smoothing level 0.3, which can be adapted using smooth, e.g., smooth=0.7), or locally weighted spline (loess, type=5, default smoothing 0.75, which can be adapted using smooth). Instead of with numbers, type can also be provided with easier to remember names: "int", "inter" or "interp" for linear interpolation, "reg", "regr", "poly" or "polyn" for linear or polynomial regression, "spl" or "spline" for cubic spline, "sm" or "smooth" for smooth spline, and "loess" or "lowess" for locally weighted spline (the names should be quoted, e.g., type="smooth"). Different model types will require different minimum amounts of dates, e.g., a smooth spline needs at least four data points, and linear interpolation or regression at least two.
Hiatuses can be modelled by providing their depths, e.g., hiatus=470 or in case of multiple ones, hiatus=c(470, 600). Each of the resulting sections will require sufficient data points (e.g., a smooth spline needs at least four dates), otherwise clam will not run.
Events of instantaneous deposition, or 'slumps', can be modelled by providing their upper and lower depths, e.g., slump=c(50, 80). If there are multiple slumps, provide a list of all their upper and lower depths, e.g., slump=c(50, 80, 250, 260). Before running the model, clam will excise these intervals, and will add the depths again after the model runs. Slumps will be indicated as horizontal bars on the graph (default slumpcol=grey(0.75)).
By default, ages are calculated at 1 cm resolution (depth units depth="cm", at resolution every=1), from the shallowest (dmin) to the deepest (dmax) dated depth of the core. Alternative sequences of depths can be provided, e.g., through extrapolating beyond the dated depths (providing alternatives for the default dmin and/or dmax), or by providing a specific sequence of depths, e.g depthseq=c(0:100, seq(102, 200, by=2)) for 1 cm resolution for 0:100 cm depth, followed by 2 cm resolution further down. In case a file with extension _depths.txt is present within a core's directory, the depths in this file will be used if told so explicitly: depths.file=TRUE (this is a change from previous clam versions). This depths file should contain one single column with the depths, without headers (see clam/Example/Example_depths.txt).
If the data points would have a symmetrical distribution (e.g., normal), it would be straightforward to calculate the mean and the confidence levels for an applied age-depth model. However, since calibrated radiocarbon ages are often highly asymmetrical with multiple peaks, we need to use an alternative method to calculate the confidence levels for an age-depth model. Clam does so by repeatedly sampling point estimates from the calibrated distributions of the dates (with the probability of an age being drawn being proportional to its height of the probability distribution at that age, see eq.1), each time calculating an age-depth model through these points. This is also called importance-sampling. An extra error akin to Heegaard et al (2005)'s mixed effect age-depth modelling can be added (mixed.effect=TRUE). In this case, the midpoints of all dates will be resampled using their errors, and used as points for the age-model. By default, this process will be repeated its=1000 times.
The polynomial, weighted spline and loess spline age-depth models are weighted (by default according to the calibrated probabilities of the dates, wghts=1, alternatively by their laboratory errors, 1/errors2, wghts=2). However, because the iteration process tends to sample more likely ages preferentially, the dates are already weighted automatically. Thus even without applying extra weighting (wghts=0), dates with larger uncertainties should show a larger spread of sampled calendar ages.
After having obtained many age-depth models, their distributions are analysed. Each iteration will cause a slightly different age-depth model, and thus a slightly different calendar age for any given depth in the core. The default amount of iterations is its=1000, which often gives good results at least for initial runs. For more reliable estimates, use more iterations, e.g., 10,000. The distribution of all age-models can be shown with grey-scales using, e.g., greyscale=500 (which will produce grey-scales at 500 equally spaced core depths, based on the histograms of the calendar age estimates at those depths). This greyscale option does not work with age-models containing hiatuses.
Confidence intervals of the age-depth models are calculated at 95% (2 sd, prob=0.95) level by default. This is done by removing the upper and lower quantiles (e.g., 2.5% and 97.5% for the default 95% confidence ranges), because using the extremes of the highest posterior density intervals would sometimes lead to jumpy ranges (or "mouse-bites"). Because of i) the multimodal distribution of most 14C dates and ii) the uncertainties connected to age-modelling choices, using 95% ranges is safer than the 68% (1 sd) level used in many older studies.
Because the confidence levels are calculated from random simulations, each run will obtain a slightly different outcome. Therefore the user should check for consistency of results by re-running the analysis several times. Please do also test for robustness of model results by re-running using alternative settings (e.g., for type or smooth), and other age-depth models such as Bacon or BChron.
For any individual age-model iteration, the calibrated ages need to be reduced to point-estimates (see Blaauw, 2010). Also, a single "best" age-depth model needs to be provided with which depths can be translated to single calendar ages (e.g., for proxy curves, however see Blaauw et al. 2007 for proxy diagrams based on multiple age-depth curves). These curves can be based on models through the midpoints of the hpd ranges (est=3), weighted means (est=4), medians (est=5) maximum densities (intercept, est=6) or midpoint of the entire calibrated distributions (est=7) of the individual calibrated distributions (Telford et al. 2004). Clam's preferred alternative however is to find, for every depth, the weighted average (default, est=1) or midpoint (est=2) of the calendar ages from the age-depth models themselves. These latter estimates are thus based on all dates together as well as on the applied model.
By default, any models with age-reversals will be removed with a warning, and up to a specified proportion of the model iterations will be removed before an extra warning is given that there are too many models with reversals (default remove.reverse=0.5). In case this option is not activated, clam will warn the user of any age-reversals. Clam will also check for a range of obviously wrong settings and warn correspondingly.
A goodness-of-fit will be calculated for the model, based on the product of the probabilities of the modelled ages of the dated depths. In more detail, the probability of the modelled year from the best age-model given the date is calculated for each date; then the logarithms of these are summed and multiplied by -1. The lower the measure, the better the fit. Values cannot be compared between different cores. This number is for general guidance only and should not be over-interpreted; your qualitative opinion on the shape and fit of the model, given your knowledge about the site, will often be a much better indicator.
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"). Alternative names can be given by providing, e.g., runname="SplineTry4". 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 (accrate=0), but can be reported in cm/yr (accrate=1).
A graph of the age-depth model is produced automatically. The axes can be changed from default settings by adapting the range (calmin, calmax, dmin, or dmax) or their labels (dlab for depths, yrlab for years). The name of the core is plotted, unless plotname=FALSE is specified. By default, the confidence intervals of the age-depth model are plotted; this can be changed be setting plotrange=FALSE. The axes can be reversed and rotated; revd=TRUE will reverse the default order of depths, revyr=TRUE will do the same for the age scale, and revaxes will put depths on the horizontal axis and ages on the vertical one.
The colours for the dates and the model are semi-transparent colours by default, using R's rgb function using four variables between 0 and 1; red, green, blue and transparency respectively. For example, C14col=rgb(0, 0, 1, 0.5) results in transparent blue. The colours can be changed by adapting the values of C14col for 14C dates, calcol for other dates, outcol for outlying dates, bestcol for the "best" model, rangecol for the confidence ranges, and slumpcol for the colour of any slumps. Some postscript devices cannot handle semi-transparency; adapt the colours if using these devices. Copies of the graph are saved to the core's directory by default; this can be avoided by setting plotpdf=FALSE and/or plotpng=FALSE.
The heights of the plotted calibrated distributions can be adapted from the default (calhght=0.3). By default, the calendar age distribution of each of the dates is normalised to 1, and as a result more precise dates will have higher peaks than less precise dates. If one of the dates is so precise that it "overwhelms" the other dates, you could adapt the maximum drawn peak height from its default maxhght=0.01. To plot all dates with the same peak height, use ash=TRUE. The distributions are drawn "mirrored" by default, and this can be cancelled by providing mirror=FALSE.
Details of the graph settings can be adapted through R's par() function. Within clam, the margins of the four axes can be adapted by changing the default values of mar=c(3.5, 3., 2, 1). The spacing of the axis text can be changed by adapting mgp=c(2, 1, 0). By default and L-shaped "box" is drawn around the graph, and this can be changed to other shapes by providing for example a "c", "o" or "]" in bty (bty="n" draws no such lines).
The age distribution of a specific depth in the sequence can be investigated in more detail by providing this depth in ageofdepth. Together with the full age-depth model, a histogram of the depth's age distribution will be drawn, and the age estimates will be stored in R's memory under the name .ageofdepth. With fewer iterations, the histogram will be more variable between runs.
By default, after every clam run the data (calibrated distributions, ranges, point estimates, iterations, age-depth models) are removed from R's memory (storedat=FALSE). If you want to have the data stored in memory, e.g. for additional pruning of the data, set storedat to TRUE. Then, calrange gives the confidence intervals and age point estimates for each core depth, dets lists the dates, and dat shows information about the dates. The latter is a list with elements (identified by a dollar sign) such as the calibrated distributions (dat$calib), highest posterior density ranges (dat$hpd), medians (dat$med), and midpoints (dat$mid).
After a clam run (setting storedat=TRUE), reconstructed deposition times can be plotted for a particular depth (e.g., deptime.depth(90)) or age (e.g., deptime.age=500). Depisition times rates are in years per cm by default, but can be set to cm per year using yrcm=FALSE. The function reports and draws the confidence limits, by default at 95% (prob=0.95), and returns the reconstructed values invisibly. These values can then be manipulated, e.g. as summary(deptime.depth(90)).
If clam is ran with proxies=TRUE, after that run individual proxies can be plotted on a time-scale. A file starting with the core's name and ending with "_proxies.csv" should be stored inside the core's directory. The file should contain a column with the depths, followed by columns containing proxy scores; all columns should be separated by commas. The first line should contain the proxy names, also separated by commas (see clam/Cores/Example/Example_proxies.csv for an example). To plot the first proxy in the file against time, type plot.proxies(1), and so on for the other proxies in the file. By default, the confidence intervals of the calendar ages are plotted (errors=TRUE) in grey (proxcol=grey(0.5)). The order of the calendar axis can be changed using revyr=TRUE.
| to top of page |
Below follows a list of all options of the functions clam and calibrate. Options left empty will be set at the default values.
Options for clam()
| option | default | description |
|---|---|---|
name | "Example" | name of the core, given using quotes. Defaults to the core provided with clam |
type | 1 | 1 linear interpolation between neighbouring levels ("int", "inter", "interp")
2 linear or higher polynomial regression ("reg", "regr", "poly" or "polyn", default linear) 3 cubic spline ("spl", "spline") 4 smooth spline ("sm", "smooth", default smoothing 0.3) 5 locally weighted spline ("loess", "lowess", default smoothing 0.75, cannot extrapolate) |
smooth | 1 (linear) for type=2
| degree of smoothing. Gives polynomial degree for model type 2 |
prob | .95 | Confidence interval (between 0 and 1) |
its | 1000 | amount of iterations |
wghts | 1 | 0 no weighting
1 weighted to calibrated probabilities of sampled calendar years 2 weighted to (inverse squared) errors of the dates |
cc | 1 | calibration curve for C14 dates (1, 2 or 3) |
cc1 | "IntCal13.14C" | for northern hemisphere terrestrial C14 dates |
cc2 | "Marine13.14C" | for marine C14 dates |
cc3 | "SHCal13.14C" | for southern hemisphere C14 dates |
cc4 | "mixed.14C" | for mixed terrestrial/marine C14 dates |
cc5 | "gluedHemispheres.14C" | for southern hemisphere C14 dates beyond 11 kcal BP (not required anymore) |
postbomb | 0 | use which postbomb curve for negative C14 ages? 0=none |
pb1 | "postbomb_NH1.14C" | for northern hemisphere region 1 postbomb C14 dates |
pb2 | "postbomb_NH2.14C" | for northern hemisphere region 2 postbomb C14 dates |
pb3 | "postbomb_NH3.14C" | for northern hemisphere region 3 postbomb C14 dates |
pb4 | "postbomb_SH1-2.14C" | for southern hemisphere postbomb region 3 C14 dates |
pb5 | "postbomb_SH3.14C" | for southern hemisphere postbomb regions 1-2 C14 dates |
outliers | c() | the number of any dates to be considered outlying, e.g. c(5,6) for the fifth and sixth date counting from the top of a core |
ignore | c() | 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 | c() | the age beyond which dates should be truncated |
extradates | c() | depths of any additional dates with their files of ages and probabilities |
slump | c() | 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-100cm depth |
est | 1 | 1 weighted averages of age-depth model derived ages
2 midpoints of age-depth model derived ages 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 (with probabilities beyond threshold) |
calibt | FALSE | off by default; provide two parameters such as c(3,4) |
mixed.effect | FALSE | set to TRUE to activate mixed-effect modelling |
dmin | c() | minimum depth of age-depth model (e.g., extrapolate) |
dmax | c() | maximum depth of age-depth model (e.g., extrapolate) |
every | 1 | resolution at which (ages for) depths are calculated |
yrmin | c() | minimum of calendar axis of age-depth plot (calculate automatically by default) |
yrmax | c() | maximum of calendar axis of age-depth plot (calculated automatically by default) |
yrsteps | 1 | temporal resolution at which calibrated ages are calculated (in calendar years) |
pbsteps | 0.01 | temporal resolution at which postbomb C14 ages are calibrated (in calendar years) |
hpdsteps | 1 | temporal resolution at which highest posterior density ranges are calibrated (in calendar years) |
BCAD | FALSE (use cal BP) | use BC/AD or cal BP scale |
decimals | 0 | amount of decimals for rounding |
accrate | 0 | give accumulation rates in yr/cm (0) or cm/yr (1) |
ageofdepth | c() | calculate age estimates of a specific depth |
depth | "cm" | depth units |
depthseq | c() | sequence of depths for which age estimates are to be calculated (default: from dmin to dmax with steps of size every) |
depths.file | FALSE | use a file with depths for depthseq |
thickness | 1 | thickness of the dated samples |
hiatus | c() | 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 | 0.5 | proportion of age-models with reversals that can be removed before prompting a warning. Set at FALSE to avoid removing models with reversals |
times | 5 | 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 |
dec | "." | charactor for decimal points |
ext | ".csv" | extension of the file containing the dating information |
runname | core name and model type combined | text to add to the corename for specific runs, e.g., "MyCore_Test1" |
storedat | FALSE | store the dates and age-model within R after a clam run |
threshold | 1e-6 | below which value should probabilities be excluded from calculations |
proxies | FALSE | set to TRUE to plot proxies against age after the run |
revaxes | FALSE | set to TRUE to plot ages on the vertical axis and depth on the horizontal axis |
revd | TRUE | plot depth axis in reverse |
revyr | TRUE | plot age axis in reverse |
calhght | 1 | heights of the calibrated distributions in the age-depth plot |
maxhght | 0.01 | maximum height of age probability distributions |
mirror | TRUE | plot the age distributions in "mirror" style (above and below depth) |
plotrange | TRUE | plot the confidence ranges of the age-model |
bty | "l" | |
mar | c(3.5,3,2,1) | plot margins (amount of white space along edges of axes 1-4) |
mgp | c(2,1,0) | axis text margins (where should titles, labels and tick marks be plotted) |
bty | "l" | draw a box around the graph ("n" for none, and "l", "7", "c", "u", "]" or "o" for correspondingly shaped boxes) |
plotpdf | TRUE | produce a pdf file of the age-depth plot |
plotpng | TRUE | produce a png file of the age-depth plot |
greyscale | none | produce a grey-scale representation of all age-models (number gives resolution, e.g., 500 bins; will cancel plotting of the confidence intervals) |
yrlab | "cal BP" or "BC/AD" | alternative names can be provided |
dlab | "depth (cm)" | alternative names can be provided |
calcol | rgb(0,0.5,0.5,0.5) (transparent blue) | colour of the calibrated distributions in the age-depth plot |
C14col | "blue" | colour of the calibrated ranges of the dates |
outcol | "red" | colour of outlying dates |
outlsize | 1 | size of symbols outlying dates |
bestcol | "black" | colour of the "best" age-depth model (based on chosen value for est) |
rangecol | rgb(0,0,0,0.3) (transparent grey) | colour of plotted confidence ranges |
slumpcol | grey(0.75) | colour of slump |
plotname | TRUE | print the core name on the graph |
ash | FALSE | plot all distributions at the same height |
Options for calibrate()
| option | default | description |
|---|---|---|
cage | 2450 | mean of the C14 age |
error | 50 | error of the C14 age |
reservoir | 0 | reservoir age or age offset |
prob | .95 | probability confidence intervals (between 0 and 1) |
cc | 1 | calibration curve for C14 dates (1, 2 or 3) |
cc1 | "IntCal13.14C" | for northern hemisphere terrestrial C14 dates |
cc2 | "Marine13.14C" | for marine C14 dates |
cc3 | "SHCal13.14C" | for southern hemisphere C14 dates |
cc4 | "mixed.14C" | for mixed marine/terrestrial C14 dates |
cc5 | "gluedHemispheres.14C" | for southern hemisphere C14 dates beyond 11 kcal BP (not required anymore) |
postbomb | FALSE | calibration curve for postbomb dates |
pb1 | "postbomb_NH1.14C" | for northern hemisphere region 1 postbomb C14 dates |
pb2 | "postbomb_NH2.14C" | for northern hemisphere region 2 postbomb C14 dates |
pb3 | "postbomb_NH3.14C" | for northern hemisphere region 3 postbomb C14 dates |
pb4 | "postbomb_SH1-2.14C" | for southern hemisphere region 3 postbomb C14 dates |
pb5 | "postbomb_SH3.14C" | for southern hemisphere regions 1-2 postbomb C14 dates |
yrsteps | 1 | temporal resolution at which C14 ages are calibrated (in calendar years) |
pbsteps | 0.01 | temporal resolution at which postbomb C14 ages are calibrated (in calendar years) |
hpdsteps | 1 | temporal resolution at which highest posterior density ranges are calibrated (in calendar years) |
calibt | FALSE | Off by default; provide two parameters such as c(3,4) |
yrmin | c() | minimum of calendar axis (default calculated automatically) |
yrmax | c() | maximum of calendar axis (default calculated automatically) |
minC14 | c() | minimum of C14 axis (default calculated automatically) |
maxC14 | c() | maximum of C14 axis (default calculated automatically) |
times | 5 | half-range of calibration curve used to calibrate dates (multiplication factor for the date's errors) |
calheight | 0.3 | maximum height of the C14 and calibrated distributions (as proportion of the invisible secondary axes) |
expand | 0.1 | by which ratio should the calendar axis be expanded to fit the calibrated distribution |
threshold | 1e-6 | below which value should probabilities be excluded from calculations |
graph | TRUE | plot a graph of the calibrated date. If set to FALSE, only the hpd ranges will be given |
storedat | FALSE | store the dates within the R session after a clam run |
xlab | "cal BP" or "BC/AD" | alternative names can be provided |
ylab | 14C BP | alternative names can be provided |
BCAD | FALSE | use BC/AD or cal BP scale (default cal BP) |
mar | c(3.5,3,2,1) | plot margins (amount of white space along edges of axes 1-4) |
mgp | c(2,1,0) | axis text margins (where should titles, labels and tick marks be plotted) |
bty | "l" | draw a box around the graph ("n" for none, and "l", "7", "c", "u", "]" or "o" for correspondingly shaped boxes) |
title | cage +- error | alternative titles can be provided |
date.col | "red" | colour of the "dot-bar" plot of the C14 date |
cc.col | rgb(0,0.5,0,0.7) (transparent green) | colour of the calibration curve |
dist.col | rgb(0,0,0,0.3) (transparent light grey) | colour of the calibrated distribution |
sd.col | rgb(0,0,0,0.5) (transparent dark grey) | colour of calibrated range |
| to top of page |
For a look under the hood of clam, type any of the functions in R without the brackets (e.g., clam, calibrate, .caldist for calibration, .hpd for the highest posterior density, .smpl for the sampling of dates, .interp for linear interpolation, .poly for polynomial regression, .spline for cubic spline, .smooth for smooth spline, and .loess for locally weighted spline). Help is available by typing, e.g., ?calibrate.
Suggestions for corrections of and additions to the code are much appreciated and can be mailed.
It is important for R to work in the correct directory, so that it can find the code and the data. After opening R, the working directory can be changed by setwd, or in Windows by following File -> Change Working Directory from the top menus. Otherwise, you can open R directly in clam's directory by navigating to its directory in a terminal and opening R there (Linux/Mac), or by making a dedicated "clam" desktop icon for R (right-click on the R icon, select "Properties" and specify the directory under "Start in:").
If you have a list of dates to calibrate (e.g., two columns of the 14C ages and their errors), you could copy the columns into your clipboard (dates <- read.table("clipboard")), and then type for(i in 1:nrow(dates)) calibrate(dates[i,1], dates[i,2]) to calibrate all dates. (The clipboard option does not work on all operating systems.)
Previously typed R commands can be retrieved by pressing the cursor-up key, after which they can be edited and/or run again. After typing part of a command, pressing tab will fill in the rest of the command or suggest alternatives.
There is much help available for R, either within R through typing a question mark followed by an internal R command (e.g, ?plot), on-line (e.g., www.rseek.org or www.r-project.org), through reading the R manuals or any of the reference cards, or, as a last resort, by asking questions in mailing lists.
| to top of page |
clam 2.3.2
clam 2.3.1
clam 2.2
plot.proxies
student.t to show effect alternative calibration
clam 2.1
clam(hiatus=470, slump=c(120,140))
calibrate()
mix.curves())
glue.curves that can be used to extend SHCal04 to 50 kcal BP using IntCal09 and a specified SH offset (obsolete since release of SHCal13)
clam 2.0:
| to top of page |
Most of the times if clam reports problems, its messages will provide hints as to how the problems can be solved. A distinction can be made between "errors", which prevent clam from running, and less severe "warnings", which do not prevent clam from running but will require extra caution as the output might well be wrong.
If upon running clam reports errors such as "cannot open file 'Cores/Example/Example.csv': Permission denied", then probably something is wrong with clam's file permissions. Check that you have writing access to where clam has been saved, and if you cannot change the access settings, try saving clam on for example your memory stick, or directly on C:\ for Windows machines, and work from there. It is also recommended to avoid spaces in any filenames and directories.
If clam says that it "cannot open the connection" and "cannot open file 'Cores/Example/Example.csv': No such file or directory", then probably you have made a mistake in naming the .csv file and its directory. The core's directory must be placed under the Cores directory, and the name of the .csv file must match that of its folder exactly (incl. use of lowercase and uppercase).
If clam stops running while displaying an error such as "line 1 did not have 6 elements", then at least one of the lines in your .csv file does not have exactly 6 fields/columns. In a plain text editor such as WordPad, check the amount of fields of each line including the headers (tip: count the number of commas on each line), correct any mistakes, save the file and run clam again.
| to top of page |
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., Christen, J.A., Mauquoy, D., van der Plicht, J., Bennett, K.D., 2007. Testing the timing of radiocarbon-dated events between proxy archives. The Holocene 17: 283-288
Blaauw, M., 2010. Methods and code for 'classical' age-modelling of radiocarbon sequences. Quaternary Geochronology 5: 512-518
Bronk Ramsey, C., 2013. OxCal 4.2. http://c14.arch.ox.ac.uk/oxcal
Christen, J.A., Pérez E., S., 2010. A new robust statistical model for radiocarbon data. Radiocarbon 51: 1047-1059
Heegaard, E., Birks, H.J.B., Telford, R.J., 2005. Relationships between calibrated ages and depth in stratigraphical sequences: an estimation procedure by mixed-effect regression. The Holocene 15: 1-7
Hogg, A.G., Hua, Q., Blackwell, P.G., Niu, M., Buck, C.E., Guilderson, T.P., Heaton, T.J., Palmer, J.G., Reimer, P.J., Reimer, R.W., Turney, C.S.M., Zimmerman, S.R.J., 2013. SHCal13 southern hemisphere calibration, 0 - 50,000 cal BP. Radiocarbon 55, doi:10.2458/azu_js_rc.55.16783
Hua, Q., Barbetti, M., Rakowski, A.Z., 2013. Atmospheric radiocarbon for the period 1950-2010. Radiocarbon 55, doi:10.2458/azu_js_rc.v55i2.16177
R Development Core Team, 2013. R: A language and environment for statistical computing. R Foundation for Statistical Computing, Vienna, Austria. ISBN 3-900051-07-0, http://www.r-project.org
Reimer, P.J., Brown, T.A., Reimer, R.W., 2004. Discussion: reporting and calibration of post-bomb 14C data. Radiocarbon 46: 1299-1304
Reimer PJ, et al., 2020. The IntCal20 northern hemisphere radiocarbon age calibration curve (0–55 cal kBP). Radiocarbon 62: 725-57.
Stuiver, M., Reimer, P.J., 1993. Extended 14C database and revised CALIB radiocarbon calibration program. Radiocarbon 35: 215-230
Telford, R.J., Heegaard, E., Birks, H.J.B., 2004. The intercept is a poor estimate of a calibrated radiocarbon age. The Holocene 14: 296-298
| to top of page |
Clam is open-source software; you are free to use, copy, distribute and modify it, but please read this manual and accompanying paper before using this program, and cite properly when using/modifying it (don't forget to mention specific settings and calibration curves). This software is distributed under the terms of the GNU General Public License. Clam does not come with any warranty and the author, a mere mortal, does not assume any responsibility for the usefulness of any portion of this program.