Introduction
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 3.5.1; R Development Core Team, 2018) 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.3.2), calibration curve(s) used (e.g., Reimer et al., 2013) and the settings applied to obtain the age-models.
Controls (Top) 1. Time Zone button 5. Week Mode button 9. Alarm 2 button 2. Alarm 1 button 3. Radio / On/Off button 11. Snooze button 8. Down button If you need any further advice, please call our Technical Helpline on:- 020 8758 0338 (Mon-Fri). Download the Chronos 1.4 V0.1 microSD card image. Remove the Operation System (OS) microSD card from the camera. This card is located at the top right of the ratings label on the bottom of the camera Use an SD card, the 2mm allen key shipped with the camera, or another thin object to push and release the card, then pull it out.
to top of page |
Radiocarbon calibration
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 IntCal13.14C (
cc=1
) from Reimer et al. (2013). This can be changed to Marine13 (Reimer et al., 2013; cc=2
) or SHCal13 (Hogg et al., 2013; 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.
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 |
Calibrating a single date
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 |
Age-depth modelling
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.,
clamCoresMyCore1MyCore1.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): - identification labels (e.g. 14C lab codes)
- 14C ages for 14C-dated depths; leave empty for non-14C dated depths
- cal BP ages (for any non-14C dates such as the core surface; leave empty for levels with 14C dates)
- errors (reported 1 standard deviation errors; this column should never be left empty. Errors should always be larger than 0)
- age offsets if known (otherwise leave empty)
- depths (depths in the sequence were the samples were taken, default unit
depth='cm'
; this column should never be left empty) - thicknesses of the sampled slices (optional column; leave empty for default of 1)
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)
. Dating points
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)
. Age-depth model
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
). Graph
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). Additional analysis
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 |
All options
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 |
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 |
R tips and tricks
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 |
Version history
clam 2.3.2
- new function calBP.14C to find the mu (IntCal 14C age) belonging to a single calendar year (suggested by Andres Christen)
- emoved suppression of warnings (suggested by Maris Nartiss)
- added sep argument to mix.calibrationcurves (suggested by Thomas Dye)
- calibrate now invisibly returns dat (suggested by Andres Christen) so now can be used as, e.g., cal = calibrate(130, 30); cal
- related functions were put into separate .R files
- unnecessary references to Bacon were removed
- dummy -5 cal BP lines were removed from the IntCal13 and SHCal13 calibration curves
clam 2.3.1
- Now a CRAN R package
- Repaired many sundry bugs
- updated the help functions
clam 2.2
- updated calibration curves (IntCal13 for both hemispheres and the ocean, plus postbomb curves)
- corrected behaviour of est
- corrected use of alternative separator in .csv files (e.g. ';' instead of ','). Also added option to specify alternative decimal points (e.g. ',' instead of '.')
- repaired bug that caused incorrect depths for
plot.proxies
- repaired bug with slump, causing some dates to be assigned wrong depths
- corrected bug with drawing sample thickness when extradates applied
- new option for est, midpoint of entire calibrated distributions (above threshold, est=7). This differs slightly from the midpoint of the calibrated hpd ranges (est=3)
- minor changes to the manual, incl. more explicit citation suggestions
- added function
student.t
to show effect alternative calibration
![Chrono plus 1 4 24 Chrono plus 1 4 24](https://cdn2.chrono24.com/images/uhren/images_96/s2/8338296_s210.jpg)
clam 2.1
- corrected wrong behaviour when using hiatus and slump, e.g.,
clam(hiatus=470, slump=c(120,140))
- polynomial age-modelling now correctly deals with weights (wght)
- uncertainties for age offsets can be included in
calibrate()
- marine offset can now be specified when producing a mixed terrestrial/marine curve (
mix.curves()
) - new function
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) - corrected references in the manual
clam 2.0:
- Depth segments of abrupt sedimentation can now be excised with the option slump
- different colours for C14 and calendar dates
- accumulation rates are calculated and added as a fifth column to the _ages.txt file
- future ages can be avoided in the dates and the age-depth model
- option to rotate the axes, or reverse the order for the age or depth axes
- optional calibt calibration (Christen and Perez 2009)
- option to provide .txt files with ages and probs for depths
- single instead of mirrored calibrated histograms can be drawn in age-depth graphs
- mix.curves
- pMC.age, age.pMC to convert between 14C ages and percent modern carbon
- proxy plot
- histograms and confidence ranges for accumulation rates can be calculated for specific depths or ages
- probability distributions are now normalised, so that precise ages have higher heights than imprecise ages. This can be turned off
- more consistent naming of dmax, dmin, etc.
- Warnings are provided in case of clearly wrong settings (e.g. type > 5)
- Internal calculations for C14 dates are now done in F14C (as in OxCal)
- core name added to age-plots
- can now leave thickness column out of .csv file (so, need 6 columns only)
- instead of standard deviation, the statistically more correct probability is used (e.g., what was formerly sdev=2 is now prob=0.95)
- use of file _depths.txt now needs to be activated explicitly
- corrected a bug with calibrating single dates on old or young extremes of the calibration curve
- corrected wrong behaviour when outliers and mixed.effect are used together
- corrected a reservoir effect bug in mixed.effect
- corrected a bug in hpds around 0 BC/AD when BCAD=TRUE
- corrected a wrong reaction to clam(BCAD=TRUE)
- corrected wrong yr.axis titles in png and pdf
- corrected a bug in title option calibrate()
- better error message when type=5 & hiatus
- enhanced treatment of plotting parameters (par)
- better rounding for ages.txt
- squashed many more small to invisible bugs
to top of page |
Troubleshooting
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 |
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 Science17: 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 Holocene17: 283-288
Blaauw, M., 2010. Methods and code for 'classical' age-modelling of radiocarbon sequences. Quaternary Geochronology5: 512-518
Chrono Plus 1 4 20
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. Radiocarbon51: 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 Holocene15: 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. Radiocarbon55, doi:10.2458/azu_js_rc.55.16783
Hua, Q., Barbetti, M., Rakowski, A.Z., 2013. Atmospheric radiocarbon for the period 1950-2010. Radiocarbon55, 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. Radiocarbon46: 1299-1304
Reimer, P.J., Bard, E., Bayliss, A., Beck, J.W., Blackwell, P.G., Bronk Ramsey, C., Buck, C.E., Edwards, R.L., Friedrich, M., Grootes, P.M., Guilderson, T.P., Haflidason, H., Hajdas, I., Hatté, C., Heaton, T.J., Hoffmann, D.L., Hogg, A.G., Hughen, K.A., Kaiser, K.F., Kromer, B., Manning, S.W., Niu, M., Reimer, R.W., Richards, D.A., Scott, E.M., Southon, J.R., Turney, C.S.M., van der Plicht, J., 2013. IntCal13 and Marine13 radiocarbon age calibration curves, 0-50,000 years cal BP. Radiocarbon55: 1869-1887
Stuiver, M., Reimer, P.J., 1993. Extended 14C database and revised CALIB radiocarbon calibration program. Radiocarbon35: 215-230
Telford, R.J., Heegaard, E., Birks, H.J.B., 2004. The intercept is a poor estimate of a calibrated radiocarbon age. The Holocene14: 296-298
to top of page |
About this manual
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.
Copyright © 2006, 2008 Beman Dawes
Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Table of Contents
- Overview
- Motivation
- Description
- User's Guide
- Getting Started
- Tutorial
- Examples
- External Resources
- Reference
- Header
<boost/chrono/include.hpp>
- Included on the C++11 Recommendation
- Chrono I/O
- Chrono Rounding Utilities
- Other Clocks
- Header
- Appendices
- Appendix: History
- Appendix: Rationale
- Appendix: Implementation Notes
- Appendix: FAQ
- Appendix: Acknowledgements
- Appendix: Future plans
]
]
- Motivation
- Description
“What is time, then? If nobody asks me, I know; if I have to explain it to someone who has asked me, I do not know.'”
How to Use This Documentation
This documentation makes use of the following naming and formatting conventions.
- Code is in
fixedwidthfont
and is syntax-highlighted. - Replaceable text that you will need to supply is in
italics
. - Free functions are rendered in the code font followed by
()
, as infree_function()
. - If a name refers to a class template, it is specified like this:
class_template<>
; that is, it is in code font and its name is followed by<>
to indicate that it is a class template. - If a name refers to a function-like macro, it is specified like this:
MACRO()
; that is, it is uppercase in code font and its name is followed by()
to indicate that it is a function-like macro. Object-like macros appear without the trailing()
. - Names that refer to concepts in the generic programming sense are specified in CamelCase.
Note |
---|
In addition, notes such as this one specify non-essential information that provides additional background or rationale. |
Finally, you can mentally add the following to any code fragments in this document:
Time
We all deal with time every day of our lives. We've intuitively known it since birth. Thus we are all very familiar with it and believe it to be a simple matter. The modeling of time in computer programs should be similarly simple. The unfortunate truth is that this perceived simplicity is only skin deep. Fortunately, we do not need a terribly complicated solution to meet the bulk of our needs. However, overly simplistic solutions can be dangerous and inefficient, and won't adapt as the computer industry evolves.
Boost.Chrono aims to implement the new time facilities in C++0x, as proposed in N2661 - A Foundation to Sleep On. That document provides background and motivation for key design decisions and is the source of a good deal of information in this documentation.
Wall clock versus system and user time
To make the timing facilities of Boost.Chrono more generally useful, the library provides a number of clocks that are thin wrappers around the operating system's process time API, thereby allowing the extraction of wall clock time, user CPU time, and system CPU time of the process. Wall clock time is the sum of CPU time and system CPU time. (On POSIX-like systems, this relies on
times()
. On Windows, it relies on GetProcessTimes()
.) The Boost.Chrono library provides:
Chrono Plus 1 4 24
Standard
- A means to represent time durations: managed by the generic
duration
class . Examples of time durations include days,minutes
,seconds
andnanoseconds
, which can be represented with a fixed number of clock ticks per unit. All of these units of time duration are united with a generic interface by theduration
facility. - A type for representing points in time:
time_point
. Atime_point
represents an epoch plus or minus aduration
. The library leaves epochs unspecified. Atime_point
is associated with a clock. - Several clocks, some of which may not be available on a particular platform:
system_clock
,steady_clock
andhigh_resolution_clock
. A clock is a pairing of atime_point
andduration
, and a function which returns atime_point
representing now.
Other clocks
To make the timing facilities more generally useful, Boost.Chrono provides a number of clocks that are thin wrappers around the operating system's time APIs, thereby allowing the extraction of wall clock time, user CPU time, system CPU time spent by the process,
process_real_cpu_clock
, captures wall clock CPU time spent by the current process.process_user_cpu_clock
, captures user-CPU time spent by the current process.process_system_cpu_clock
, captures system-CPU time spent by the current process.- A tuple-like class
process_cpu_clock
, that captures real, user-CPU, and system-CPU process times together. - A
thread_clock
thread steady clock giving the time spent by the current thread (when supported by a platform).
Lastly, Boost.Chrono includes typeof registration for
duration
and time_point
to permit using emulated auto with C++03 compilers. I/O
Chrono Plus 1 4 2 0
It provides I/O for
duration
and time_point
. It builds on <boost/ratio/ratio_io.hpp>
to provide readable and flexible formatting and parsing for types in <boost/chrono.hpp>
. The duration
unit names can be customized through a new facet: duration_punct
. Chrono Plus 1 4 2 Player Games
Rounding utilities
A few simple rounding utility functions for working with durations.
Caveat Emptor
The underlying clocks provided by operating systems are subject to many seemingly arbitrary policies and implementation irregularities. That's a polite way of saying they tend to be flakey, and each operating system or even each clock has its own cruel and unusual forms of flakiness. Don't bet the farm on their accuracy, unless you have become deeply familiar with exactly what the specific operating system is guaranteeing, which is often very little.