| Title: | Radiocarbon Equations |
|---|---|
| Description: | Provides functions for the calibration of radiocarbon dates, as well as options to calculate different radiocarbon realms (C14 age, F14C, pMC, D14C) and estimating the effects of contamination or local reservoir offsets (Reimer and Reimer 2001 <doi:10.1017/S0033822200038339>). The methods follow long-established recommendations such as Stuiver and Polach (1977) <doi:10.1017/S0033822200003672> and Reimer et al. (2004) <doi:10.1017/S0033822200033154>. This package complements the data package 'rintcal'. |
| Authors: | Maarten Blaauw [aut, cre]
|
| Maintainer: | Maarten Blaauw <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 1.0.0 |
| Built: | 2025-02-06 06:13:57 UTC |
| Source: | https://github.com/maarten14c/rice |
Provides functions for the calibration of radiocarbon dates, as well as options to calculate different radiocarbon realms (C14 age, F14C, pMC, D14C) and estimating the effects of contamination or local reservoir offsets (Reimer and Reimer 2001 doi:10.1017/S0033822200038339). The methods follow long-established recommendations such as Stuiver and Polach (1977) doi:10.1017/S0033822200003672 and Reimer et al. (2004) doi:10.1017/S0033822200033154. This package complements the data package 'rintcal'.
Maintainer: Maarten Blaauw [email protected] (ORCID)
Calculate F14C values from radiocarbon ages
age.F14C(mn, sdev = c(), decimals = 5, lambda = 8033)age.F14C(mn, sdev = c(), decimals = 5, lambda = 8033)
mn |
Reported mean of the 14C age. |
sdev |
Reported error of the 14C age. If left empty, will translate mn to F14C. |
decimals |
Amount of decimals required for the F14C value. Defaults to 5. |
lambda |
The mean-life of radiocarbon (based on Libby half-life of 5568 years) |
Post-bomb dates are often reported as F14C or fraction modern carbon. Since Bacon expects radiocarbon ages, this function can be used to calculate F14C values from radiocarbon ages. The reverse function of F14CtoC14.
F14C values from C14 ages.
Calculate pMC values from radiocarbon ages
age.pMC(mn, sdev = c(), ratio = 100, decimals = 5, lambda = 8033)age.pMC(mn, sdev = c(), ratio = 100, decimals = 5, lambda = 8033)
mn |
Reported mean of the 14C age. |
sdev |
Reported error of the 14C age. |
ratio |
Most modern-date values are reported against |
decimals |
Amount of decimals required for the pMC value. Defaults to 5. |
lambda |
The mean-life of radiocarbon (based on Libby half-life of 5568 years) |
Post-bomb dates are often reported as pMC or percent modern carbon. Since Bacon expects radiocarbon ages, this function can be used to calculate pMC values from radiocarbon ages. The reverse function of pMC.C14.
pMC values from C14 ages.
Combine all calibrated dates by calculating their product for a range of calendar ages, as if all dates belonged to the same (unknown) calendar age bin.
as.bin( y, er, width = 100, move.by = c(), move.res = 100, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, is.F = FALSE, as.F = FALSE, thiscurve = NULL, yrsteps = 1, threshold = 0.001, normal = TRUE, t.a = 3, t.b = 4, BCAD = FALSE, cc.dir = NULL, age.lim = c(), age.lab = c(), d.lim = c(), calib.col = rgb(0, 0, 0, 0.2), bin.col = rgb(0, 0, 1, 0.5), bin.height = 4, talk = TRUE, prob = 0.95, roundby = 0, bty = "n" )as.bin( y, er, width = 100, move.by = c(), move.res = 100, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, is.F = FALSE, as.F = FALSE, thiscurve = NULL, yrsteps = 1, threshold = 0.001, normal = TRUE, t.a = 3, t.b = 4, BCAD = FALSE, cc.dir = NULL, age.lim = c(), age.lab = c(), d.lim = c(), calib.col = rgb(0, 0, 0, 0.2), bin.col = rgb(0, 0, 1, 0.5), bin.height = 4, talk = TRUE, prob = 0.95, roundby = 0, bty = "n" )
y |
The set of radiocarbon dates to be tested |
er |
The lab errors of the radiocarbon dates |
width |
The bin width to apply. Narrower bins will result in fewer dates fitting those bins, but in more detailed bin width histograms. |
move.by |
Step size by which the window moves. Left empty by default, and then the moves are set by the parameter move.res. |
move.res |
The amount of steps taken to make the histogram. Defaults to |
cc |
Calibration curve to use. Defaults to IntCal20 ( |
postbomb |
Whether or not to use a postbomb curve. Required for negative radiocarbon ages. |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
is.F |
Set this to TRUE if the provided age and error are in the F14C realm. |
as.F |
Whether or not to calculate ages in the F14C realm. Defaults to |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
yrsteps |
Steps to use for interpolation. Defaults to the cal BP steps in the calibration curve |
threshold |
Report only values above a threshold. Defaults to |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2016). |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
BCAD |
Which calendar scale to use. Defaults to cal BP, |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
age.lim |
Limits of the age axis. Calculated automatically by default. |
age.lab |
Label of the age axis. Defaults to cal BP or BC/AD. |
d.lim |
Limits of the depth/vertical axis. Calculated automatically by default. |
calib.col |
The colour of the individual calibrated ages. Defaults to semi-transparent grey. |
bin.col |
The colour of the combined |
bin.height |
The height of the combined distribution |
talk |
Whether or not to report the calculations made. Defaults to |
prob |
Probability range for highest posterior density (hpd) values. Defaults to |
roundby |
Rounding of reported years. Defaults to 0 decimals |
bty |
Draw a box around a box of a certain shape. Defaults to |
This calculates the amount of calibrated dates that fall within a specific bin, and calculates these bins as moving windows over the range of calendar ages to which the radiocarbon ages calibrate.
The number of dates that fall within the moving bins, for each bin.
Maarten Blaauw
data(shroud) shroudbin <- as.bin(shroud$y, shroud$er, 50, 10) # bins of 50 yr, moving by 10 yr, slowdata(shroud) shroudbin <- as.bin(shroud$y, shroud$er, 50, 10) # bins of 50 yr, moving by 10 yr, slow
Combine all calibrated dates by calculating their product for a range of calendar ages, as if all dates belonged to the same (unknown) single calendar age. This assumed that they all belong to the same single year in time. Use with great care, as often dates could stem from material that could have accumulated over a (much) longer time-span, and if so, then the result will be wrong. See Baillie (1991)'s 'suck-in' effect, Journal of Theoretical Archaeology 2, 12-16.
as.one( y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, is.F = FALSE, as.F = FALSE, thiscurve = NULL, yrsteps = 1, threshold = 0.001, normal = TRUE, t.a = 3, t.b = 4, BCAD = FALSE, cc.dir = NULL, age.lim = c(), age.lab = c(), d.lim = c(), calib.col = rgb(0, 0, 0, 0.2), one.col = rgb(0, 0, 1, 0.5), one.height = 4, prob = 0.95, talk = TRUE, roundby = 0, bty = "n" )as.one( y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, is.F = FALSE, as.F = FALSE, thiscurve = NULL, yrsteps = 1, threshold = 0.001, normal = TRUE, t.a = 3, t.b = 4, BCAD = FALSE, cc.dir = NULL, age.lim = c(), age.lab = c(), d.lim = c(), calib.col = rgb(0, 0, 0, 0.2), one.col = rgb(0, 0, 1, 0.5), one.height = 4, prob = 0.95, talk = TRUE, roundby = 0, bty = "n" )
y |
The set of radiocarbon dates to be tested |
er |
The lab errors of the radiocarbon dates |
cc |
Calibration curve to use. Defaults to IntCal20 ( |
postbomb |
Whether or not to use a postbomb curve. Required for negative radiocarbon ages. |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
is.F |
Set this to TRUE if the provided age and error are in the F14C realm. |
as.F |
Whether or not to calculate ages in the F14C realm. Defaults to |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
yrsteps |
Steps to use for interpolation. Defaults to the cal BP steps in the calibration curve |
threshold |
Report only values above a threshold. Defaults to |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2016). |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
BCAD |
Which calendar scale to use. Defaults to cal BP, |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
age.lim |
Limits of the age axis. Calculated automatically by default. |
age.lab |
Label of the age axis. Defaults to cal BP or BC/AD. |
d.lim |
Limits of the depth/vertical axis. Calculated automatically by default. |
calib.col |
The colour of the individual calibrated ages. Defaults to semi-transparent grey. |
one.col |
The colour of the combined |
one.height |
The height of the combined distribution |
prob |
Probability range for highest posterior density (hpd) values. Defaults to |
talk |
Whether or not to provide an analysis of the results |
roundby |
Rounding of reported years. Defaults to 0 decimals |
bty |
Draw a box around a box of a certain shape. Defaults to |
This calculates the product of all calibrated probabilities, over the range of calendar ages to which the radiocarbon ages calibrate.
The product of all calibrated probabilities over the range of cal BP years.
Maarten Blaauw
data(shroud) as.one(shroud$y,shroud$er, BCAD=TRUE) # but note the scatter! Zu <- grep("ETH", shroud$ID) # Zurich lab only as.one(shroud$y[Zu],shroud$er[Zu], BCAD=TRUE)data(shroud) as.one(shroud$y,shroud$er, BCAD=TRUE) # but note the scatter! Zu <- grep("ETH", shroud$ID) # Zurich lab only as.one(shroud$y[Zu],shroud$er[Zu], BCAD=TRUE)
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding 14C age and error are returned. BC ages are negative. In this implementation, the year 0 BC/AD does exist.
BCADtoC14( x, cc = 1, postbomb = FALSE, zero = TRUE, rule = 1, cc.dir = NULL, thiscurve = NULL )BCADtoC14( x, cc = 1, postbomb = FALSE, zero = TRUE, rule = 1, cc.dir = NULL, thiscurve = NULL )
x |
The BC/AD year. |
cc |
calibration curve for C14 (see |
postbomb |
Whether or not to use a postbomb curve (see |
zero |
Whether or not to include 0 in BC/AD years. Defaults to TRUE. |
rule |
How should R's approx function deal with extrapolation. If |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
Interpolation is used, and values outside the calibration curve are given as NA. For ages younger than AD 1950, a postbomb curve will have to be provided.
The calibration-curve 14C year belonging to the entered BC/AD age
Maarten Blaauw
BCADtoC14(100)BCADtoC14(100)
calculate cal BP ages from BC/AD ages
BCADtocalBP(x, zero = TRUE)BCADtocalBP(x, zero = TRUE)
x |
The BCAD age(s) to be translated into cal BP age(s). BC ages are negative, AD ages are positive. |
zero |
Whether or not zero BC/AD should be included. Defaults to 0. |
Turn BC/AD (or BCE/CE) ages into cal BP ages. Negative ages indicate BC, positive ages AD. Since the Gregorian and Julian calendars do not include 0 BC/AD (i.e., 31 December of 1 BC is followed by 1 January of AD 1), zero can be omitted. The years then go from 1 (AD) to -1 (i.e., 1 BC). Other calendars, such as the astronomical one, do include zero. The often-used BCE/CE ages are equivalent to BC/AD.
The cal BP age(s).
BCADtocalBP(2024) BCADtocalBP(-1, zero=TRUE) BCADtocalBP(-1, zero=FALSE)BCADtocalBP(2024) BCADtocalBP(-1, zero=TRUE) BCADtocalBP(-1, zero=FALSE)
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding F14C value and error are returned.
BCADtoD14C( x, zero = TRUE, cc = 1, postbomb = FALSE, rule = 1, cc.dir = NULL, thiscurve = NULL )BCADtoD14C( x, zero = TRUE, cc = 1, postbomb = FALSE, rule = 1, cc.dir = NULL, thiscurve = NULL )
x |
The cal BP year. |
zero |
Whether or not to include 0 in BC/AD years. Defaults to TRUE. |
cc |
calibration curve for C14 (see |
postbomb |
Whether or not to use a postbomb curve (see |
rule |
How should R's approx function deal with extrapolation. If |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
Interpolation is used, and values outside the calibration curve are given as NA. For negative cal BP ages, a postbomb curve will have to be provided.
The calibration-curve 14C year belonging to the entered cal BP age
Maarten Blaauw
BCADtoD14C(1900)BCADtoD14C(1900)
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding F14C and error are returned. BC ages are negative. In this implementation, the year 0 BC/AD does exist.
BCADtoF14C( x, cc = 1, postbomb = FALSE, zero = TRUE, rule = 1, cc.dir = NULL, thiscurve = NULL )BCADtoF14C( x, cc = 1, postbomb = FALSE, zero = TRUE, rule = 1, cc.dir = NULL, thiscurve = NULL )
x |
The BC/AD year. |
cc |
calibration curve for C14 (see |
postbomb |
Whether or not to use a postbomb curve (see |
zero |
Whether or not to include 0 in BC/AD years. Defaults to TRUE. |
rule |
How should R's approx function deal with extrapolation. If |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
Interpolation is used, and values outside the calibration curve are given as NA. For ages younger than AD 1950, a postbomb curve will have to be provided.
The calibration-curve F14C belonging to the entered BC/AD age
Maarten Blaauw
BCADtoF14C(100)BCADtoF14C(100)
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding pMC and error are returned. BC ages are negative. In this implementation, the year 0 BC/AD does exist.
BCADtopMC( x, cc = 1, postbomb = FALSE, zero = TRUE, rule = 1, cc.dir = NULL, thiscurve = NULL )BCADtopMC( x, cc = 1, postbomb = FALSE, zero = TRUE, rule = 1, cc.dir = NULL, thiscurve = NULL )
x |
The BC/AD year. |
cc |
calibration curve for C14 (see |
postbomb |
Whether or not to use a postbomb curve (see |
zero |
Whether or not to include 0 in BC/AD years. Defaults to TRUE. |
rule |
How should R's approx function deal with extrapolation. If |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
Interpolation is used, and values outside the calibration curve are given as NA. For ages younger than AD 1950, a postbomb curve will have to be provided.
The calibration-curve F14C belonging to the entered BC/AD age
Maarten Blaauw
BCADtopMC(100)BCADtopMC(100)
Find the BCAD ages where the calibration curve crosses a given C14 age. This function is for illustration only and not to be used for, e.g., calibration, because intercept calibration is an outdated method.
C14toBCAD( y, cc = 1, postbomb = FALSE, rule = 1, zero = TRUE, cc.dir = NULL, thiscurve = NULL )C14toBCAD( y, cc = 1, postbomb = FALSE, rule = 1, zero = TRUE, cc.dir = NULL, thiscurve = NULL )
y |
The C14 age. |
cc |
calibration curve for C14 (see |
postbomb |
Whether or not to use a postbomb curve (see |
rule |
How should R's approx function deal with extrapolation. If |
zero |
Whether or not to include 0 in BC/AD years. Defaults to TRUE. |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
. Whereas each cal BP age will only have one single IntCal radiocarbon age (mu), the same cannot be said for the other way round. Recurring C14 ages do happen, especially during periods of plateaux and wiggles. Therefore, there can be multiple cal BP ages for a single C14 age. In the early days, radiocarbon calibration used an 'intercept method' to find possible calendar ages belonging to a radiocarbon age, but this is problematic since small deviations in the C14 age can easily cause more or fewer crossing cal BP ages (try for example C14tocalBP(130) vs C14tocalBP(129)), and moreover, this approach does not deal well with the errors in either a date of the calibration curve. Therefore, the probabilistic approach to radiocarbon calibration (which starts with a cal BP age and then looks up the corresponding C14 age) has taken over as the standard.
The BCAD age(s) belonging to the entered C14 age
Maarten Blaauw
y <- 130 calibrate(y,10, BCAD=TRUE) abline(h=y) abline(v=C14toBCAD(y))y <- 130 calibrate(y,10, BCAD=TRUE) abline(h=y) abline(v=C14toBCAD(y))
Find the cal BP ages where the calibration curve crosses a given C14 age. This function is for illustration only and not to be used for, e.g., calibration, because intercept calibration is an outdated method.
C14tocalBP( y, cc = 1, postbomb = FALSE, rule = 1, cc.dir = NULL, thiscurve = NULL )C14tocalBP( y, cc = 1, postbomb = FALSE, rule = 1, cc.dir = NULL, thiscurve = NULL )
y |
The C14 age. |
cc |
calibration curve for C14 (see |
postbomb |
Whether or not to use a postbomb curve (see |
rule |
How should R's approx function deal with extrapolation. If |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
. Whereas each cal BP age will only have one single IntCal radiocarbon age (mu), the same cannot be said for the other way round. Recurring C14 ages do happen, especially during periods of plateaux and wiggles. Therefore, there can be multiple cal BP ages for a single C14 age. In the early days, radiocarbon calibration used an 'intercept method' to find possible calendar ages belonging to a radiocarbon age, but this is problematic since small deviations in the C14 age can easily cause more or fewer crossing cal BP ages (try for example C14tocalBP(130) vs C14tocalBP(129)), and moreover, this approach does not deal well with the errors in either a date of the calibration curve. Therefore, the probabilistic approach to radiocarbon calibration (which starts with a cal BP age and then looks up the corresponding C14 age) has taken over as the standard.
The cal BP age(s) belonging to the entered C14 age
Maarten Blaauw
y <- 130 calibrate(y,10) abline(h=y) abline(v=C14tocalBP(y))y <- 130 calibrate(y,10) abline(h=y) abline(v=C14tocalBP(y))
Transform C14 age(s) into D14C
C14toD14C(y, er = NULL, t)C14toD14C(y, er = NULL, t)
y |
The C14 age to translate |
er |
Reported error of the C14 age. Returns just the mean if left empty. |
t |
the cal BP age |
As explained by Heaton et al. 2020 (Radiocarbon), 14C measurements are commonly expressed in three domains: Delta14C, F14C and the radiocarbon age. This function translates C14 ages into Delta14C, the historical level of Delta14C in the year t cal BP. Note that per convention, this function uses the Cambridge half-life, not the Libby half-life.
The corresponding D14C value
C14toD14C(0.985, 20, 222)C14toD14C(0.985, 20, 222)
Calculate F14C values from radiocarbon ages
C14toF14C(y, er = NULL, decimals = 5, lambda = 8033)C14toF14C(y, er = NULL, decimals = 5, lambda = 8033)
y |
Reported mean of the 14C age. |
er |
Reported error of the 14C age. If left empty, will translate y to F14C. |
decimals |
Amount of decimals required for the F14C value. Defaults to 5. |
lambda |
The mean-life of radiocarbon (based on Libby half-life of 5568 years) |
Post-bomb dates are often reported as F14C or fraction modern carbon. Since software such as Bacon expects radiocarbon ages, this function can be used to calculate F14C values from radiocarbon ages. The reverse function of F14C.age.
F14C values from C14 ages.
C14toF14C(-2000, 20)C14toF14C(-2000, 20)
Calculate pMC values from radiocarbon ages
C14topMC(y, er = NULL, decimals = 5, lambda = 8033)C14topMC(y, er = NULL, decimals = 5, lambda = 8033)
y |
Reported mean of the C14 age. |
er |
Reported error of the C14 age. |
decimals |
Amount of decimals required for the pMC value. Defaults to 5. |
lambda |
The mean-life of radiocarbon (based on Libby half-life of 5568 years) |
Post-bomb dates are often reported as pMC or percent modern carbon. Since Bacon expects radiocarbon ages, this function can be used to calculate pMC values from radiocarbon ages. The reverse function of pMCtoC14.
pMC values from C14 ages.
C14topMC(-2000, 20) C14topMC(-2000, 20, 1)C14topMC(-2000, 20) C14topMC(-2000, 20, 1)
calculate BC/AD ages from cal BP ages
calBPtoBCAD(x, zero = TRUE)calBPtoBCAD(x, zero = TRUE)
x |
The calBP age(s) to be translated into BC/AD ages. |
zero |
Whether or not zero BC/AD should be included. Defaults to 0. |
Turn cal BP ages into BC/AD (or BCE/CE). Negative ages indicate BC, positive ages AD. Since the Gregorian and Julian calendars do not include 0 BCAD (i.e., 31 December of 1 BC is followed by 1 January of AD 1), zero can be omitted. The years then go from 1 (AD) to -1 (i.e., 1 BC). Other calendars, such as the astronomical one, do include zero. The often-used BCE/CE ages are equivalent to BC/AD.
The BC/AD age(s). BC ages are negative, AD ages are positive.
calBPtoBCAD(2024) calBPtoBCAD(1945:1955, zero=TRUE) calBPtoBCAD(1945:1955, zero=FALSE)calBPtoBCAD(2024) calBPtoBCAD(1945:1955, zero=TRUE) calBPtoBCAD(1945:1955, zero=FALSE)
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding 14C age and error are returned.
calBPtoC14( x, cc = 1, postbomb = FALSE, rule = 1, cc.dir = NULL, thiscurve = NULL )calBPtoC14( x, cc = 1, postbomb = FALSE, rule = 1, cc.dir = NULL, thiscurve = NULL )
x |
The cal BP year. |
cc |
calibration curve for C14 (see |
postbomb |
Whether or not to use a postbomb curve (see |
rule |
How should R's approx function deal with extrapolation. If |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
Interpolation is used, and values outside the calibration curve are given as NA. For negative cal BP ages, a postbomb curve will have to be provided.
The calibration-curve 14C year belonging to the entered cal BP age
Maarten Blaauw
calBPtoC14(100)calBPtoC14(100)
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding F14C value and error are returned.
calBPtoD14C( x, cc = 1, postbomb = FALSE, rule = 1, cc.dir = NULL, thiscurve = NULL )calBPtoD14C( x, cc = 1, postbomb = FALSE, rule = 1, cc.dir = NULL, thiscurve = NULL )
x |
The cal BP year. |
cc |
calibration curve for C14 (see |
postbomb |
Whether or not to use a postbomb curve (see |
rule |
How should R's approx function deal with extrapolation. If |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
Interpolation is used, and values outside the calibration curve are given as NA. For negative cal BP ages, a postbomb curve will have to be provided.
The calibration-curve 14C year belonging to the entered cal BP age
Maarten Blaauw
calBPtoD14C(100)calBPtoD14C(100)
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding F14C value and error are returned.
calBPtoF14C( x, cc = 1, postbomb = FALSE, rule = 1, cc.dir = NULL, thiscurve = NULL )calBPtoF14C( x, cc = 1, postbomb = FALSE, rule = 1, cc.dir = NULL, thiscurve = NULL )
x |
The cal BP year. |
cc |
calibration curve for C14 (see |
postbomb |
Whether or not to use a postbomb curve (see |
rule |
How should R's approx function deal with extrapolation. If |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
Interpolation is used, and values outside the calibration curve are given as NA. For negative cal BP ages, a postbomb curve will have to be provided.
The calibration-curve 14C year belonging to the entered cal BP age
Maarten Blaauw
calBPtoF14C(100)calBPtoF14C(100)
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding F14C value and error are returned.
calBPtopMC( x, cc = 1, postbomb = FALSE, rule = 1, cc.dir = NULL, thiscurve = NULL )calBPtopMC( x, cc = 1, postbomb = FALSE, rule = 1, cc.dir = NULL, thiscurve = NULL )
x |
The cal BP year. |
cc |
calibration curve for C14 (see |
postbomb |
Whether or not to use a postbomb curve (see |
rule |
How should R's approx function deal with extrapolation. If |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
Interpolation is used, and values outside the calibration curve are given as NA. For negative cal BP ages, a postbomb curve will have to be provided.
The calibration-curve 14C year belonging to the entered cal BP age
Maarten Blaauw
calBPtopMC(100)calBPtopMC(100)
Calculate the calibrated distribution of a radiocarbon date.
caldist( y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, is.F = FALSE, as.F = FALSE, thiscurve = NULL, yrsteps = FALSE, cc.resample = FALSE, dist.res = 200, threshold = 0.001, normal = TRUE, t.a = 3, t.b = 4, normalise = TRUE, BCAD = FALSE, rule = 1, cc.dir = NULL )caldist( y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, is.F = FALSE, as.F = FALSE, thiscurve = NULL, yrsteps = FALSE, cc.resample = FALSE, dist.res = 200, threshold = 0.001, normal = TRUE, t.a = 3, t.b = 4, normalise = TRUE, BCAD = FALSE, rule = 1, cc.dir = NULL )
y |
Uncalibrated radiocarbon age |
er |
Lab error of the radiocarbon age |
cc |
Calibration curve to use. Defaults to IntCal20 ( |
postbomb |
Whether or not to use a postbomb curve. Required for negative radiocarbon ages. |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
is.F |
Set this to TRUE if the provided age and error are in the F14C realm. |
as.F |
Whether or not to calculate ages in the F14C realm. Defaults to |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
yrsteps |
Steps to use for interpolation. Defaults to the cal BP steps in the calibration curve |
cc.resample |
The IntCal20 curves have different densities (every year between 0 and 5 kcal BP, then every 5 yr up to 15 kcal BP, then every 10 yr up to 25 kcal BP, and then every 20 yr up to 55 kcal BP). If calibrated ages span these density ranges, their drawn heights can differ, as can their total areas (which should ideally all sum to the same size). To account for this, resample to a constant time-span, using, e.g., |
dist.res |
As an alternative to yrsteps, provide the amount of 'bins' in the distribution |
threshold |
Report only values above a threshold. Defaults to |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2016). |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
normalise |
Sum the entire calibrated distribution to 1. Defaults to |
BCAD |
Which calendar scale to use. Defaults to cal BP, |
rule |
Which extrapolation rule to use. Defaults to |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
The probability distribution(s) as two columns: cal BP ages and their associated probabilities
calib <- caldist(130,10) plot(calib, type="l") postbomb <- caldist(-3030, 20, postbomb=1, BCAD=TRUE)calib <- caldist(130,10) plot(calib, type="l") postbomb <- caldist(-3030, 20, postbomb=1, BCAD=TRUE)
Visualise how a date calibrates using the t distribution and the normal distribution.
calib.t( y = 2450, er = 50, t.a = 3, t.b = 4, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, as.F = FALSE, BCAD = FALSE, cc.dir = c(), normal.col = "red", normal.lwd = 1.5, t.col = rgb(0, 0, 0, 0.25), t.border = rgb(0, 0, 0, 0, 0.25), xlim = c(), ylim = c() )calib.t( y = 2450, er = 50, t.a = 3, t.b = 4, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, as.F = FALSE, BCAD = FALSE, cc.dir = c(), normal.col = "red", normal.lwd = 1.5, t.col = rgb(0, 0, 0, 0.25), t.border = rgb(0, 0, 0, 0, 0.25), xlim = c(), ylim = c() )
y |
The reported mean of the date. |
er |
The reported error of the date. |
t.a |
Value for the t parameter |
t.b |
Value for the t parameter |
cc |
calibration curve for the radiocarbon date(s) (see the |
postbomb |
Which postbomb curve to use for negative 14C dates. |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
as.F |
Whether or not to calculate ages in the F14C realm. Defaults to |
BCAD |
Which calendar scale to use. Defaults to cal BP, |
cc.dir |
Directory where the calibration curves for C14 dates |
normal.col |
Colour of the normal curve |
normal.lwd |
Line width of the normal curve |
t.col |
Colour of the t histogram |
t.border |
Colour of the border of the t histogram |
xlim |
x axis limits |
ylim |
y axis limits |
Radiocarbon and other dates are usually modelled using the normal distribution (red curve). The t approach (grey distribution) however allows for wider tails and thus tends to better accommodate outlying dates. This distribution requires two parameters, called 'a' and 'b'.
Maarten Blaauw
calib.t()calib.t()
Calibrate individual 14C dates, plot them and report calibrated ranges.
calibrate( age = 2450, error = 50, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, bombalert = TRUE, thiscurve = c(), as.F = FALSE, reservoir = 0, prob = 0.95, BCAD = FALSE, ka = FALSE, draw = TRUE, cal.lab = c(), C14.lab = c(), cal.lim = c(), C14.lim = c(), cc.col = rgb(0, 0.5, 0, 0.7), cc.fill = rgb(0, 0.5, 0, 0.7), date.col = "red", dist.col = rgb(0, 0, 0, 0.3), dist.fill = rgb(0, 0, 0, 0.3), hpd.fill = rgb(0, 0, 0, 0.3), dist.height = 0.3, dist.float = c(0.01, 0.01), cal.rev = FALSE, yr.steps = FALSE, cc.resample = 5, threshold = 5e-04, edge = TRUE, normal = TRUE, t.a = 3, t.b = 4, rounded = 1, every = 1, extend.range = 0.05, legend.cex = 0.8, legend1.loc = "topleft", legend2.loc = "topright", print.truncate.warning = TRUE, mgp = c(2, 1, 0), mar = c(3, 3, 1, 1), xaxs = "i", yaxs = "i", bty = "l", cc.dir = NULL, cc.er = 0, ... )calibrate( age = 2450, error = 50, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, bombalert = TRUE, thiscurve = c(), as.F = FALSE, reservoir = 0, prob = 0.95, BCAD = FALSE, ka = FALSE, draw = TRUE, cal.lab = c(), C14.lab = c(), cal.lim = c(), C14.lim = c(), cc.col = rgb(0, 0.5, 0, 0.7), cc.fill = rgb(0, 0.5, 0, 0.7), date.col = "red", dist.col = rgb(0, 0, 0, 0.3), dist.fill = rgb(0, 0, 0, 0.3), hpd.fill = rgb(0, 0, 0, 0.3), dist.height = 0.3, dist.float = c(0.01, 0.01), cal.rev = FALSE, yr.steps = FALSE, cc.resample = 5, threshold = 5e-04, edge = TRUE, normal = TRUE, t.a = 3, t.b = 4, rounded = 1, every = 1, extend.range = 0.05, legend.cex = 0.8, legend1.loc = "topleft", legend2.loc = "topright", print.truncate.warning = TRUE, mgp = c(2, 1, 0), mar = c(3, 3, 1, 1), xaxs = "i", yaxs = "i", bty = "l", cc.dir = NULL, cc.er = 0, ... )
age |
Mean of the uncalibrated C-14 age. |
error |
Error of the uncalibrated C-14 age. |
cc |
Calibration curve for C-14 dates (1, 2, 3, or 4, or, e.g., "IntCal20", "Marine20", "SHCal20", "nh1", "sh3", or "mixed"). |
postbomb |
Whether or not this is a postbomb age. Defaults to FALSE. |
deltaR |
Age offset (e.g. for marine samples). Can also be provided as option 'reservoir'. |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). Can also be provided within option 'reservoir'. |
bombalert |
Warn if a date is close to the lower limit of the IntCal curve. Defaults to |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). Defaults to c(). |
as.F |
Whether or not to calculate ages in the F14C realm. Defaults to |
reservoir |
Reservoir age, or reservoir age and age offset as two values (e.g., |
prob |
Probability confidence intervals (between 0 and 1). |
BCAD |
Use BC/AD or cal BP scale (default cal BP). |
ka |
Use thousands of years instead of years in the plots and hpd ranges. Defaults to FALSE. |
draw |
Whether or not to draw the date. Can be set as FALSE to speed up things |
cal.lab |
Label of the calendar/horizontal axis. Defaults to the calendar scale, but alternative names can be provided. |
C14.lab |
Label of the C-14/vertical axis. Defaults to the 14C scale, but alternative names can be provided. |
cal.lim |
Minimum and maximum of calendar axis (default calculated automatically). |
C14.lim |
Minimum and maximum of C-14 axis (default calculated automatically). |
cc.col |
Colour of the lines of the calibration curve. Defaults to semi-transparent dark green; |
cc.fill |
Colour of the inner part of the calibration curve. Defaults to semi-transparent dark green; |
date.col |
Colour of the "dot-bar" plot of the C14 date. Defaults to |
dist.col |
Colour of the outer lines of the distributions. Defaults to semi-transparent grey, |
dist.fill |
Colour of the inner part of the distributions. Defaults to semi-transparent grey, |
hpd.fill |
Colour of the highest posterior density. Defaults to semi-transparent grey, |
dist.height |
Maximum height of the C14 and calibrated distributions (as proportion of the invisible secondary axes). Defaults to 0.3. |
dist.float |
The probability distributions float a bit above the axes by default. Can be set to distinct heights of the axes, e.g.: |
cal.rev |
Whether or not to reverse the direction of the calendar axis. |
yr.steps |
Temporal resolution at which C-14 ages are calibrated (in calendar years). By default follows the spacing in the calibration curve. |
cc.resample |
The IntCal20 curves have different densities (every year between 0 and 5 kcal BP, then every 5 yr up to 15 kcal BP, then every 10 yr up to 25 kcal BP, and then every 20 yr up to 55 kcal BP). If calibrated ages span these density ranges, their drawn heights can differ, as can their total areas (which should ideally all sum to the same size). To account for this, resample to a constant time-span, using, e.g., cc.resample=5 for 5-yr timespans. |
threshold |
Below which value should probabilities be excluded from calculations. |
edge |
How to treat dates are at or beyond the edge of the calibration curve. If dates are truncated, a warning is given. If they lie beyond the calibration curve, an error is given. |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2016). |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
rounded |
Rounding of the percentages of the reported hpd ranges. Defaults to 1 decimal. |
every |
Yearly precision (defaults to |
extend.range |
Range by which the axes are extended beyond the data limits. Defaults to 5%. |
legend.cex |
Size of the font of the legends. Defaults to 0.8. |
legend1.loc |
Where the first legend (with the calibration curve name and the uncalibrated date) is plotted. Defaults to topleft. |
legend2.loc |
Where the second legend (with the hpd ranges) is plotted. Defaults to topright. |
print.truncate.warning |
Whether or not a truncation warning is printed on the plot. Defaults to |
mgp |
Axis text margins (where should titles, labels and tick marks be plotted). |
mar |
Plot margins (amount of white space along edges of axes 1-4). |
xaxs |
Whether or not to extend the limits of the horizontal axis. Defaults to |
yaxs |
Whether or not to extend the limits of the vertical axis. Defaults to |
bty |
Draw a box around the graph ("n" for none, and "l", "7", "c", "u", "]" or "o" for correspondingly shaped boxes). |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
cc.er |
The error of the calibration curve. Only used for plotting the uncalibrated C14 distribution, which by default only shows the date's uncertainty (the calibration curve uncertainty is indeed taken into account during calibration). If known, the calibration curve's error can be added. |
... |
Other plotting parameters. |
Type calibrate() to see how a date of 2450 +- 50 14C BP gets calibrated (the calibration curve happens to show
a plateau around this 14C age). To calibrate a different date, provide its reported mean and error (1
standard deviation error as reported by the radiocarbon laboratory) as follows: calibrate(mean, error),
e.g., for a date of 130 +- 10 14C BP, type calibrate(age=130, error=10) or, shorter, calibrate(130,10).
In case the date has a reservoir effect or age offset, e.g. of 100 14C years, provide this as follows:
calibrate(130, 10, 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,10,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 and calibrate the date using that custom-built curve (cc="mixed").
If you prefer to work with, e.g., 68 % as opposed to the default 95 % confidence intervals,
type: calibrate(130, 10, prob=0.68) or calibrate(130, 10,, 0.68) (the commas between the brackets indicate the position of the option;
the standard deviation is the fourth option of the calibrate function). The calibrated distribution can be calculated
for every single calendar year (yrsteps=1) within a wide range of the 14C date. Probabilities below a threshold (default threshold=0.0005) will be neglected.
By default the northern hemisphere terrestrial calibration curve is used (cc=1 or cc1="IntCal20").
To use alternative curves, use cc=2 (cc2="Marine20"), cc=3 (cc3="SHCal20C"),
cc=4 (cc4="mixed.14C"), or specify a postbomb curve (e.g., cc="nh1").
Calibrate 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 t distribution (Christen and Perez 2016) instead,
set normal=FALSE provide values for t.a and t.b (defaults to t.a=3 and t.b=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. 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 standard deviation hpd ranges is considerable (c. 32%). Therefore the use of 95% calibrated ranges is preferable, and default.
Negative radiocarbon ages are calibrated with postbomb curves, but the user needs to tell which curve to use.
For example, to use the first of the three northern hemisphere curves, provide the option cc="nh1", cc="nh2", cc="nh3",
while for southern hemisphere samples, use cc="sh1-2" or cc="sh3".
A graph of the calibration is produced, 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 cal.lim, C14.lim.
The titles of both axis can be changed by providing alternative titles to cal.lab and/or C14.lab. The heights of the distributions of the 14C and calibrated
ages can be set to alternative values using dist.height (default 0.3 which plots the distribution up to 30% of the height of the entire graph).
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 distributions, and the highest posterior density (hpd)
ranges, can be changed by providing an alternative colour in date.col, cc.col, dist.col, and/or hpd.col, respectively.
The default colours are transparent grey for the dates 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.
A graph of the raw and calibrated C-14 date, the calibrated ranges and, invisibly, the calibrated distribution and hpd ranges.
calibrate() calibrate(130, 10) cal <- calibrate(2550, 20, reservoir=100) cal; plot(cal[[1]]) calibrate(130, 10, prob=0.68) calibrate(age=130, error=10, BCAD=TRUE) calibrate(4450, 40, reservoir=c(100, 50))calibrate() calibrate(130, 10) cal <- calibrate(2550, 20, reservoir=100) cal; plot(cal[[1]]) calibrate(130, 10, prob=0.68) calibrate(age=130, error=10, BCAD=TRUE) calibrate(4450, 40, reservoir=c(100, 50))
Given an observed radiocarbon age, remove the impact of contamination (for example, 1% contamination with modern carbon) to estimate the true/target age
clean( y, er = 0, percentage, percentage.error = 0, F.contam = 1, F.contam.er = 0, MC = TRUE, its = 10000, roundby = 1, decimals = 5, visualise = TRUE, talk = TRUE, eq.x = 5, eq.y = c(), eq.size = 0.75, true.col = "darkgreen", observed.col = "blue", contamination.col = "red", true.pch = 20, observed.pch = 18, contamination.pch = 17, true.name = "true", xlab = "contamination (%)", ylab = "F14C", ylim = c(), bty = "l" )clean( y, er = 0, percentage, percentage.error = 0, F.contam = 1, F.contam.er = 0, MC = TRUE, its = 10000, roundby = 1, decimals = 5, visualise = TRUE, talk = TRUE, eq.x = 5, eq.y = c(), eq.size = 0.75, true.col = "darkgreen", observed.col = "blue", contamination.col = "red", true.pch = 20, observed.pch = 18, contamination.pch = 17, true.name = "true", xlab = "contamination (%)", ylab = "F14C", ylim = c(), bty = "l" )
y |
The observed radiocarbon age |
er |
The error of the observed radiocarbon age |
percentage |
Relative amount of contamination. Must be between 0 and 100 (%) |
percentage.error |
Uncertainty of the contamination. Assumed to be normally distributed (which fails close to 0% or 100% contamination levels). Defaults to 0%. |
F.contam |
The F14C of the contamination. Set at 1 for carbon of modern radiocarbon age, at 0 for 14C-free carbon, or anywhere inbetween. |
F.contam.er |
The error of the contamination. Defaults to 0. |
MC |
Whether or not to use Monte Carlo iterations to estimate the values. Defaults to TRUE, because it treats uncertainties better than if set to FALSE. |
its |
Amount of iterations to use if MC=TRUE. Defaults to 10,000. |
roundby |
Rounding of the output for C14 ages. Defaults to 1 decimal. |
decimals |
Rounding of the output. Since details matter here, the default is to provide 5 decimals. |
visualise |
By default, a plot is made to visualise the target and observed F14C values, together with the inferred contamination. |
talk |
Whether or not to report the calculations made. Defaults to |
eq.x |
Leftmost location of the equation. Defaults to |
eq.y |
Vertical location of the equation. Defaults to the top of the graph. |
eq.size |
Size of the font of the equation. In case the equation gets jumbled up upon resizing of a graphical device, just issue the previous 'clean' command again. Defaults to |
true.col |
Colour for the target/true values. Defaults to "darkgreen". |
observed.col |
Colour for the observed values. Defaults to blue. |
contamination.col |
Colour for the contamination values. Defaults to red. |
true.pch |
Icon for the true/target date. Defaults to a filled circle. |
observed.pch |
Icon for the observed. Defaults to a diamond |
contamination.pch |
Icon for the contamination. Defaults to a triangle. |
true.name |
Name of the label of the true/target date |
xlab |
Name of the x-axis. Defaults to 'contamination (%)'. |
ylab |
Name of the y-axis. Defaults to 'F14C'. |
ylim |
Limits of the y-axis. Calculated automatically by default. |
bty |
Draw a box around a box of a certain shape. Defaults to |
Whereas the function takes C14 ages and percentage contamination as input, internal calculations are done in the F14C realm and using fractions (between 0 and 1). The central calculation is 'F_true = ((1-frac)*F_obs) - (frac*F_contam)', where 'F_true' is the true or target age in F14C, 'frac' is the fraction of contamination, 'F_obs' is the F14C of the observed C14 age, and 'F_contam' is the F activity of the contamination. In some extreme cases, the calculations will spit out unexpected results. Messages will be provided in most of these cases.
The true/target radiocarbon age and error
Maarten Blaauw
# 1% contamination with modern carbon (no uncertainties in contamination's percentage or F) clean(5000, 20, 1, 0, 1, 0) # now with errors: clean(5000, 20, 1, 0.1, 1, 0.1)# 1% contamination with modern carbon (no uncertainties in contamination's percentage or F) clean(5000, 20, 1, 0, 1, 0) # now with errors: clean(5000, 20, 1, 0.1, 1, 0.1)
Given a true/target radiocarbon age, calculate the impact of contamination (for example, 1% contamination with modern carbon) on the observed age. Can optionally include contamination uncertainties, but then Monte Carlo iterations should be used (option MC=TRUE).
contaminate( y, er = 0, percentage, percentage.error = 0, F.contam = 1, F.contam.er = 0, MC = TRUE, its = 10000, decimals = 5, roundby = 1, visualise = TRUE, talk = TRUE, eq.x = 5, eq.y = c(), eq.size = 0.75, true.col = "darkgreen", observed.col = "blue", contamination.col = "red", true.pch = 20, observed.pch = 18, contamination.pch = 17, true.name = "true", xlab = "contamination (%)", ylab = "F14C", ylim = c(), bty = "l" )contaminate( y, er = 0, percentage, percentage.error = 0, F.contam = 1, F.contam.er = 0, MC = TRUE, its = 10000, decimals = 5, roundby = 1, visualise = TRUE, talk = TRUE, eq.x = 5, eq.y = c(), eq.size = 0.75, true.col = "darkgreen", observed.col = "blue", contamination.col = "red", true.pch = 20, observed.pch = 18, contamination.pch = 17, true.name = "true", xlab = "contamination (%)", ylab = "F14C", ylim = c(), bty = "l" )
y |
The 'true' radiocarbon age |
er |
The error of the 'true' radiocarbon age |
percentage |
Relative amount of contamination. Must be between 0 and 1 |
percentage.error |
Uncertainty of the contamination. Assumed to be normally distributed (which fails close to 0% or 100% contamination levels). Defaults to 0%. |
F.contam |
the F14C of the contamination. Set at 1 for carbon of modern radiocarbon age, at 0 for 14C-free carbon, or anywhere inbetween. |
F.contam.er |
error of the contamination. Defaults to 0. |
MC |
Whether or not to use Monte Carlo iterations to estimate the values. Defaults to TRUE, because it treats uncertainties better than if set to FALSE. |
its |
Amount of iterations to use if MC=TRUE. Defaults to 10,000. |
decimals |
Rounding of the output for F values. Since details matter here, the default is to provide 5 decimals. |
roundby |
Rounding of the output for C14 ages. Defaults to 1 decimal. |
visualise |
By default, a plot is made to visualise the target and observed F14C values, together with the inferred contamination. |
talk |
Whether or not to report the calculations made. Defaults to |
eq.x |
Leftmost location of the equation. Defaults to |
eq.y |
Vertical location of the equation. Defaults to the top of the graph. |
eq.size |
Size of the font of the equation. In case the equation gets jumbled up upon resizing of a graphical device, just issue the previous 'clean' command again. Defaults to |
true.col |
Colour for the target/true values. Defaults to "darkgreen". |
observed.col |
Colour for the observed values. Defaults to blue. |
contamination.col |
Colour for the contamination values. Defaults to red. |
true.pch |
Icon for the true/target date. Defaults to a filled circle. |
observed.pch |
Icon for the observed. Defaults to a diamond. |
contamination.pch |
Icon for the contamination. Defaults to a triangle. |
true.name |
Name of the label of the true/target date |
xlab |
Name of the x-axis. Defaults to 'contamination (%)'. |
ylab |
Name of the y-axis. Defaults to 'F14C'. |
ylim |
Limits of the y-axis. Calculated automatically by default. |
bty |
Draw a box around a box of a certain shape. Defaults to |
Whereas the function takes C14 ages and percentage contamination as input, internal calculations are done in the F14C realm and using fractions (between 0 and 1). The central calculation is 'F_obs = ((1-frac)*F_true) + (frac*F_contam)', where 'F_obs' is the observed C14 age as F14C, 'frac' is the fraction of contamination, 'F_true' is the F14C of the true/target C14 age, and 'F_contam' is the F activity of the contamination. In some extreme cases, the calculations will spit out unexpected results. Messages will be provided in most of these cases.
The observed radiocarbon age and error
Maarten Blaauw
contaminate(5000, 20, 1, 0, 1) # 1% contamination with modern carbon contaminate(66e6, 1e6, 1, 0, 1) # dino bone, shouldn't be dated as way beyond the dating limitcontaminate(5000, 20, 1, 0, 1) # 1% contamination with modern carbon contaminate(66e6, 1e6, 1, 0, 1) # dino bone, shouldn't be dated as way beyond the dating limit
Transform D14C into C14 age
D14CtoC14(D14C, er = NULL, t)D14CtoC14(D14C, er = NULL, t)
D14C |
The Delta14C value to translate |
er |
Reported error of the D14C. Returns just the mean if left empty. |
t |
the cal BP age |
As explained by Heaton et al. 2020 (Radiocarbon), 14C measurements are commonly expressed in three domains: Delta14C, F14C and the radiocarbon age. This function translates Delta14C, the historical level of Delta14C in the year t cal BP, to C14 ages. Note that per convention, this function uses the Cambridge half-life, not the Libby half-life.
The corresponding C14 age
D14CtoC14(-10, 1, 238)D14CtoC14(-10, 1, 238)
Transform D14C into F14C
D14CtoF14C(D14C, er = NULL, t)D14CtoF14C(D14C, er = NULL, t)
D14C |
The Delta14C value to translate |
er |
Reported error of the D14C. Returns just the mean if left empty. |
t |
the cal BP age |
As explained by Heaton et al. 2020 (Radiocarbon), 14C measurements are commonly expressed in three domains: Delta14C, F14C and the radiocarbon age. This function translates Delta14C, the historical level of Delta14C in the year t cal BP, to F14C values. Note that per convention, this function uses the Cambridge half-life, not the Libby half-life.
The corresponding F14C value
D14CtoF14C(-10, 1, 238)D14CtoF14C(-10, 1, 238)
Transform D14C into pMC
D14CtopMC(D14C, er = NULL, t)D14CtopMC(D14C, er = NULL, t)
D14C |
The Delta14C value to translate |
er |
Reported error of the D14C. Returns just the mean if left empty. |
t |
the cal BP age |
As explained by Heaton et al. 2020 (Radiocarbon), 14C measurements are commonly expressed in three domains: Delta14C, F14C and the radiocarbon age. This function translates Delta14C, the historical level of Delta14C in the year t cal BP, to F14C values. Note that per convention, this function uses the Cambridge half-life, not the Libby half-life.
The corresponding F14C value
D14CtoF14C(-10, 1, 238)D14CtoF14C(-10, 1, 238)
Draw one or two of the calibration curves, or add a calibration curve to an existing plot.
draw.ccurve( cal1 = c(), cal2 = c(), cc1 = "IntCal20", cc2 = NA, cc1.postbomb = FALSE, cc2.postbomb = FALSE, BCAD = FALSE, realm = "C14", cal.lab = NA, cal.rev = FALSE, c14.lab = NA, c14.lim = NA, c14.rev = FALSE, ka = FALSE, add.yaxis = FALSE, cc1.col = rgb(0, 0, 1, 0.5), cc1.fill = rgb(0, 0, 1, 0.2), cc2.col = rgb(0, 0.5, 0, 0.5), cc2.fill = rgb(0, 0.5, 0, 0.2), add = FALSE, bty = "l", cc.dir = NULL, legend = "topleft", ... )draw.ccurve( cal1 = c(), cal2 = c(), cc1 = "IntCal20", cc2 = NA, cc1.postbomb = FALSE, cc2.postbomb = FALSE, BCAD = FALSE, realm = "C14", cal.lab = NA, cal.rev = FALSE, c14.lab = NA, c14.lim = NA, c14.rev = FALSE, ka = FALSE, add.yaxis = FALSE, cc1.col = rgb(0, 0, 1, 0.5), cc1.fill = rgb(0, 0, 1, 0.2), cc2.col = rgb(0, 0.5, 0, 0.5), cc2.fill = rgb(0, 0.5, 0, 0.2), add = FALSE, bty = "l", cc.dir = NULL, legend = "topleft", ... )
cal1 |
First calendar year for the plot. Defaults to 0 cal BP. |
cal2 |
Last calendar year for the plot. Defaults to 55,000 cal BP. |
cc1 |
Name of the calibration curve. Can be "IntCal20", "Marine20", "SHCal20", or for the previous curves "IntCal13", "Marine13" or "SHCal13". Can also be "nh1", "nh2", "nh3", "sh1-2", "sh3", "nh1_monthly", "nh1_monthly", "nh2_monthly", "nh3_monthly", "sh1-2_monthly", "sh3_monthly", "Kure", "LevinKromer" or "Santos" for postbomb curves. |
cc2 |
Optional second calibration curve to plot. Can be "IntCal20", "Marine20", "SHCal20", or for the previous curves "IntCal13", "Marine13" or "SHCal13". Defaults to nothing, NA. |
cc1.postbomb |
Use |
cc2.postbomb |
Use |
BCAD |
The calendar scale of graphs and age output-files is in cal BP (calendar or calibrated years before the present, where the present is AD 1950) by default, but can be changed to BC/AD using |
realm |
Which 'realm' of radiocarbon to use. Defaults to |
cal.lab |
The labels for the calendar axis (default |
cal.rev |
Reverse the calendar axis. |
c14.lab |
Label for the C-14 axis. Defaults to 14C BP (or 14C kBP if ka=TRUE). |
c14.lim |
Axis limits for the C-14 axis. Calculated automatically by default. |
c14.rev |
Reverse the C-14 axis. |
ka |
Use kcal BP (and C14 kBP). |
add.yaxis |
Whether or not to plot the second calibration. Defaults to |
cc1.col |
Colour of the calibration curve (outline). |
cc1.fill |
Colour of the calibration curve (fill). |
cc2.col |
Colour of the calibration curve (outline), if activated (default cc2=NA). |
cc2.fill |
Colour of the calibration curve (fill), if activated (default cc2=NA). |
add |
Whether or not to add the curve(s) to an existing plot. Defaults to FALSE, which draws a new plot |
bty |
Draw a box around a box of a certain shape. Defaults to |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
legend |
Location of the legend (only activated if more than one curve is plotted). Plotted in the topleft corner by default. Use |
... |
Any additional optional plotting parameters. |
A plot of the calibration curve
draw.ccurve() draw.ccurve(1000, 3000, cc2="Marine20") draw.ccurve(1800, 2020, BCAD=TRUE, cc2="nh1", cc2.postbomb=TRUE) draw.ccurve(1800, 2010, BCAD=TRUE, cc2="nh1", add.yaxis=TRUE)draw.ccurve() draw.ccurve(1000, 3000, cc2="Marine20") draw.ccurve(1800, 2020, BCAD=TRUE, cc2="nh1", cc2.postbomb=TRUE) draw.ccurve(1800, 2010, BCAD=TRUE, cc2="nh1", add.yaxis=TRUE)
Show how contamination with different fractions of modern carbon affect observed C-14 ages.
draw.contamination( from = 0, to = 50000, ka = TRUE, age.res = 500, xlim = c(), ylim = c(), colours = rainbow(age.res), max.contam = 0.1, contam.F14C = 1, contam.legend = max.contam * c(1/100, (1:5)/50, (1:4)/5, 1), legend.pos = 0.07, legend.cex = 0.6, grid = TRUE, xaxs = "i", yaxs = "i" )draw.contamination( from = 0, to = 50000, ka = TRUE, age.res = 500, xlim = c(), ylim = c(), colours = rainbow(age.res), max.contam = 0.1, contam.F14C = 1, contam.legend = max.contam * c(1/100, (1:5)/50, (1:4)/5, 1), legend.pos = 0.07, legend.cex = 0.6, grid = TRUE, xaxs = "i", yaxs = "i" )
from |
Minimum 14C age for the plot. Defaults to 0 |
to |
Maximum 14C age for the plot. Defaults to 50e3. |
ka |
Use C14 kBP. Defaults to TRUE. |
age.res |
Resolution of age scale. Defaults to 500, which results in smooth curves. Higher numbers will take longer to draw. |
xlim |
Limits of the horizontal axis. |
ylim |
Limits of the vertical axis. |
colours |
Colours of the percentages. Defaults to rainbow colours. |
max.contam |
Maximum contamination level as a fraction of the sample. Defaults to 0.1 (10%). |
contam.F14C |
14C activity of the sample. Defaults to 'modern' 14C, F14C=1. |
contam.legend |
Percentages for which numbers will be plotted. |
legend.pos |
horizontal position beyond which the percentage values will be plotted |
legend.cex |
font size of the legend |
grid |
Whether to plot a grid. Defaults to TRUE |
xaxs |
Whether or not to extend the limits of the horizontal axis. Defaults to |
yaxs |
Whether or not to extend the limits of the vertical axis. Defaults to |
A plot of real and observed (contamination-impacted) C14 ages.
draw.contamination() draw.contamination(40e3, 50e3, ka=FALSE)draw.contamination() draw.contamination(40e3, 50e3, ka=FALSE)
Draw a proxy of the atmospheric 14C concentration (d14C) as well as the calibration curve.
draw.D14C( cal1 = c(), cal2 = c(), cc = rintcal::ccurve(), BCAD = FALSE, mar = c(4, 4, 1, 4), mgp = c(2.5, 1, 0), xaxs = "r", yaxs = "r", bty = "u", ka = FALSE, cal.lab = c(), cal.rev = FALSE, C14.lab = c(), C14.lim = c(), cc.col = rgb(0, 0.5, 0, 0.5), cc.border = rgb(0, 0.5, 0, 0.5), D14C.lab = c(), D14C.lim = c(), D14C.col = rgb(0, 0, 1, 0.5), D14C.border = rgb(0, 0, 1, 0.5) )draw.D14C( cal1 = c(), cal2 = c(), cc = rintcal::ccurve(), BCAD = FALSE, mar = c(4, 4, 1, 4), mgp = c(2.5, 1, 0), xaxs = "r", yaxs = "r", bty = "u", ka = FALSE, cal.lab = c(), cal.rev = FALSE, C14.lab = c(), C14.lim = c(), cc.col = rgb(0, 0.5, 0, 0.5), cc.border = rgb(0, 0.5, 0, 0.5), D14C.lab = c(), D14C.lim = c(), D14C.col = rgb(0, 0, 1, 0.5), D14C.border = rgb(0, 0, 1, 0.5) )
cal1 |
First calendar year for the plot. Defaults to youngest calendar age of the calibration curve |
cal2 |
Last calendar year for the plot. Defaults to oldest calendar age of the calibration curve |
cc |
The calibration curve to use. Defaults to IntCal20 |
BCAD |
The calendar scale of graphs and age output-files is in cal BP (calendar or calibrated years before the present, where the present is AD 1950) by default, but can be changed to BC/AD using |
mar |
Plot margins (amount of white space along edges of axes 1-4). |
mgp |
Axis text margins (where should titles, labels and tick marks be plotted). |
xaxs |
Whether or not to extend the limits of the horizontal axis. Defaults to |
yaxs |
Whether or not to extend the limits of the vertical axis. Defaults to |
bty |
Draw a box around the graph ("n" for none, and "l", "7", "c", "u", "]" or "o" for correspondingly shaped boxes). |
ka |
Use kcal BP (and C14 kBP). Defaults to FALSE. |
cal.lab |
The labels for the calendar axis (default |
cal.rev |
Reverse the calendar axis (defaults to FALSE). |
C14.lab |
Label for the C-14 axis. Defaults to 14C BP (or 14C kBP if ka=TRUE). |
C14.lim |
Limits for the C-14 axis. Calculated automatically by default. |
cc.col |
Colour of the calibration curve (fill). |
cc.border |
Colour of the calibration curve (border). |
D14C.lab |
Label for the D14C axis. |
D14C.lim |
Axis limits for the D14C axis. Calculated automatically by default. |
D14C.col |
Colour of the D14C curve (fill). |
D14C.border |
Colour of the D14C curve (border). |
A plot of d14C and the calibration curve
draw.D14C() draw.D14C(30e3, 55e3, ka=TRUE) draw.D14C(cc=rintcal::ccurve("NH1_monthly"), BCAD=TRUE)draw.D14C() draw.D14C(30e3, 55e3, ka=TRUE) draw.D14C(cc=rintcal::ccurve("NH1_monthly"), BCAD=TRUE)
Add individual or multiple calibrated dates to a plot.
draw.dates( age, error, depth = c(), cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, thiscurve = c(), oncurve = FALSE, realm = "C", reservoir = c(), normal = TRUE, t.a = 3, t.b = 4, prob = 0.95, threshold = 0.001, BCAD = FALSE, draw.hpd = TRUE, hpd.border = NA, hpd.col = rgb(0, 0, 1, 0.7), cal.hpd.col = rgb(0, 0.5, 0.5, 0.35), rounded = 0.1, every = 1, mirror = TRUE, up = TRUE, draw.base = TRUE, col = rgb(0, 0, 1, 0.3), border = rgb(0, 0, 1, 0.5), cal.col = rgb(0, 0.5, 0.5, 0.35), cal.border = rgb(0, 0.5, 0.5, 0.35), add = FALSE, ka = FALSE, rotate.axes = FALSE, ex = 0.8, normalise = TRUE, cc.col = rgb(0, 0.5, 0, 0.5), cc.border = rgb(0, 0.5, 0, 0.5), cc.resample = 5, age.lab = c(), age.lim = c(), age.rev = FALSE, d.lab = c(), d.lim = c(), d.rev = TRUE, labels = c(), label.x = 1, label.y = c(), label.cex = 0.8, label.col = border, label.offset = c(0, 0), label.adj = c(1, 0), label.rot = 0, cc.dir = NULL, dist.res = 100, ... )draw.dates( age, error, depth = c(), cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, thiscurve = c(), oncurve = FALSE, realm = "C", reservoir = c(), normal = TRUE, t.a = 3, t.b = 4, prob = 0.95, threshold = 0.001, BCAD = FALSE, draw.hpd = TRUE, hpd.border = NA, hpd.col = rgb(0, 0, 1, 0.7), cal.hpd.col = rgb(0, 0.5, 0.5, 0.35), rounded = 0.1, every = 1, mirror = TRUE, up = TRUE, draw.base = TRUE, col = rgb(0, 0, 1, 0.3), border = rgb(0, 0, 1, 0.5), cal.col = rgb(0, 0.5, 0.5, 0.35), cal.border = rgb(0, 0.5, 0.5, 0.35), add = FALSE, ka = FALSE, rotate.axes = FALSE, ex = 0.8, normalise = TRUE, cc.col = rgb(0, 0.5, 0, 0.5), cc.border = rgb(0, 0.5, 0, 0.5), cc.resample = 5, age.lab = c(), age.lim = c(), age.rev = FALSE, d.lab = c(), d.lim = c(), d.rev = TRUE, labels = c(), label.x = 1, label.y = c(), label.cex = 0.8, label.col = border, label.offset = c(0, 0), label.adj = c(1, 0), label.rot = 0, cc.dir = NULL, dist.res = 100, ... )
age |
Mean of the uncalibrated C-14 age (or multiple ages). |
error |
Error of the uncalibrated C-14 age (or ages). |
depth |
Depth(s) of the date(s). Defaults to their relative positions if no depths are provided. |
cc |
Calibration curve for C-14 dates (1, 2, 3, or 4, or, e.g., "IntCal20", "Marine20", "SHCal20", "nh1", "sh3", or "mixed"). If there are multiple dates but all use the same calibration curve, one value can be provided. |
postbomb |
Whether or not this is a postbomb age. Defaults to FALSE. |
deltaR |
Age offset (e.g. for marine samples). Can also be provided as option 'reservoir'. |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). Can also be provided within option 'reservoir'. |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). Defaults to c(). |
oncurve |
Whether or not to plot the calibration curve and then plot the dates onto this curve. Defaults to FALSE. |
realm |
If oncurve is used, by default the calibration curve is plotted in the C14 age realm. Alternatively, it can be provided as |
reservoir |
Reservoir age, or reservoir age and age offset. |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2009). |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
prob |
Probability confidence intervals (between 0 and 1). |
threshold |
Report only values above a threshold. Defaults to |
BCAD |
Use BC/AD or cal BP scale (default cal BP). |
draw.hpd |
Whether or not to draw the hpd ranges as a line |
hpd.border |
Colour of the border of the hpd intervals. Not drawn by default. |
hpd.col |
Colour of the hpd rectangle for all dates or radiocarbon dates |
cal.hpd.col |
Colour of the hpd rectangle for cal BP dates |
rounded |
Rounding for probabilities of reported hpd ranges. Defaults to 1 decimal. |
every |
Yearly precision of hpds (defaults to |
mirror |
Plot distributions mirrored, a bit like a swan. Confuses some people but looks nice to the author so is the default. |
up |
If mirror is set to FALSE, the distribution can be plotted facing upwards or downwards. |
draw.base |
By default, the base of the calibrated distributions is plotted. This can be avoided by supplying |
col |
Colour of the inside of the distribution |
border |
Colour of the border of the distribution |
cal.col |
Colour of the inside of distribution of non-radiocarbon dates that didn't need calibration |
cal.border |
Colour of the border of the distribution of non-radiocarbon dates that didn't need calibration |
add |
Whether or not to add the dates to an existing plot. If set to FALSE (default), a plot will be set up. |
ka |
Whether or not to plot ages as thousands of years. Defaults to |
rotate.axes |
By default, the calendar age axis is plotted on the horizontal axis, and depth/position on the vertical one. Use |
ex |
Exaggeration of the height of the distribution, defaults to |
normalise |
If TRUE, the age distributions are normalised by plotting each distribution with the same total area. Precise dates will therefore peak higher than less precise dates (default). If |
cc.col |
Colour of the calibration curve. Default semi-transparent darkgreen. |
cc.border |
Colour of the edges of the calibration curve. Default semi-transparent darkgreen. |
cc.resample |
The IntCal20 curves have different densities (every year between 0 and 5 kcal BP, then every 5 yr up to 15 kcal BP, then every 10 yr up to 25 kcal BP, and then every 20 yr up to 55 kcal BP). If calibrated ages span these density ranges, their drawn heights can differ, as can their total areas (which should ideally all sum to the same size). To account for this, resample to a constant time-span, using, e.g., |
age.lab |
Title of the calendar axis (if present) |
age.lim |
Limits of the calendar axis (if present) |
age.rev |
Reverse the age axis. Defaults to TRUE |
d.lab |
Title of the vertical axis (if present) |
d.lim |
Limits of the vertical axis (if present) |
d.rev |
Reverse the y-axis. Defaults to TRUE |
labels |
Add labels to the dates. Empty by default. |
label.x |
Horizontal position of the date labels. By default draws them before the youngest age (1), but can also draw them after the oldest age (2), or above its mean (3). |
label.y |
Vertical positions of the depths/labels. Defaults to 0 (or 1 if label.x is 3 or 4). |
label.cex |
Size of labels. |
label.col |
Colour of the labels. Defaults to the colour given to the borders of the dates. |
label.offset |
Offsets of the positions of the depths/labels, giving the x and y offsets. Defaults to c(0,0). |
label.adj |
Justification of the labels. Follows R's adj option: A value of "0" produces left-justified text, "0.5" (the default) centered text and "1" right-justified text. |
label.rot |
Rotation of the label. 0 by default (horizontal). |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
dist.res |
Resolution of the distribution polygons. Defaults to |
... |
Additional plotting options |
A plot of the (calibrated) dates
plot(0, xlim=c(500,0), ylim=c(0, 2)) draw.dates(130, 20, depth=1) x <- sort(runif(10, 1000, 10000)) # draw 10 random calendar ages cc <- rintcal::ccurve() # get the calibration curve y <- approx(cc[,1], cc[,2], x)$y # find the IntCal 14C ages er <- .01 * y draw.dates(y, er, 1:length(x)) # or draw on the calibration curve draw.dates(y, er, y, d.lab="Radiocarbon age (BP)") draw.ccurve(add=TRUE, cc1.col=rgb(0,.5,0,.5))plot(0, xlim=c(500,0), ylim=c(0, 2)) draw.dates(130, 20, depth=1) x <- sort(runif(10, 1000, 10000)) # draw 10 random calendar ages cc <- rintcal::ccurve() # get the calibration curve y <- approx(cc[,1], cc[,2], x)$y # find the IntCal 14C ages er <- .01 * y draw.dates(y, er, 1:length(x)) # or draw on the calibration curve draw.dates(y, er, y, d.lab="Radiocarbon age (BP)") draw.ccurve(add=TRUE, cc1.col=rgb(0,.5,0,.5))
Calculate C14 ages from F14C values of radiocarbon dates.
F14C.age(mn, sdev = c(), decimals = 5, lambda = 8033)F14C.age(mn, sdev = c(), decimals = 5, lambda = 8033)
mn |
Reported mean of the F14C |
sdev |
Reported error of the F14C. Returns just the mean if left empty. |
decimals |
Amount of decimals required for the radiocarbon age. Quite sensitive, defaults to 5. |
lambda |
The mean-life of radiocarbon (based on Libby half-life of 5568 years) |
Post-bomb dates are often reported as F14C or fraction modern carbon. Since Bacon expects radiocarbon ages, this function can be used to calculate radiocarbon ages from F14C values. The reverse function is age.F14C.
Radiocarbon ages from F14C values. If F14C values are above 100%, the resulting radiocarbon ages will be negative.
Calculate C14 ages from F14C values of radiocarbon dates.
F14CtoC14(F14C, er = NULL, decimals = 5, lambda = 8033)F14CtoC14(F14C, er = NULL, decimals = 5, lambda = 8033)
F14C |
Reported mean of the F14C |
er |
Reported error of the F14C. Returns just the mean if left empty. |
decimals |
Amount of decimals required for the radiocarbon age. Quite sensitive, defaults to 5. |
lambda |
The mean-life of radiocarbon (based on Libby half-life of 5568 years) |
Post-bomb dates are often reported as F14C (between 0 at c. 55 kcal BP and 1 at c. AD 1950). Since software such as Bacon expects radiocarbon ages, this function can be used to calculate radiocarbon ages from F14C values. The reverse function is age.F14C.
The radiocarbon ages from the F14C values. If F14C values are above 100%, the resulting radiocarbon ages will be negative.
F14CtoC14(1.10, 0.5) # a postbomb date, so with a negative C14 age F14CtoC14(.80, 0.5) # prebomb dates can also be calculatedF14CtoC14(1.10, 0.5) # a postbomb date, so with a negative C14 age F14CtoC14(.80, 0.5) # prebomb dates can also be calculated
Transform F14C into D14C
F14CtoD14C(F14C, er = NULL, t)F14CtoD14C(F14C, er = NULL, t)
F14C |
The F14C value to translate |
er |
Reported error of the F14C. Returns just the mean if left empty. |
t |
the cal BP age |
As explained by Heaton et al. 2020 (Radiocarbon), 14C measurements are commonly expressed in three domains: Delta14C, F14C and the radiocarbon age. This function translates F14C values into Delta14C, the historical level of Delta14C in the year t cal BP. Note that per convention, this function uses the Cambridge half-life, not the Libby half-life.
The corresponding D14C value
F14CtoD14C(0.89, .001, 900)F14CtoD14C(0.89, .001, 900)
Calculate pMC values from F14C values of radiocarbon dates.
F14CtopMC(F14C, er = NULL)F14CtopMC(F14C, er = NULL)
F14C |
Reported mean of the F14C |
er |
Reported error of the F14C. Returns just the mean if left empty. |
Post-bomb dates are often reported as F14C (between 0 at c. 55 kcal BP and 1 at c. AD 1950). Since software such as Bacon expects radiocarbon ages, this function can be used to calculate radiocarbon ages from F14C values. The reverse function is age.F14C.
The pMC values from the F14C values. Basically the original values multiplied by 100.
F14CtopMC(1.10, 0.5)F14CtopMC(1.10, 0.5)
Find the shells closest to a chosen coordinate, and plot the dR values and feeding ecology. Uses the marine database downloaded (30 Aug 2024) from calib.org/marine. See Reimer PJ, Reimer RW, 2001. A marine reservoir correction database and on-line interface. Radiocarbon 43:461-3.
find.shells( longitude, latitude, nearest = 50, colour = "dR", rainbow = FALSE, size = 2, mapsize = "large", mincol = "yellow", maxcol = "red", symbol = "feeding", symbol.legend = TRUE, ocean.col = "aliceblue", land.col = rgb(0, 0.5, 0, 0.6) )find.shells( longitude, latitude, nearest = 50, colour = "dR", rainbow = FALSE, size = 2, mapsize = "large", mincol = "yellow", maxcol = "red", symbol = "feeding", symbol.legend = TRUE, ocean.col = "aliceblue", land.col = rgb(0, 0.5, 0, 0.6) )
longitude |
Longitude of the point. Can only deal with one point at a time. |
latitude |
Latitude of the point. Can only deal with one point at a time. |
nearest |
The number of shell values to be returned. Defaults to 50. |
colour |
The variable to be plotted as colour. Expects a continuous variable. Defaults to 'dR'. |
rainbow |
Whether or not to use a rainbow scale to plot the variable. |
size |
Size of the symbols. Defaults to 2. |
mapsize |
Resolution of the map. Can be "small", "medium" or "large". If the latter, a high-resolution dataset will have to be downloaded using the R package 'rnaturalearthhires'. Since this package is on github but not on CRAN, you will have to download it yourself (using the command devtools::install_github("ropensci/rnaturalearthhires")). Defaults to 'medium' if 'rnaturalearthhires' is not installed, and to 'high' if it is installed. |
mincol |
Colour for minimum values. |
maxcol |
Colour for maximum values. |
symbol |
The variable to be plotted as symbol. Expects a categoric variable. Defaults to 'feeding'. |
symbol.legend |
Whether or not to plot the legend for the symbols. |
ocean.col |
Colour for the oceans. Defaults to |
land.col |
Colour for the land. Defaults to semi-transparent darkgreen: |
This function uses the 'rnaturalearth' package for country maps. If the high-resolution maps are desired, the 'rnaturalearthhires' package must be installed from GitHub.
A dataset with the n nearest dR values, and a plot of their coordinates.
UK <- find.shells(0, 55, mapsize="medium") mean(UK$dR) Caribbean <- find.shells(-70, 20, 30, mapsize="medium")UK <- find.shells(0, 55, mapsize="medium") mean(UK$dR) Caribbean <- find.shells(-70, 20, 30, mapsize="medium")
Estimate a missing radiocarbon age from a sample which has C14 dates on both the bulk and on fractions, but where 1 sample was too small to be dated. This can be used in for example soils separated into size fractions, where one of the samples turns out to be too small to be dated. Requires to have the bulk age, the ages of the dated fractions, and the carbon contents and weights of all fractions.
fractions( bulk_age, bulk_er, fractions_percC, fractions_weights, fractions_ages, fractions_errors, roundby = 1 )fractions( bulk_age, bulk_er, fractions_percC, fractions_weights, fractions_ages, fractions_errors, roundby = 1 )
bulk_age |
The age of the bulk/entire sample |
bulk_er |
The error of the age of the bulk/entire sample |
fractions_percC |
The %carbon contents of the fractions. If unknown, enter estimates (e.g., rep(1,4)) |
fractions_weights |
The weights of the fractions. The units are not important here as the weights are used to calculate the relative contributions of carbon within individual fractions to the entire sample. |
fractions_ages |
The radiocarbon ages of the individual fractions. The fraction without a date should be entered as NA. |
fractions_errors |
The errors of the radiocarbon ages of the individual fractions. The fraction without a date should be entered as NA. |
roundby |
Rounding of the reported age |
Cs <- c(.02, .05, .03, .04) # carbon contents of each fraction wghts <- c(5, 4, 2, .5) # weights for all fractions, e.g., in mg ages <- c(130, 130, 130, NA) # ages of all fractions. The unmeasured one is NA errors <- c(10, 12, 10, NA) # errors, unmeasured is NA fractions(150, 20, Cs, wghts, ages, errors) # assuming a bulk age of 150 +- 20 C14 BPCs <- c(.02, .05, .03, .04) # carbon contents of each fraction wghts <- c(5, 4, 2, .5) # weights for all fractions, e.g., in mg ages <- c(130, 130, 130, NA) # ages of all fractions. The unmeasured one is NA errors <- c(10, 12, 10, NA) # errors, unmeasured is NA fractions(150, 20, Cs, wghts, ages, errors) # assuming a bulk age of 150 +- 20 C14 BP
Calculate highest posterior density ranges of calibrated distribution
hpd( calib, prob = 0.95, return.raw = FALSE, BCAD = FALSE, age.round = 0, prob.round = 1, every = 0.1 )hpd( calib, prob = 0.95, return.raw = FALSE, BCAD = FALSE, age.round = 0, prob.round = 1, every = 0.1 )
calib |
The calibrated distribution, as returned from caldist() |
prob |
Probability range which should be calculated. Default |
return.raw |
The raw data to calculate hpds can be returned, e.g. to draw polygons of the calibrated distributions. Defaults to |
BCAD |
Which calendar scale to use. Defaults to cal BP, |
age.round |
Rounding for ages. Defaults to 0 decimals. |
prob.round |
Rounding for reported probabilities. Defaults to 1 decimal. |
every |
Yearly precision (defaults to 0.1, as a compromise between speed and accuracy). |
The highest posterior density ranges, as three columns: from age, to age, and the corresponding percentage(s) of the range(s)
hpd(caldist(130,20)) plot(tmp <- caldist(2450,50), type='l') abline(v=hpd(tmp)[,1:2], col=4)hpd(caldist(130,20)) plot(tmp <- caldist(2450,50), type='l') abline(v=hpd(tmp)[,1:2], col=4)
Find the calibrated probability of a cal BP age for a radiocarbon date. Can handle either multiple calendar ages for a single radiocarbon date, or a single calendar age for multiple radiocarbon dates.
l.calib( x, y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, thiscurve = c(), cc.dir = c(), normal = TRUE, as.F = FALSE, t.a = 3, t.b = 4 )l.calib( x, y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, thiscurve = c(), cc.dir = c(), normal = TRUE, as.F = FALSE, t.a = 3, t.b = 4 )
x |
The cal BP year. |
y |
The radiocarbon date's mean. |
er |
The radiocarbon date's lab error. |
cc |
calibration curve for the radiocarbon date(s) (see the |
postbomb |
Whether or not to use a postbomb curve. Required for negative radiocarbon ages. |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2016). |
as.F |
Whether or not to calculate ages in the F14C realm. Defaults to |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
The function cannot deal with multiple calibration curves if multiple calendar years or radiocarbon dates are entered.
The calibrated probability of a calendar age for a 14C age
Maarten Blaauw
l.calib(100, 130, 20) l.calib(100:110, 130, 20) # multiple calendar ages of a single date l.calib(100, c(130,150), c(15,20)) # multiple radiocarbon ages and a single calendar age plot(0:300, l.calib(0:300, 130, 20), type='l')l.calib(100, 130, 20) l.calib(100:110, 130, 20) # multiple calendar ages of a single date l.calib(100, c(130,150), c(15,20)) # multiple radiocarbon ages and a single calendar age plot(0:300, l.calib(0:300, 130, 20), type='l')
Find the shells that fit within a rectangular region (bounded by N, E, S and W), and plot the dR values and feeding ecology. Uses the marine database downloaded (30 Aug 2024) from calib.org/marine. See Reimer PJ, Reimer RW, 2001. A marine reservoir correction database and on-line interface. Radiocarbon 43:461-3. Expects the coordinates for the map to be provided (starting south, then clockwise as with R axes).
map.shells( S = 48, W = -15, N = 62, E = 5, colour = "dR", rainbow = FALSE, size = 2, mapsize = "large", mincol = "yellow", maxcol = "red", symbol = "feeding", symbol.legend = TRUE, ocean.col = "aliceblue", land.col = rgb(0, 0.5, 0, 0.6) )map.shells( S = 48, W = -15, N = 62, E = 5, colour = "dR", rainbow = FALSE, size = 2, mapsize = "large", mincol = "yellow", maxcol = "red", symbol = "feeding", symbol.legend = TRUE, ocean.col = "aliceblue", land.col = rgb(0, 0.5, 0, 0.6) )
S |
The southern limit of the rectangular region. |
W |
The western limit of the rectangular region. |
N |
The northern limit of the rectangular region. |
E |
The eastern limit of the rectangular region. |
colour |
The variable to be plotted as colour. Expects a continuous variable. Defaults to 'dR'. |
rainbow |
Whether or not to use a rainbow scale to plot the variable. |
size |
Size of the symbols. Defaults to 2. |
mapsize |
Resolution of the map. Can be "small", "medium" or "large". If the latter, a high-resolution dataset will have to be downloaded using the R package 'rnaturalearthhires'. Since this package is on github but not on CRAN, you will have to download it yourself (using the command devtools::install_github("ropensci/rnaturalearthhires")). Defaults to 'medium' if 'rnaturalearthhires' is not installed, and to 'high' if it is installed. |
mincol |
Colour for minimum values. |
maxcol |
Colour for maximum values. |
symbol |
The variable to be plotted as symbol. Expects a categoric variable. Defaults to 'feeding'. |
symbol.legend |
Whether or not to plot the legend for the symbols. |
ocean.col |
Colour for the oceans. Defaults to |
land.col |
Colour for the land. Defaults to semi-transparent darkgreen: |
This function uses the 'rnaturalearth' package for country maps. If the high-resolution maps are desired, the 'rnaturalearthhires' package must be installed from GitHub.
A plot and the relevant dR values.
N_UK <- map.shells(53, -11, 60, 2, mapsize="medium") mean(N_UK$dR)N_UK <- map.shells(53, -11, 60, 2, mapsize="medium") mean(N_UK$dR)
Given an observed and a target radiocarbon age, calculate the amount of contamination required to explain the observed age.
muck( y.obs, y.obs.er = 0, y.target, y.target.er = 0, F.contam = 1, F.contam.er = 0, MC = TRUE, its = 10000, roundby = 1, decimals = 3, visualise = TRUE, talk = TRUE, eq.x = 5, eq.y = c(), eq.size = 0.8, target.col = "darkgreen", observed.col = "blue", contamination.col = "red", target.pch = 20, observed.pch = 18, contamination.pch = 17, true.name = "target", xlab = "contamination (%)", ylab = "F14C", ylim = c(), bty = "l" )muck( y.obs, y.obs.er = 0, y.target, y.target.er = 0, F.contam = 1, F.contam.er = 0, MC = TRUE, its = 10000, roundby = 1, decimals = 3, visualise = TRUE, talk = TRUE, eq.x = 5, eq.y = c(), eq.size = 0.8, target.col = "darkgreen", observed.col = "blue", contamination.col = "red", target.pch = 20, observed.pch = 18, contamination.pch = 17, true.name = "target", xlab = "contamination (%)", ylab = "F14C", ylim = c(), bty = "l" )
y.obs |
The observed radiocarbon age |
y.obs.er |
The error of the observed radiocarbon age |
y.target |
the target radiocarbon age |
y.target.er |
The error of the target radiocarbon age. Not taken into account in the calculations. |
F.contam |
the F14C of the contamination. Set at 1 for carbon of modern radiocarbon age, at 0 for 14C-free carbon, or anywhere inbetween. |
F.contam.er |
The error of the contamination. Defaults to 0. |
MC |
Whether or not to use Monte Carlo iterations to estimate the values. Defaults to TRUE, because it treats uncertainties better than if set to FALSE. |
its |
Amount of iterations to use if MC=TRUE. Defaults to 10,000. |
roundby |
Rounding of the output for C14 ages. Defaults to 1 decimal. |
decimals |
Rounding of the output. Since details matter here, the default is to provide 5 decimals. |
visualise |
By default, a plot is made to visualise the target and observed F14C values, together with the inferred contamination. |
talk |
Whether or not to report the calculations made. Defaults to |
eq.x |
Leftmost location of the equation. Defaults to |
eq.y |
Vertical location of the equation. Defaults to the top of the graph. |
eq.size |
Size of the font of the equation. In case the equation gets jumbled up upon resizing of a graphical device, just issue the previous 'clean' command again. Defaults to |
target.col |
Colour for the target/true values. Defaults to darkgreen. |
observed.col |
Colour for the observed values. Defaults to blue. |
contamination.col |
Colour for the contamination values. Defaults to red. |
target.pch |
Icon for the target. Defaults to a filled circle. |
observed.pch |
Icon for the observed. Defaults to a diamond |
contamination.pch |
Icon for the contamination. Defaults to a triangle. |
true.name |
Name of the label of the true/target date |
xlab |
Name of the x-axis. Defaults to 'contamination (%)'. |
ylab |
Name of the y-axis. Defaults to 'F14C'. |
ylim |
Limits of the y-axis. Calculated automatically by default. |
bty |
Draw a box around a box of a certain shape. Defaults to |
Whereas the function takes true/target and observed C14 ages as input and percentage contamination as output, internal calculations are done in the F14C realm and using contamination fractions (between 0 and 1). The central calculation is 'frac = (F_obs - F_true) / (F_contam - F_true)', where 'frac' is the fraction of contamination to explain how we went from the observed to the true C14 age, 'F_obs' is the observed C14 age in F14C, 'F_true' is the true or target age in F14C, 'F_contam' is the F value of the contamination. In some extreme cases (e.g., if dividing by zero), the calculation will spit out unexpected results. Messages will be provided in most of these cases.
The required contamination (as percentage), as well as a plot
Maarten Blaauw
muck(600, 30, 2000, 0, 1, .01)muck(600, 30, 2000, 0, 1, .01)
Find the probability of a calibrated date being older than an age x.
Find the probability that a sample is older than a certain calendar age x, by calculating the proportion of the calibrated distribution 'after' x (i.e., 1 - the summed calibrated distribution up to year x).
older( x, y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, normal = TRUE, as.F = FALSE, t.a = 3, t.b = 4, BCAD = FALSE, threshold = 0 )older( x, y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, normal = TRUE, as.F = FALSE, t.a = 3, t.b = 4, BCAD = FALSE, threshold = 0 )
x |
The year of interest, in cal BP by default. |
y |
The radiocarbon date's mean. |
er |
The radiocarbon date's lab error. |
cc |
calibration curve for the radiocarbon date(s) (see the |
postbomb |
Whether or not to use a postbomb curve (see |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2016). |
as.F |
Whether or not to calculate ages in the F14C realm. Defaults to |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
BCAD |
Which calendar scale to use. Defaults to cal BP, |
threshold |
Report only values above a threshold. Defaults to |
The function can only deal with one date at a time.
The probability of a date being older than a certain calendar age.
Maarten Blaauw
older(2800, 2450, 20) older(2400, 2450, 20) calibrate(160, 20, BCAD=TRUE) older(1750, 160, 20, BCAD=TRUE)older(2800, 2450, 20) older(2400, 2450, 20) calibrate(160, 20, BCAD=TRUE) older(1750, 160, 20, BCAD=TRUE)
Calculates the amount of overlap (as percentage) between two or more calibrated radiocarbon dates. It does this by taking a sequence of calendar dates 'x' and for each calendar date find the calibrated distribution with the minimum height - this minimum height is taken as the overlap between the dates for that age. This is repeated for all 'x'. The sum of these heights is the overlap, which can reach values from 0 to 100%.
overlap( y, er, res = 1000, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, thiscurve = NULL, BCAD = FALSE, normal = TRUE, t.a = 3, t.b = 4, cc.dir = NULL, threshold = 0.001, age.lim = c(), age.lab = c(), calib.col = rgb(0, 0, 0, 0.2), overlap.col = rgb(0, 0, 1, 0.4), overlap.border = NA, overlap.height = 1, talk = TRUE, prob = 0.95, roundby = 1, bty = "n" )overlap( y, er, res = 1000, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, thiscurve = NULL, BCAD = FALSE, normal = TRUE, t.a = 3, t.b = 4, cc.dir = NULL, threshold = 0.001, age.lim = c(), age.lab = c(), calib.col = rgb(0, 0, 0, 0.2), overlap.col = rgb(0, 0, 1, 0.4), overlap.border = NA, overlap.height = 1, talk = TRUE, prob = 0.95, roundby = 1, bty = "n" )
y |
The set of radiocarbon dates |
er |
The lab errors of the radiocarbon dates |
res |
The resolution to base the calculations on. Defaults to 1000 steps between the minimum and maximum cal BP (these are calculated from the total calendar age range of all calibrated distributions). |
cc |
Calibration curve to use. Defaults to IntCal20 ( |
postbomb |
Whether or not to use a postbomb curve. Required for negative radiocarbon ages. |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
BCAD |
Which calendar scale to use. Defaults to cal BP, |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2016). |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
threshold |
Report only values above a threshold. Defaults to |
age.lim |
Calendar age limits of the calculations. Calculated automatically by default. |
age.lab |
Label of the calendar age, defaults to BCAD or cal BP. |
calib.col |
The colour of the individual calibrated ages. Defaults to semi-transparent grey. |
overlap.col |
The colour of the overlap distribution |
overlap.border |
The colour of the border of the overlap distribution |
overlap.height |
The height of the overlap distribution |
talk |
Whether or not to report a summary of the spread |
prob |
Probability range to report. Defaults to |
roundby |
Number of decimals to report |
bty |
Draw a box around a box of a certain shape. Defaults to |
The overlap between all calibrated probabilities as percentage, and a plot.
y <- c(3820, 4430) # the C14 ages of a twig and a marine shell from a single layer er <- c(40, 40) # their lab errors overlap(y, er, cc=1:2)y <- c(3820, 4430) # the C14 ages of a twig and a marine shell from a single layer er <- c(40, 40) # their lab errors overlap(y, er, cc=1:2)
Find the probability of a calibrated date lying within an age range
p.range( x1, x2, y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, normal = TRUE, as.F = FALSE, t.a = 3, t.b = 4, BCAD = FALSE, threshold = 0 )p.range( x1, x2, y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, normal = TRUE, as.F = FALSE, t.a = 3, t.b = 4, BCAD = FALSE, threshold = 0 )
x1 |
The start the range of interest. |
x2 |
The end of the range of interest. |
y |
The radiocarbon date's mean. |
er |
The radiocarbon date's lab error. |
cc |
calibration curve for the radiocarbon date(s) (see the |
postbomb |
Whether or not to use a postbomb curve (see |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2016). |
as.F |
Whether or not to calculate ages in the F14C realm. Defaults to |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
BCAD |
Which calendar scale to use. Defaults to cal BP, |
threshold |
Report only values above a threshold. Defaults to |
The function can only deal with one date at a time.
The probability of a date lying within a certain calendar age range.
Maarten Blaauw
p.range(2800, 2400, 2450, 20)p.range(2800, 2400, 2450, 20)
Will be deprecated. Use pMCtoC14 instead.
pMC.age(mn, sdev = c(), ratio = 100, decimals = 0, lambda = 8033)pMC.age(mn, sdev = c(), ratio = 100, decimals = 0, lambda = 8033)
mn |
Reported mean of the pMC. |
sdev |
Reported error of the pMC. |
ratio |
Most modern-date values are reported against |
decimals |
Amount of decimals required for the radiocarbon age. |
lambda |
The mean-life of radiocarbon (based on Libby half-life of 5568 years) |
Post-bomb dates are often reported as pMC or percent modern carbon. Since Bacon expects radiocarbon ages, this function can be used to calculate radiocarbon ages from pMC values. The reverse function is C14.pMC.
Radiocarbon ages from pMC values. If pMC values are above 100%, the resulting radiocarbon ages will be negative.
Calculate C14 ages from pMC values of radiocarbon dates.
pMCtoC14(pMC, er = NULL, decimals = 0, lambda = 8033)pMCtoC14(pMC, er = NULL, decimals = 0, lambda = 8033)
pMC |
Reported mean of the pMC. |
er |
Reported error of the pMC. |
decimals |
Amount of decimals required for the radiocarbon age. |
lambda |
The mean-life of radiocarbon (based on Libby half-life of 5568 years) |
Post-bomb dates are often reported as pMC or percent modern carbon. Since Bacon expects radiocarbon ages, this function can be used to calculate radiocarbon ages from pMC values. The reverse function is C14.pMC.
Radiocarbon ages from pMC values. If pMC values are above 100%, the resulting radiocarbon ages will be negative.
pMCtoC14(110, 0.5) # a postbomb date, so with a negative 14C age pMCtoC14(80, 0.5) # prebomb dates can also be calculated pMCtoC14(.8, 0.005) # throws a warning, use F14C.age insteadpMCtoC14(110, 0.5) # a postbomb date, so with a negative 14C age pMCtoC14(80, 0.5) # prebomb dates can also be calculated pMCtoC14(.8, 0.005) # throws a warning, use F14C.age instead
Transform F14C into D14C
pMCtoD14C(pMC, er = NULL, t)pMCtoD14C(pMC, er = NULL, t)
pMC |
The pMC value to translate |
er |
Reported error of the pMC value. Returns just the mean if left empty. |
t |
the cal BP age |
As explained by Heaton et al. 2020 (Radiocarbon), 14C measurements are commonly expressed in three domains: Delta14C, F14C and the radiocarbon age. This function translates F14C values into Delta14C, the historical level of Delta14C in the year t cal BP. Note that per convention, this function uses the Cambridge half-life, not the Libby half-life.
The corresponding D14C value
pMCtoD14C(0.985, .1, 222)pMCtoD14C(0.985, .1, 222)
Calculate pMC values from F14C values of radiocarbon dates.
pMCtoF14C(pMC, er = NULL)pMCtoF14C(pMC, er = NULL)
pMC |
Reported mean of the F14C |
er |
Reported error of the pMC value. Returns just the mean if left empty. |
Post-bomb dates are often reported as F14C (between 0 at c. 55 kcal BP and 1 at c. AD 1950). Since software such as Bacon expects radiocarbon ages, this function can be used to calculate radiocarbon ages from F14C values. The reverse function is age.F14C.
The F14C values from the pMC values. Basically the original values divided by 100.
pMCtoF14C(110, 5)pMCtoF14C(110, 5)
Calculate a point estimate of a calibrated distribution - either the weighted mean, the median or the mode (maximum). Note that point estimates often tend to be very poor representations of entire calibrated distributions, so please be careful and do not reduce entire calibrated distributions to just 1 point value.
point.estimates( calib, wmean = TRUE, median = TRUE, mode = TRUE, midpoint = TRUE, prob = 0.95, rounded = 1, every = 1 )point.estimates( calib, wmean = TRUE, median = TRUE, mode = TRUE, midpoint = TRUE, prob = 0.95, rounded = 1, every = 1 )
calib |
The calibrated distribution, as returned from caldist() |
wmean |
Report the weighted mean (defaults to TRUE) |
median |
Report the median (defaults to TRUE) |
mode |
Report the mode, which is the year with the maximum probability (defaults to TRUE) |
midpoint |
Report the midpoint of the hpd range(s) |
prob |
probability range for the hpd range(s) |
rounded |
Rounding for reported probabilities. Defaults to 1 decimal. |
every |
Yearly precision (defaults to |
The chosen point estimates
point.estimates(caldist(130,20)) plot(tmp <- caldist(2450,50), type='l') abline(v=point.estimates(tmp), col=1:4)point.estimates(caldist(130,20)) plot(tmp <- caldist(2450,50), type='l') abline(v=point.estimates(tmp), col=1:4)
Calculate the (chi-square) probability that a set of radiocarbon dates is consistent, i.e. that it can be assumed that they all pertain to the same true radiocarbon age (and thus to the same calendar age - note though that sometimes multiple calendar ages obtain the same C14 age). The function calculates the differences (chi2 value) and finds the corresponding p-value. If the chi2 values is sufficiently small, then the p-value is sufficiently large (above the threshold), and the pooled mean is calculated and returned. If the scatter is too large, no pooled mean is calculated.
pool(y, er, deltaR = 0, deltaSTD = 0, threshold = 0.05, roundby = 1)pool(y, er, deltaR = 0, deltaSTD = 0, threshold = 0.05, roundby = 1)
y |
The set of radiocarbon dates to be tested |
er |
The lab errors of the radiocarbon dates |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
threshold |
Probability threshold above which chisquare values are considered acceptable (between 0 and 1; default |
roundby |
Rounding of the reported mean, chisquare and and p-value. Defaults to |
This follows the calculations of Ward and Wilson (1978; Archaeometry 20: 19-31 <doi:10.1111/j.1475-4754.1978.tb00208.x>) and should only be used for multiple dates that stem from the same sample (e.g., multiple measurements on a single bone). It cannot be used to test if multiple dates from multiple samples pertain to the same event. Since the assumption is that all measurements stem from the same event, we can assume that they all share the same C14 age (since any calBP age will have an associated IntCal C14 age).
The pooled mean and error if the p-value is above the threshold - a warning if it is not.
Maarten Blaauw
data(shroud) pool(shroud$y,shroud$er) Zu <- grep("ETH", shroud$ID) # Zurich lab only pool(shroud$y[Zu],shroud$er[Zu])data(shroud) pool(shroud$y,shroud$er) Zu <- grep("ETH", shroud$ID) # Zurich lab only pool(shroud$y[Zu],shroud$er[Zu])
Push a date to younger or older ages by adding (or subtracting) a gamma distribution (e.g. if a bone is assumed to have a lag or in-built age)
push.gamma( y, er, mean, shape, add = TRUE, n = 1e+06, prob = 0.95, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, thiscurve = NULL, cc.dir = NULL, normal = TRUE, t.a = 3, t.b = 4, BCAD = FALSE, cal.lim = c(), calib.col = rgb(0, 0, 0, 0.25), pushed.col = rgb(0, 0, 1, 0.4), inset = TRUE, inset.col = "darkgreen", inset.loc = c(0.6, 0.97, 0.6, 0.97), inset.mar = c(3, 0.5, 0.5, 0.5), inset.mgp = c(2, 1, 0) )push.gamma( y, er, mean, shape, add = TRUE, n = 1e+06, prob = 0.95, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, thiscurve = NULL, cc.dir = NULL, normal = TRUE, t.a = 3, t.b = 4, BCAD = FALSE, cal.lim = c(), calib.col = rgb(0, 0, 0, 0.25), pushed.col = rgb(0, 0, 1, 0.4), inset = TRUE, inset.col = "darkgreen", inset.loc = c(0.6, 0.97, 0.6, 0.97), inset.mar = c(3, 0.5, 0.5, 0.5), inset.mgp = c(2, 1, 0) )
y |
The radiocarbon age |
er |
The error of the radiocarbon age |
mean |
The mean of the gamma distribution |
shape |
The shape of the gamma distribution. If setting this to shape=1, it becomes an exponential distribution. |
add |
The distribution can be added or subtracted. Adding results in ages being pushed to younger age distributions, and subtracting to older ones. |
n |
The amount of random values to sample (from both the calibrated distribution and the gamma distribution) to calculate the push. Defaults to |
prob |
The probability for the hpd ranges. Defaults to |
cc |
Calibration curve to use. Defaults to IntCal20 ( |
postbomb |
Whether or not to use a postbomb curve. Required for negative radiocarbon ages. Defaults to |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2016). |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
BCAD |
Which calendar scale to use. Defaults to cal BP, |
cal.lim |
Calendar axis limits. Calculated automatically by default. |
calib.col |
Colour of the calibrated distribution (defaults to semi-transparent light grey). |
pushed.col |
Colour of the pushed distribution (defaults to semi-transparent blue). |
inset |
Whether or not to plot an inset graph showing the shape of the normal/gamma distribution. |
inset.col |
Colour of the normal/gamma distribution. |
inset.loc |
Location of the inset graph. |
inset.mar |
Margins of the inset graph. |
inset.mgp |
Margin lines for the inset graph. |
n random values will be sampled from the calibrated distribution, and a similar amount will be sampled from the gamma distribution. The sampled values will then be added to or subtracted from each other to push the date to younger or older ages.
The resulting calibrated distribution and its hpd ranges, together with a plot of the pushed date with the gamma distribution (and whether it is added or subtracted) as inset
push.gamma(250, 25, 50, 2, add=FALSE) # subtract a gamma distributionpush.gamma(250, 25, 50, 2, add=FALSE) # subtract a gamma distribution
Push a date to younger or older ages by adding (or subtracting) a normal distribution (e.g. if a bone is assumed to have a lag or in-built age)
push.normal( y, er, mean, sdev, add = TRUE, n = 1e+06, prob = 0.95, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, thiscurve = NULL, cc.dir = NULL, normal = TRUE, t.a = 3, t.b = 4, BCAD = FALSE, cal.lim = c(), calib.col = rgb(0, 0, 0, 0.25), pushed.col = rgb(0, 0, 1, 0.4), inset = TRUE, inset.col = "darkgreen", inset.loc = c(0.6, 0.97, 0.6, 0.97), inset.mar = c(3, 0.5, 0.5, 0.5), inset.mgp = c(2, 1, 0) )push.normal( y, er, mean, sdev, add = TRUE, n = 1e+06, prob = 0.95, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, thiscurve = NULL, cc.dir = NULL, normal = TRUE, t.a = 3, t.b = 4, BCAD = FALSE, cal.lim = c(), calib.col = rgb(0, 0, 0, 0.25), pushed.col = rgb(0, 0, 1, 0.4), inset = TRUE, inset.col = "darkgreen", inset.loc = c(0.6, 0.97, 0.6, 0.97), inset.mar = c(3, 0.5, 0.5, 0.5), inset.mgp = c(2, 1, 0) )
y |
The radiocarbon age. |
er |
The error of the radiocarbon age. |
mean |
The mean of the normal or gamma distribution. |
sdev |
The standard deviation of the normal distribution. |
add |
The distribution can be added or subtracted. Adding results in ages being pushed to younger age distributions, and subtracting to older ones. |
n |
The amount of random values to sample (from both the calibrated distribution and the gamma/normal distribution) to calculate the push. Defaults to |
prob |
The probability for the hpd ranges. Defaults to |
cc |
Calibration curve to use. Defaults to IntCal20 ( |
postbomb |
Whether or not to use a postbomb curve. Required for negative radiocarbon ages. Defaults to |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2016). |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
BCAD |
Which calendar scale to use. Defaults to cal BP, |
cal.lim |
Calendar axis limits. Calculated automatically by default. |
calib.col |
Colour of the calibrated distribution (defaults to semi-transparent light grey). |
pushed.col |
Colour of the pushed distribution (defaults to semi-transparent blue). |
inset |
Whether or not to plot an inset graph showing the shape of the normal/gamma distribution. |
inset.col |
Colour of the normal/gamma distribution. |
inset.loc |
Location of the inset graph. |
inset.mar |
Margins of the inset graph. |
inset.mgp |
Margin lines for the inset graph. |
n random values will be sampled from the calibrated distribution, and a similar amount will be sampled from the normal distribution. The sampled values will then be added to or subtracted from each other to push the date to younger or older ages.
The resulting calibrated distribution and its hpd ranges, together with a plot of the pushed date with the normal distribution (and whether it is added or subtracted) as inset
push.normal(250, 25, 50, 10)push.normal(250, 25, 50, 10)
Calculate the cumulative calibrated distribution, then sample n random uniform values between 0 and 1 and find the corresponding calendar ages through interpolation. Calendar ages with higher calibrated probabilities will be proportionally more likely to be sampled.
r.calib( n, y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, as.F = FALSE, thiscurve = NULL, yrsteps = FALSE, cc.resample = FALSE, dist.res = 200, threshold = 0, normal = TRUE, t.a = 3, t.b = 4, normalise = TRUE, BCAD = FALSE, rule = 2, cc.dir = NULL )r.calib( n, y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, as.F = FALSE, thiscurve = NULL, yrsteps = FALSE, cc.resample = FALSE, dist.res = 200, threshold = 0, normal = TRUE, t.a = 3, t.b = 4, normalise = TRUE, BCAD = FALSE, rule = 2, cc.dir = NULL )
n |
The number of calendar ages to sample |
y |
Uncalibrated radiocarbon age |
er |
Lab error of the radiocarbon age |
cc |
Calibration curve to use. Defaults to IntCal20 ( |
postbomb |
Whether or not to use a postbomb curve. Required for negative radiocarbon ages. |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
as.F |
Whether or not to calculate ages in the F14C realm. Defaults to |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
yrsteps |
Steps to use for interpolation. Defaults to the cal BP steps in the calibration curve |
cc.resample |
The IntCal20 curves have different densities (every year between 0 and 5 kcal BP, then every 5 yr up to 15 kcal BP, then every 10 yr up to 25 kcal BP, and then every 20 yr up to 55 kcal BP). If calibrated ages span these density ranges, their drawn heights can differ, as can their total areas (which should ideally all sum to the same size). To account for this, resample to a constant time-span, using, e.g., |
dist.res |
As an alternative to yrsteps, provide the amount of 'bins' in the distribution |
threshold |
Report only values above a threshold. Defaults to |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2016). |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
normalise |
Sum the entire calibrated distribution to 1. Defaults to |
BCAD |
Which calendar scale to use. Defaults to cal BP, |
rule |
Which extrapolation rule to use. Defaults to |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
n randomly sampled calendar ages
Maarten Blaauw
r.calib(10,130,20) # 10 random cal BP ages plot(density(r.calib(1e6, 2450, 20)))r.calib(10,130,20) # 10 random cal BP ages plot(density(r.calib(1e6, 2450, 20)))
A dataset containing the deltaR values and accompanying data from the marine database
shellsshells
A data frame with 1968 rows and 15 variables.
Longitude of the datapoint
Latitude of the datapoint
Map or ID number of the datapoint
Taxon number of the datapoint
calculated deltaR of the datapoint
uncertainty of the deltaR of the datapoint
Collection year for the datapoint
Reservoir effect of the datapoint
Uncertainty of the reservoir effect of the datapoint
Radiocarbon age of the datapoint
Error of the radiocarbon age of the datapoint
Lab code of the datapoint
Reference for the datapoint
Taxon of the datapoint
Feeding ecology of the datapoint (if known)
Data downloaded from calib.org/marine
data(shells) head(shells)data(shells) head(shells)
After selecting a relevant range of shell values, plot them and calculate the weighted mean and variance.
shells.mean( dat, feeding = c(), draw = TRUE, distance = FALSE, pch = 20, col.mn = 1, lty.mn = 2, col.sd = rgb(0, 0, 0, 0.1) )shells.mean( dat, feeding = c(), draw = TRUE, distance = FALSE, pch = 20, col.mn = 1, lty.mn = 2, col.sd = rgb(0, 0, 0, 0.1) )
dat |
The data, as returned from the function 'plot.shells'. |
feeding |
Whether or not to select a specific feeding behaviour. Defaults to empty (no selection of feeding behaviour). |
draw |
Whether or not to draw the values. |
distance |
Plot the dR values according to their distance (if you've used find.shells; assumes that 'dat' has a final column with the distances). |
pch |
Symbol to be plotted. Defaults to a closed circle ( |
col.mn |
Colour for the weighted mean. Defaults to black, |
lty.mn |
Line type for the weighted mean. Defaults to dashed, |
col.sd |
Colour of the rectangle of the error. Defaults to transparent grey, |
A plot of the dR values, as well as the weighted mean (vertical line) and (weighted) error (rectangle).
N_UK <- map.shells(53, -11, 60, 2, mapsize="medium") shells.mean(N_UK) nearby <- find.shells(0,56,20) # somewhere in Scotland shells.mean(nearby, distance=TRUE) # distance mattersN_UK <- map.shells(53, -11, 60, 2, mapsize="medium") shells.mean(N_UK) nearby <- find.shells(0,56,20) # somewhere in Scotland shells.mean(nearby, distance=TRUE) # distance matters
A dataset containing the radiocarbon dates on the Shroud of Turin, from three labs
shroudshroud
A data frame with 1968 rows and 15 variables.
Lab numbers. Replicates are indicates with .1, .2, etc.
Radiocarbon year
Lab error
Data taken from Damon et al. 1989 [Nature] <doi:10.1038/337611a0>, see also Christen 1994 [Applied Statistics] <doi:10.2307/2986273>
data(shroud) head(shroud)data(shroud) head(shroud)
Smooth a calibration curve over a time window of a specified width. This to accommodate material that has accumulated over a certain assumed time, e.g. a cm of peat over say 30 years.
smooth.ccurve( smooth = 30, cc = 1, postbomb = FALSE, cc.dir = c(), thiscurve = c(), resample = 0, name = "smoothed.csv", save = FALSE, sep = "\t" )smooth.ccurve( smooth = 30, cc = 1, postbomb = FALSE, cc.dir = c(), thiscurve = c(), resample = 0, name = "smoothed.csv", save = FALSE, sep = "\t" )
smooth |
The window width of the smoothing. Defaults to |
cc |
The calibration curve to smooth. Calibration curve for 14C dates: 'cc=1' for IntCal20 (northern hemisphere terrestrial), 'cc=2' for Marine20 (marine), 'cc=3' for SHCal20 (southern hemisphere terrestrial). Alternatively, one can also write, e.g., "IntCal20", "Marine13". One can also make a custom-built calibration curve, e.g. using 'mix.ccurves()', and load this using 'cc=4'. In this case, it is recommended to place the custom calibration curve in its own directory, using 'cc.dir' (see below). |
postbomb |
Use 'postbomb=TRUE' to get a postbomb calibration curve (default 'postbomb=FALSE'). For monthly data, type e.g. 'ccurve("sh1-2_monthly")' |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., 'cc.dir="ccurves"'. |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). Defaults to c(). |
resample |
The IntCal curves come at a range of 'bin sizes'; every year from 0 to 5 kcal BP, then every 5 yr until 15 kcal BP, then every 10 yr until 25 kcal BP, and every 20 year thereafter. The curves can be resampled to constant bin sizes, e.g. 'resample=5'. Defaults to FALSE. |
name |
The filename of the curve, if it is being saved. Defaults to |
save |
Whether or not to save the curve to cc.dir. Defaults to |
sep |
Separator between fields if the file is saved (tab by default, |
The smoothing is done by calculating the mean C14 age and error of a moving window (moving along with the cal BP steps of the calibration curve). Something similar is done in the online calibration software CALIB.
Maarten Blaauw
mycurve <- smooth.ccurve(smooth=50) calibrate(2450,20, thiscurve=mycurve)mycurve <- smooth.ccurve(smooth=50) calibrate(2450,20, thiscurve=mycurve)
Calculates the spread among multiple calibrated radiocarbon dates. It does this by randomly sampling ages from the calibrated dates, and calculate the difference between one random date and all others for that iteration.
spread( y, er, n = 1e+05, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, as.F = FALSE, thiscurve = NULL, yrsteps = 1, cc.resample = FALSE, threshold = 0.001, normal = TRUE, t.a = 3, t.b = 4, cc.dir = NULL, visualise = TRUE, talk = TRUE, prob = 0.95, roundby = 1, bty = "l" )spread( y, er, n = 1e+05, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, as.F = FALSE, thiscurve = NULL, yrsteps = 1, cc.resample = FALSE, threshold = 0.001, normal = TRUE, t.a = 3, t.b = 4, cc.dir = NULL, visualise = TRUE, talk = TRUE, prob = 0.95, roundby = 1, bty = "l" )
y |
The set of radiocarbon dates |
er |
The lab errors of the radiocarbon dates |
n |
The number of iterations to base the calculations on. Defaults to 100,000. |
cc |
Calibration curve to use. Defaults to IntCal20 ( |
postbomb |
Whether or not to use a postbomb curve. Required for negative radiocarbon ages. |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
as.F |
Whether or not to calculate ages in the F14C realm. Defaults to |
thiscurve |
As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). |
yrsteps |
Steps to use for interpolation. Defaults to the cal BP steps in the calibration curve |
cc.resample |
The IntCal20 curves have different densities (every year between 0 and 5 kcal BP, then every 5 yr up to 15 kcal BP, then every 10 yr up to 25 kcal BP, and then every 20 yr up to 55 kcal BP). If calibrated ages span these density ranges, their drawn heights can differ, as can their total areas (which should ideally all sum to the same size). To account for this, resample to a constant time-span, using, e.g., cc.resample=5 for 5-yr timespans. |
threshold |
Report only values above a threshold. Defaults to |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2016). |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
cc.dir |
Directory of the calibration curves. Defaults to where the package's files are stored (system.file), but can be set to, e.g., |
visualise |
Whether or not to plot the spread |
talk |
Whether or not to report a summary of the spread |
prob |
Probability range to report. Defaults to |
roundby |
Number of decimals to report |
bty |
Draw a box around a box of a certain shape. Defaults to |
The spread of all calibrated probabilities.
data(shroud) spread(shroud$y,shroud$er) Zu <- grep("ETH", shroud$ID) # Zurich lab only spread(shroud$y[Zu],shroud$er[Zu])data(shroud) spread(shroud$y,shroud$er) Zu <- grep("ETH", shroud$ID) # Zurich lab only spread(shroud$y[Zu],shroud$er[Zu])
Calculating the weighted mean of multiple C14 ages, using their means and lab errors.
weighted_means(y, er, round = 1, talk = TRUE)weighted_means(y, er, round = 1, talk = TRUE)
y |
The C14 ages. |
er |
The lab errors of the C14 ages. |
round |
Rounding to be applied (defaults to 1 decimal). |
talk |
Report details of the found values. |
The weighted mean and error (the latter is the maximum of the weighted error and the square root of the variance).
N_UK <- map.shells(53, -11, 60, 2, mapsize="medium") weighted_means(N_UK$dR, N_UK$dSTD)N_UK <- map.shells(53, -11, 60, 2, mapsize="medium") weighted_means(N_UK$dR, N_UK$dSTD)
Find the probability that a sample is of a certain calendar age x or younger than it, by calculating the proportion of the calibrated distribution up to and including x (i.e., summing the calibrated distribution up to year x).
younger( x, y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, normal = TRUE, as.F = FALSE, t.a = 3, t.b = 4, BCAD = FALSE, threshold = 0 )younger( x, y, er, cc = 1, postbomb = FALSE, deltaR = 0, deltaSTD = 0, normal = TRUE, as.F = FALSE, t.a = 3, t.b = 4, BCAD = FALSE, threshold = 0 )
x |
The year of interest, in cal BP by default. |
y |
The radiocarbon date's mean. |
er |
The radiocarbon date's lab error. |
cc |
calibration curve for the radiocarbon date(s) (see the |
postbomb |
Whether or not to use a postbomb curve (see |
deltaR |
Age offset (e.g. for marine samples). |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). |
normal |
Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2016). |
as.F |
Whether or not to calculate ages in the F14C realm. Defaults to |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
BCAD |
Which calendar scale to use. Defaults to cal BP, |
threshold |
Report only values above a threshold. Defaults to |
The function can only deal with one date at a time.
The probability of a date being of a certain calendar age or younger than it.
Maarten Blaauw
younger(2800, 2450, 20) younger(2400, 2450, 20) calibrate(160, 20, BCAD=TRUE) younger(1750, 160, 20, BCAD=TRUE)younger(2800, 2450, 20) younger(2400, 2450, 20) calibrate(160, 20, BCAD=TRUE) younger(1750, 160, 20, BCAD=TRUE)