| Type: | Package |
| Title: | Radiocarbon Equations |
| Version: | 1.2.0 |
| Author: | Maarten Blaauw 
[aut, cre] |
| Maintainer: | Maarten Blaauw <maarten.blaauw@qub.ac.uk> |
| 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 uses the calibration curves from the data package 'rintcal'. |
| License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| Imports: | rlang, ggplot2, maps (≥ 3.4.2.1) |
| Suggests: | knitr, rmarkdown, utf8, remotes, devtools, sf, rnaturalearthdata, rnaturalearth (≥ 1.0.1), leaflet, htmltools, CopernicusMarine, testthat (≥ 3.0.0) |
| Depends: | R (≥ 3.5.0), rintcal (≥ 1.2.1) |
| Language: | en-GB |
| VignetteBuilder: | knitr |
| NeedsCompilation: | no |
| LazyData: | true |
| Config/testthat/edition: | 3 |
| Packaged: | 2025-06-13 09:40:08 UTC; maarten |
| Repository: | CRAN |
| Date/Publication: | 2025-06-13 10:10:02 UTC |
rice: 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 uses the calibration curves from the data package 'rintcal'.
Author(s)
Maintainer: Maarten Blaauw maarten.blaauw@qub.ac.uk (ORCID)
Find the 14C age and error belonging to a BC/AD age.
Description
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.
Usage
BCADtoC14(
x,
cc = 1,
postbomb = FALSE,
zero = TRUE,
rule = 1,
cc.dir = NULL,
thiscurve = NULL
)
Arguments
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 zero BC/AD should be included. Defaults to |
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). |
Details
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.
Value
The calibration-curve 14C year belonging to the entered BC/AD age
Author(s)
Maarten Blaauw
Examples
BCADtoC14(100)
Find the pMC and error belonging to a cal BP age.
Description
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding F14C value and error are returned.
Usage
BCADtoD14C(
x,
zero = TRUE,
cc = 1,
postbomb = FALSE,
rule = 1,
cc.dir = NULL,
thiscurve = NULL,
decimals = 8
)
Arguments
x |
The cal BP year. |
zero |
Whether or not zero BC/AD should be included. Defaults to |
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). |
decimals |
Amount of decimals required for the F14C value. Defaults to 8. |
Details
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.
Value
The calibration-curve 14C year belonging to the entered cal BP age
Author(s)
Maarten Blaauw
Examples
BCADtoD14C(1900)
Find the F14C and error belonging to a BC/AD age.
Description
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding F14C and error are returned. BC ages are negative.
Usage
BCADtoF14C(
x,
cc = 1,
postbomb = FALSE,
zero = TRUE,
rule = 1,
cc.dir = NULL,
thiscurve = NULL,
decimals = 8
)
Arguments
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 zero BC/AD should be included. Defaults to |
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). |
decimals |
Amount of decimals required for the F14C value. Defaults to 8. |
Details
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.
Value
The calibration-curve F14C belonging to the entered BC/AD age
Author(s)
Maarten Blaauw
Examples
BCADtoF14C(100)
calculate b2k from BC/AD ages
Description
calculate b2k from BC/AD ages
Usage
BCADtob2k(x, zero = TRUE)
Arguments
x |
The BCAD age(s) to be translated into b2k age(s). BC ages are negative, AD ages are positive. |
zero |
Whether or not zero BC/AD should be included. Defaults to |
Details
Turn BC/AD (or BCE/CE) ages into b2k ages. b2k ages are used frequently in the ice core community. 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 (i.e., 1 BC) to 1 AD. Other calendars, such as the astronomical one, do include zero. The often-used BCE/CE ages are equivalent to BC/AD.
Value
The b2k age(s).
Examples
BCADtob2k(2025)
BCADtob2k(-1, zero=TRUE)
BCADtob2k(-1, zero=FALSE)
calculate cal BP ages from BC/AD ages
Description
calculate cal BP ages from BC/AD ages
Usage
BCADtocalBP(x, zero = TRUE)
Arguments
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 |
Details
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 (i.e., 1 BC) to 1 AD. Other calendars, such as the astronomical one, do include zero. The often-used BCE/CE ages are equivalent to BC/AD.
Value
The cal BP age(s).
Examples
BCADtocalBP(2024)
BCADtocalBP(-1, zero=TRUE)
BCADtocalBP(-1, zero=FALSE)
Find the pMC and error belonging to a BC/AD age.
Description
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding pMC and error are returned. BC ages are negative.
Usage
BCADtopMC(
x,
cc = 1,
postbomb = FALSE,
zero = TRUE,
rule = 1,
cc.dir = NULL,
thiscurve = NULL,
decimals = 8
)
Arguments
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 zero BC/AD should be included. Defaults to |
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). |
decimals |
Amount of decimals required for the F14C value. Defaults to 8. |
Details
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.
Value
The calibration-curve F14C belonging to the entered BC/AD age
Author(s)
Maarten Blaauw
Examples
BCADtopMC(100)
Find the BCAD age(s) crossing a C14 age.
Description
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.
Usage
C14toBCAD(
y,
cc = 1,
postbomb = FALSE,
rule = 1,
zero = TRUE,
cc.dir = NULL,
thiscurve = NULL
)
Arguments
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). |
Details
. 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.
Value
The BCAD age(s) belonging to the entered C14 age
Author(s)
Maarten Blaauw
Examples
y <- 130
calibrate(y,10, BCAD=TRUE)
abline(h=y)
abline(v=C14toBCAD(y))
Transform C14 age(s) into D14C
Description
Transform C14 age(s) into D14C
Usage
C14toD14C(y, er = NULL, t, decimals = 8)
Arguments
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 |
decimals |
Amount of decimals required for the F14C value. Defaults to 8. |
Details
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.
Value
The corresponding D14C value
Examples
C14toD14C(0.985, 20, 222)
Calculate F14C values from C14 ages
Description
Calculate F14C values from radiocarbon ages
Usage
C14toF14C(y, er = NULL, decimals = 8, lambda = 8033)
Arguments
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 8. |
lambda |
The mean-life of radiocarbon (based on Libby half-life of 5568 years). |
Details
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.
Value
F14C values from C14 ages.
Examples
C14toF14C(-2000, 20)
Find the b2k age(s) crossing a C14 age.
Description
Find the b2k ages (years before AD 2000, popular in the ice core community) 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.
Usage
C14tob2k(
y,
cc = 1,
postbomb = FALSE,
rule = 1,
cc.dir = NULL,
thiscurve = NULL
)
Arguments
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). |
Details
. Whereas each calendar 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.
Value
The b2k age(s) belonging to the entered C14 age
Author(s)
Maarten Blaauw
Examples
C14tob2k(130,20)
Find the calBP age(s) crossing a C14 age.
Description
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.
Usage
C14tocalBP(
y,
cc = 1,
postbomb = FALSE,
rule = 2,
cc.dir = NULL,
thiscurve = NULL
)
Arguments
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). |
Details
. 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.
Value
The cal BP age(s) belonging to the entered C14 age
Author(s)
Maarten Blaauw
Examples
y <- 130
calibrate(y,10)
abline(h=y)
abline(v=C14tocalBP(y))
Calculate pMC values from C14 ages
Description
Calculate pMC values from radiocarbon ages
Usage
C14topMC(y, er = NULL, decimals = 8, lambda = 8033)
Arguments
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 8. |
lambda |
The mean-life of radiocarbon (based on Libby half-life of 5568 years) |
Details
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.
Value
pMC values from C14 ages.
Examples
C14topMC(-2000, 20)
C14topMC(-2000, 20, 1)
Transform D14C into C14 age
Description
Transform D14C into C14 age
Usage
D14CtoC14(D14C, er = NULL, t, decimals = 8)
Arguments
D14C |
The Delta14C value to translate |
er |
Reported error of the D14C. Returns just the mean if left empty. |
t |
the cal BP age |
decimals |
Amount of decimals required for the F14C value. Defaults to 8. |
Details
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.
Value
The corresponding C14 age
Examples
D14CtoC14(-10, 1, 238)
Transform D14C into F14C
Description
Transform D14C into F14C
Usage
D14CtoF14C(D14C, er = NULL, t)
Arguments
D14C |
The Delta14C value to translate |
er |
Reported error of the D14C. Returns just the mean if left empty. |
t |
the cal BP age |
Details
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.
Value
The corresponding F14C value
Examples
D14CtoF14C(-10, 1, 238)
Transform D14C into pMC
Description
Transform D14C into pMC
Usage
D14CtopMC(D14C, er = NULL, t)
Arguments
D14C |
The Delta14C value to translate |
er |
Reported error of the D14C. Returns just the mean if left empty. |
t |
the cal BP age |
Details
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.
Value
The corresponding F14C value
Examples
D14CtoF14C(-10, 1, 238)
To be deprecated. Calculate C14 ages from F14C values.
Description
Calculate C14 ages from F14C values of radiocarbon dates.
Usage
F14C.age(mn, sdev = c(), decimals = 5, lambda = 8033)
Arguments
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) |
Details
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.
Value
Radiocarbon ages from F14C values. If F14C values are above 100%, the resulting radiocarbon ages will be negative.
Calculate C14 ages from F14C values.
Description
Calculate C14 ages from F14C values of radiocarbon dates.
Usage
F14CtoC14(F14C, er = NULL, decimals = 8, lambda = 8033)
Arguments
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 8. |
lambda |
The mean-life of radiocarbon (based on Libby half-life of 5568 years) |
Details
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.
Value
The radiocarbon ages from the F14C values. If F14C values are above 100%, the resulting radiocarbon ages will be negative.
Examples
F14CtoC14(1.10, 0.005) # a postbomb date, so with a negative C14 age
F14CtoC14(.80, 0.005) # prebomb dates can also be calculated
Transform F14C into D14C
Description
Transform F14C into D14C
Usage
F14CtoD14C(F14C, er = NULL, t)
Arguments
F14C |
The F14C value to translate |
er |
Reported error of the F14C. Returns just the mean if left empty. |
t |
the cal BP age |
Details
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.
Value
The corresponding D14C value
Examples
F14CtoD14C(0.89, .001, 900)
Calculate pMC ages from F14C values.
Description
Calculate pMC values from F14C values of radiocarbon dates.
Usage
F14CtopMC(F14C, er = NULL)
Arguments
F14C |
Reported mean of the F14C |
er |
Reported error of the F14C. Returns just the mean if left empty. |
Details
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.
Value
The pMC values from the F14C values. Basically the original values multiplied by 100.
Examples
F14CtopMC(1.10, 0.5)
Adjust a radiocarbon age for background measurements
Description
Calculate the radiocarbon age by adjusting it for a measured background. It is planned to update this function to more properly reflect calculations in the 14CHRONO lab.
Usage
adjust.background(y, er, bg, bg.er, realm = "C14")
Arguments
y |
The age of the sample (in C14 by default, but can also be in F or pMC). |
er |
The error of the date. |
bg |
The background measurement. Should be in the same realm as that of the sample. |
bg.er |
The error of the background measurement. Should be in the same realm as that of the sample. |
realm |
Type of radiocarbon age. Can be in 'C14' (default), 'F14C' or 'pMC'. |
Details
Radiocarbon ages are measured using a series of standards and backgrounds, and the raw values are then corrected for these background values. Backgrounds are >0 (in F14C) owing to contamination in even the cleanest lab.
Value
The background-adjusted age.
Author(s)
Maarten Blaauw
Examples
adjust.background(9000, 50, 45000, 200)
Adjust a radiocarbon age for fractionation
Description
Calculate the radiocarbon age by adjusting a sample's d13C to the reference d13C of -25 permil. It is planned to update this function to more properly reflect calculations in the 14CHRONO lab.
Usage
adjust.fractionation(y, d13C, reference_d13C = -25, realm = "C14")
Arguments
y |
The age of the sample (in C14 by default, but can also be in F or pMC). |
d13C |
The measured d13C value. |
reference_d13C |
The reference/standard d13C value (OX2, oxalic acid 2, NIST SRM 4990C made from 1977 French beet molasses), set at -25 permil by default. |
realm |
Type of radiocarbon age. Can be in 'C14' (default), 'F14C' or 'pMC'. |
Details
Radiocarbon ages are corrected for fractionation (which can take place in the field, or during lab pretreatment and measurement), by calculating the radiocarbon age as if the d13C fractionation were at the d13C of the standard (-25 permil). Errors are not taken into account.
Value
The fractionation-adjusted age.
Author(s)
Maarten Blaauw
Examples
adjust.fractionation(5000, -17)
To be deprecated. Use C14.F14C instead
Description
Calculate F14C values from radiocarbon ages
Usage
age.F14C(mn, sdev = c(), decimals = 5, lambda = 8033)
Arguments
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) |
Details
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.
Value
F14C values from C14 ages.
To be deprecated. Use C14topMC instead.
Description
Calculate pMC values from radiocarbon ages
Usage
age.pMC(mn, sdev = c(), ratio = 100, decimals = 5, lambda = 8033)
Arguments
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) |
Details
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.
Value
pMC values from C14 ages.
Combine multiple radiocarbon dates within bins
Description
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.
Usage
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 = 0.3,
talk = TRUE,
prob = 0.95,
roundby = 0,
bty = "n"
)
Arguments
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 |
Details
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.
Value
The number of dates that fall within the moving bins, for each bin.
Author(s)
Maarten Blaauw
Examples
data(shroud)
shroudbin <- as.bin(shroud$y, shroud$er, 50, 10)
# bins of 50 yr, moving by 10 yr, slow
Combine multiple radiocarbon dates assuming they belong to the same single year
Description
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.
Usage
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 = 0.3,
prob = 0.95,
talk = TRUE,
roundby = 0,
bty = "n"
)
Arguments
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 |
Details
This calculates the product of all calibrated probabilities, over the range of calendar ages to which the radiocarbon ages calibrate.
Value
The product of all calibrated probabilities over the range of cal BP years.
Author(s)
Maarten Blaauw
Examples
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)
calculate BC/AD ages from b2k ages
Description
calculate BC/AD ages from b2k ages
Usage
b2ktoBCAD(x, zero = TRUE)
Arguments
x |
The b2k age(s) to be translated into BC/AD ages. |
zero |
Whether or not zero BC/AD should be included. Defaults to |
Details
Turn b2k ages (popular in the ice core community) 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 (i.e., 1 BC) to 1 AD. Other calendars, such as the astronomical one, do include zero. The often-used BCE/CE ages are equivalent to BC/AD.
Value
The BC/AD age(s). BC ages are negative, AD ages are positive.
Examples
b2ktoBCAD(0)
b2ktoBCAD(1990:2010, zero=TRUE)
b2ktoBCAD(1990:2010, zero=FALSE)
Find the 14C age and error belonging to a b2k age.
Description
Given a b2k age (years before AD 2000, popular in the ice core community), the calibration curve (default cc=1) is interpolated and the corresponding 14C age and error are returned.
Usage
b2ktoC14(
x,
cc = 1,
postbomb = FALSE,
rule = 1,
cc.dir = NULL,
thiscurve = NULL
)
Arguments
x |
The b2k 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). |
Details
Interpolation is used, and values outside the calibration curve are given as NA. For ages younger than 50 b2k, a postbomb curve will have to be provided.
Value
The calibration-curve 14C year belonging to the entered b2k age
Author(s)
Maarten Blaauw
Examples
b2ktoC14(100)
Find the pMC and error belonging to a b2k age.
Description
Given a b2k age (years before AD 2000, popular in the ice core community), the calibration curve (default cc=1) is interpolated and the corresponding F14C value and error are returned.
Usage
b2ktoD14C(
x,
cc = 1,
postbomb = FALSE,
rule = 1,
cc.dir = NULL,
thiscurve = NULL,
decimals = 8
)
Arguments
x |
The b2k 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). |
decimals |
Amount of decimals required for the F14C value. Defaults to 8. |
Details
Interpolation is used, and values outside the calibration curve are given as NA. For b2k < 50, a postbomb curve will have to be provided.
Value
The calibration-curve 14C year belonging to the entered b2k age
Author(s)
Maarten Blaauw
Examples
b2ktoD14C(100)
Find the F14C and error belonging to a b2k age.
Description
Given a b2k age (years before AD 2000, popular in the ice core community), the calibration curve (default cc=1) is interpolated and the corresponding F14C and error are returned.
Usage
b2ktoF14C(
x,
cc = 1,
postbomb = FALSE,
rule = 1,
cc.dir = NULL,
thiscurve = NULL,
decimals = 8
)
Arguments
x |
The b2k 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). |
decimals |
Amount of decimals required for the F14C value. Defaults to 8. |
Details
Interpolation is used, and values outside the calibration curve are given as NA. For ages younger than 50 b2k, a postbomb curve will have to be provided.
Value
The calibration-curve F14C belonging to the entered b2k age
Author(s)
Maarten Blaauw
Examples
b2ktoF14C(100)
calculate cal BP ages from b2k ages
Description
calculate cal BP ages from b2k ages
Usage
b2ktocalBP(x)
Arguments
x |
The b2k age(s) to be translated into cal BP age(s). |
Details
Turn b2k ages (often used in the ice core community, AD 2000) into cal BP ages.
Value
The cal BP age(s).
Examples
b2ktocalBP(0)
Find the pMC and error belonging to a b2k age.
Description
Given a b2k age (years before AD 2000, popular in the ice core community), the calibration curve (default cc=1) is interpolated and the corresponding pMC and error are returned.
Usage
b2ktopMC(
x,
cc = 1,
postbomb = FALSE,
rule = 1,
cc.dir = NULL,
thiscurve = NULL,
decimals = 8
)
Arguments
x |
The b2k 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). |
decimals |
Amount of decimals required for the F14C value. Defaults to 8. |
Details
Interpolation is used, and values outside the calibration curve are given as NA. For ages younger than 50 b2k, a postbomb curve will have to be provided.
Value
The calibration-curve F14C belonging to the entered b2k age
Author(s)
Maarten Blaauw
Examples
b2ktopMC(100)
calculate BC/AD ages from cal BP ages
Description
calculate BC/AD ages from cal BP ages
Usage
calBPtoBCAD(x, zero = TRUE)
Arguments
x |
The calBP age(s) to be translated into BC/AD ages. |
zero |
Whether or not zero BC/AD should be included. Defaults to |
Details
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 (i.e., 1 BC) to 1 AD. Other calendars, such as the astronomical one, do include zero. The often-used BCE/CE ages are equivalent to BC/AD.
Value
The BC/AD age(s). BC ages are negative, AD ages are positive.
Examples
calBPtoBCAD(2024)
calBPtoBCAD(1945:1955, zero=TRUE)
calBPtoBCAD(1945:1955, zero=FALSE)
Find the 14C age and error belonging to a cal BP age.
Description
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding 14C age and error are returned.
Usage
calBPtoC14(
x,
cc = 1,
postbomb = FALSE,
rule = 1,
cc.dir = NULL,
thiscurve = NULL
)
Arguments
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). |
Details
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.
Value
The calibration-curve 14C year belonging to the entered cal BP age
Author(s)
Maarten Blaauw
Examples
calBPtoC14(100)
Find the pMC and error belonging to a cal BP age.
Description
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding F14C value and error are returned.
Usage
calBPtoD14C(
x,
cc = 1,
postbomb = FALSE,
rule = 1,
cc.dir = NULL,
thiscurve = NULL,
decimals = 8
)
Arguments
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). |
decimals |
Amount of decimals required for the F14C value. Defaults to 8. |
Details
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.
Value
The calibration-curve 14C year belonging to the entered cal BP age
Author(s)
Maarten Blaauw
Examples
calBPtoD14C(100)
Find the F14C and error belonging to a cal BP age.
Description
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding F14C value and error are returned.
Usage
calBPtoF14C(
x,
cc = 1,
postbomb = FALSE,
rule = 1,
cc.dir = NULL,
thiscurve = NULL,
decimals = 8
)
Arguments
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). |
decimals |
Amount of decimals required for the F14C value. Defaults to 8. |
Details
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.
Value
The calibration-curve 14C year belonging to the entered cal BP age
Author(s)
Maarten Blaauw
Examples
calBPtoF14C(100)
calculate b2k ages from cal BP ages
Description
calculate b2k ages from cal BP ages
Usage
calBPtob2k(x)
Arguments
x |
The calBP age(s) to be translated into b2k ages. |
Details
Turn cal BP ages into b2k ages (years before AD 2000), which are often used in the ice core community.
Value
The b2k ages.
Examples
calBPtob2k(-50)
Find the pMC and error belonging to a cal BP age.
Description
Given a calendar age, the calibration curve (default cc=1) is interpolated and the corresponding F14C value and error are returned.
Usage
calBPtopMC(
x,
cc = 1,
postbomb = FALSE,
rule = 1,
cc.dir = NULL,
thiscurve = NULL,
decimals = 8
)
Arguments
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). |
decimals |
Amount of decimals required for the F14C value. Defaults to 8. |
Details
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.
Value
The calibration-curve 14C year belonging to the entered cal BP age
Author(s)
Maarten Blaauw
Examples
calBPtopMC(100)
Calculate calibrated distribution
Description
Calculate the calibrated distribution of a radiocarbon date.
Usage
caldist(
y,
er,
cc = 1,
postbomb = FALSE,
deltaR = 0,
deltaSTD = 0,
is.F = FALSE,
is.pMC = 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
)
Arguments
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. |
is.pMC |
Set this to TRUE if the provided age and error are in the pMC 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., |
Value
The probability distribution(s) as two columns: cal BP ages and their associated probabilities
Examples
calib <- caldist(130,10)
plot(calib, type="l")
postbomb <- caldist(-3030, 20, postbomb=1, BCAD=TRUE)
Comparison dates calibrated using both the t distribution (Christen and Perez 2009) and the normal distribution.
Description
Visualise how a date calibrates using the t distribution and the normal distribution.
Usage
calib.t(
y = 2450,
er = 50,
t.a = 3,
t.b = 4,
cc = 1,
postbomb = FALSE,
deltaR = 0,
deltaSTD = 0,
as.F = FALSE,
is.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()
)
Arguments
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 |
is.F |
Use this if the provided date is in the F14C realm. |
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 |
Details
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'.
Author(s)
Maarten Blaauw
Examples
calib.t()
Plot individual calibrated dates.
Description
Calibrate individual 14C dates, plot them and report calibrated ranges.
Usage
calibrate(
age = 2450,
error = 50,
cc = 1,
postbomb = FALSE,
deltaR = 0,
deltaSTD = 0,
bombalert = TRUE,
thiscurve = c(),
as.F = FALSE,
is.F = FALSE,
is.pMC = 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,
...
)
Arguments
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 |
is.F |
Use |
is.pMC |
Use |
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 1.8. |
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 |
Not used, use yr.steps instead. |
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. |
Details
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.
Value
A graph of the raw and calibrated C-14 date, the calibrated ranges and, invisibly, the calibrated distribution and hpd ranges.
Examples
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))
Simulate removing contamination from a radiocarbon age
Description
Given an observed radiocarbon age, remove the impact of contamination (for example, 1% contamination with modern carbon) to estimate the true/target age
Usage
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(),
C14.axis = TRUE,
bty = "u"
)
Arguments
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. |
C14.axis |
Whether or not to draw a secondary vertical axis for C14 ages. Defaults to |
bty |
Draw a box around a box of a certain shape. Defaults to |
Details
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.
Value
The true/target radiocarbon age and error
Author(s)
Maarten Blaauw
Examples
# 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)
Simulate the impact of contamination on a radiocarbon age
Description
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).
Usage
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.7,
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(),
C14.axis = TRUE,
bty = "u"
)
Arguments
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. |
C14.axis |
Whether or not to draw a secondary vertical axis for C14 ages. Defaults to |
bty |
Draw a box around a box of a certain shape. Defaults to |
Details
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.
Value
The observed radiocarbon age and error
Author(s)
Maarten Blaauw
Examples
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 limit
Draw d14C and the calibration curve.
Description
Draw a proxy of the atmospheric 14C concentration (d14C) as well as the calibration curve.
Usage
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)
)
Arguments
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). |
Value
A plot of d14C and the calibration curve
Examples
draw.D14C()
draw.D14C(30e3, 55e3, ka=TRUE)
draw.D14C(cc=rintcal::ccurve("NH1_monthly"), BCAD=TRUE)
Draw a calibration curve.
Description
Draw one or two of the calibration curves, or add a calibration curve to an existing plot.
Usage
draw.ccurve(
cal1 = c(),
cal2 = c(),
cc1 = "IntCal20",
cc2 = NA,
cc1.postbomb = FALSE,
cc2.postbomb = FALSE,
BCAD = FALSE,
realm = "C14",
as.F = FALSE,
as.pMC = FALSE,
as.D = FALSE,
realm2 = c(),
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",
...
)
Arguments
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 |
as.F |
Plot as F14C values. Defaults to |
as.pMC |
Plot as pMC values. Defaults to |
as.D |
Plot as D14C values. Defaults to |
realm2 |
Which 'realm' to use for the second calibration curve (if used). 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. |
Value
A plot of the calibration curve
Examples
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 contamination impacts
Description
Show how contamination with different fractions of modern carbon affect observed C-14 ages.
Usage
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"
)
Arguments
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 |
Value
A plot of real and observed (contamination-impacted) C14 ages.
Examples
draw.contamination()
draw.contamination(40e3, 50e3, ka=FALSE)
add calibrated distributions to a plot.
Description
Add individual or multiple calibrated dates to a plot.
Usage
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,
...
)
Arguments
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 |
Value
A plot of the (calibrated) dates
Examples
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))
Find nearby shell-derived dR values
Description
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.
Usage
find.shells(
longitude,
latitude,
nearest = 50,
browse = FALSE,
colour = "dR",
rainbow = FALSE,
size = 2,
mapsize = "large",
mincol = "yellow",
maxcol = "red",
symbol = "feeding",
symbol.legend = TRUE,
legend.loc = c(0.95, 0.02),
legend.size = c(0.05, 0.2),
ocean.col = "aliceblue",
land.col = rgb(0, 0.5, 0, 0.6),
padding = 1,
warn = TRUE,
currents = TRUE
)
Arguments
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. |
browse |
Type of map to provide. |
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" 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 "small" if 'rnaturalearthhires' is not installed, and to "large" 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. |
legend.loc |
Location of the legend, if using a basic plot. Defaults to the bottom right corner based on par("usr"), |
legend.size |
Size of the legend, if using a basic plot. Defaults to |
ocean.col |
Colour for the oceans. Defaults to |
land.col |
Colour for the land. Defaults to semi-transparent darkgreen: |
padding |
Area around the map if using a basic plot. Avoids strange line features. Defaults to |
warn |
Whether or not to warn if some recommended R packages are not available. |
currents |
If set to TRUE (the default), the user will be asked if they want to browse a map of ocean currents. If the user responds 'y', an Internet browser window will be opened pointing to a zoomed-in map of ocean currents (at 50 m depth). The ocean currents are from 'earth.nullschool.net' and are based on an ocean circulation model which is updated daily. Owing to limitations of the website, the shell locations cannot currently be added to the page itself. |
Details
This function uses the 'rnaturalearth' package for country maps. If the high-resolution maps are desired, the 'rnaturalearthhires' package must be installed from GitHub.
Value
A dataset with the n nearest dR values, and a plot of their coordinates.
Examples
UK <- find.shells(0, 55, mapsize="small")
mean(UK$dR)
Caribbean <- find.shells(-70, 20, 30, mapsize="small")
Estimate a missing radiocarbon age from fractions
Description
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.
Usage
fractions(
bulk_age,
bulk_er,
fractions_percC,
fractions_weights,
fractions_ages,
fractions_errors,
roundby = 1,
talk = TRUE
)
Arguments
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 |
talk |
Provide feedback |
Examples
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 BP
translate between realms
Description
translate between realms
Usage
fromto(
x,
from = "calBP",
cc = 1,
postbomb = 1,
cc.dir = NULL,
thiscurve = NULL,
zero = TRUE,
width = c(),
digits = 0,
C14.col = rgb(0, 0, 1, 0.5),
D14C.col = rgb(0, 0.4, 0, 0.4),
ka = FALSE,
legend.size = 0.7
)
Arguments
x |
The value to be translated into other realms |
from |
The realm of the entered value. Can be "calBP" for cal BP, "BCAD" for BC/AD, "C14" for C14 BP, "F14C" for F14C, or "pMC" for pMC. D14C cannot be entered as a value (you could enter the corresponding cal BP or BC/AD ages instead). |
cc |
calibration curve for C14 (see |
postbomb |
Whether or not to use a postbomb curve (see |
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). |
zero |
Whether or not zero BC/AD should be included. Defaults to 0. |
width |
Width of the righthand plot. Calculated automatically by default (older ages get wider windows). |
digits |
Rounding of the reported values. Defaults to 0 digits. |
C14.col |
Colour of the 14C calibration curve. Defaults to semi-transparent blue, |
D14C.col |
Colour of the D14C curve. Defaults to semi-transparent green, |
ka |
Whether to use years or ka (thousands of years). Defaults to |
legend.size |
Size of the font of the legend. Defaults to 0.7 of R's standard size. |
Details
Upon entering a value and its realm, this function will find the corresponding values in the other realms. Note that uncertainties are *not* taken into account, and especially going from C14 BP to cal BP and BC/AD ignores many calibration-related uncertainties. D14C values are only reported for entered values on the cal BP or BC/AD scale.
Value
A plot and output showing the translations into the different realms.
Examples
fromto(0, "BCAD")
fromto(2450, "C14")
Amount of C14 particles in a sample
Description
Find the amount of remaining C14 atoms in a sample, given its weight and age.
Usage
howmanyC14(
age,
wght = 1,
use.cc = TRUE,
Av = 6.02214076e+23,
C14.ratio = 1.176e-12,
format = "g",
cc = 1,
postbomb = FALSE,
cc.dir = NULL,
thiscurve = NULL,
talk = TRUE,
decimals = 3
)
Arguments
age |
The age of the sample (in cal BP per default, or in C14 BP is use.cc=FALSE). |
wght |
The weight of the sample (in mg). Defaults to 1 mg. |
use.cc |
Whether or not to use the calibration curve. If set to |
Av |
Avogadro's number, used to calculate the number of carbon atoms in the sample. |
C14.ratio |
The 14C/C ratio at F=1 (AD 1950). |
format |
The format of the printed numbers. Defaults to either scientific (for large numbers) or as fixed-point, depending on the size of the number. |
cc |
calibration curve for C14 (see |
postbomb |
Whether or not to use a postbomb curve (see |
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). |
talk |
Whether or not to provide feedback (defaults to TRUE). |
decimals |
Number of decimals to be returned for F and atom counts. |
Details
The number of carbon atoms in the sample is estimated. Given the known C14/C ratio at F=1, and given the sample's age, we can estimate the number of remaining C14 atoms.
Value
The estimated number of C14 atoms.
Author(s)
Maarten Blaauw
Examples
howmanyC14(0) # recent sample
howmanyC14(55e3) # at dating limit
howmanyC14(145e3) # way beyond the dating limit, 1 C14 atom per mg remains
Calculate highest posterior density
Description
Calculate highest posterior density ranges of calibrated distribution
Usage
hpd(
calib,
prob = 0.95,
return.raw = FALSE,
BCAD = FALSE,
ka = FALSE,
age.round = 0,
prob.round = 1,
every = 0.1,
bins = 20
)
Arguments
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, |
ka |
Whether to report results in years (default) or as ka |
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). |
bins |
The number of bins required. Any distribution with fewer bins gets recalculated using 100 narrower bins. |
Value
The highest posterior density ranges, as three columns: from age, to age, and the corresponding percentage(s) of the range(s)
Examples
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 calendar age for a 14C date.
Description
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.
Usage
l.calib(
x,
y,
er,
cc = 1,
postbomb = FALSE,
deltaR = 0,
deltaSTD = 0,
thiscurve = c(),
cc.dir = c(),
normal = TRUE,
as.F = FALSE,
is.F = FALSE,
t.a = 3,
t.b = 4
)
Arguments
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 |
is.F |
Use this if the provided date is in the F14C realm. |
t.a |
Value a of the t distribution (defaults to 3). |
t.b |
Value b of the t distribution (defaults to 4). |
Details
The function cannot deal with multiple calibration curves if multiple calendar years or radiocarbon dates are entered.
Value
The calibrated probability of a calendar age for a 14C age
Author(s)
Maarten Blaauw
Examples
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')
Plot regional shell-derived dR values
Description
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).
Usage
map.shells(
S = 48,
W = -15,
N = 62,
E = 5,
browse = FALSE,
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),
legend.loc = c(0.95, 0.02),
legend.size = c(0.05, 0.2),
padding = 0.1,
warn = TRUE,
currents = TRUE
)
Arguments
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. |
browse |
Type of map to provide. |
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" 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 "small" if 'rnaturalearthhires' is not installed, and to "large" 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: |
legend.loc |
Location of the legend, if using a basic plot. Defaults to the bottom right corner based on par("usr"), |
legend.size |
Size of the legend, if using a basic plot. Defaults to |
padding |
Area around the map if using a basic plot. Avoids strange line features. Defaults to |
warn |
Whether or not to warn if some recommended R packages are not available. |
currents |
If set to TRUE (the default), the user will be asked if they want to browse a map of ocean currents. If the user responds 'y', an Internet browser window will be opened pointing to a zoomed-in map of ocean currents (at 50 m depth). The ocean currents are from 'earth.nullschool.net' and are based on an ocean circulation model which is updated daily. Owing to limitations of the website, the shell locations cannot currently be added to the page itself. |
Details
This function uses the 'rnaturalearth' package for country maps. If the high-resolution maps are desired, the 'rnaturalearthhires' package must be installed from GitHub.
Value
A plot and the relevant dR values.
Examples
N_UK <- map.shells(53, -11, 60, 2, mapsize="small")
mean(N_UK$dR)
Calculate the amount of muck/contamination to explain an observed C14 age
Description
Given an observed and a target radiocarbon age, calculate the amount of contamination required to explain the observed age.
Usage
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(),
C14.axis = TRUE,
bty = "u"
)
Arguments
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. |
C14.axis |
Whether or not to draw a secondary vertical axis for C14 ages. Defaults to |
bty |
Draw a box around a box of a certain shape. Defaults to |
Details
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.
Value
The required contamination (as percentage), as well as a plot
Author(s)
Maarten Blaauw
Examples
muck(600, 30, 2000, 0, 1, .01)
Find the probability of a calibrated date being older than a certain age
Description
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).
Usage
older(
x,
y,
er,
cc = 1,
postbomb = FALSE,
deltaR = 0,
deltaSTD = 0,
normal = TRUE,
as.F = FALSE,
is.F = FALSE,
t.a = 3,
t.b = 4,
BCAD = FALSE,
threshold = 0
)
Arguments
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 |
is.F |
Use this if the provided date is in the F14C realm. |
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 |
Details
The function can only deal with one date at a time.
Value
The probability of a date being older than a certain calendar age.
Author(s)
Maarten Blaauw
Examples
older(2800, 2450, 20)
older(2400, 2450, 20)
calibrate(160, 20, BCAD=TRUE)
older(1750, 160, 20, BCAD=TRUE)
The overlap between calibrated C14 dates
Description
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%.
Usage
overlap(
y,
er = c(),
labels = c(),
is.F = FALSE,
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,
xlim = c(),
xlab = c(),
yrby = 1,
dist.col = rgb(0, 0, 0, 0.2),
overlap.col = rgb(0, 0, 1, 0.4),
overlap.border = NA,
overlap.height = 1,
talk = TRUE,
visualise = TRUE,
prob = 0.95,
roundby = 1,
bty = "n",
yaxt = "n"
)
Arguments
y |
The set of radiocarbon dates. Alternatively, existing distributions can be provided as a list of distributions, e.g. already-calibrated distributions or distributions derived from age-model estimates. |
er |
The lab errors of the radiocarbon dates |
labels |
Labels to be printed for the distributions (optional). |
is.F |
Set this to TRUE if the provided age and error are in the F14C realm. |
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 |
xlim |
Age limits of the x-axis. Calculated automatically by default. |
xlab |
Label of the calendar age, defaults to BCAD or cal BP. |
yrby |
Resolution in years. Defaults to |
dist.col |
The colour of the individual (calibrated) distributions. Defaults to semi-transparent grey. Different colours can also be provided for the individual distributions. |
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. |
visualise |
Whether or not to plot the individual distributions and the overlap. |
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 |
yaxt |
Type of y-axis. Defaults to none drawn ( |
Value
The overlap between all calibrated probabilities as percentage, and a plot.
Examples
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, dist.col=3:4, labels=c("twig", "shell"))
mydists <- list(caldist(130,20, cc=1), caldist(150,20, cc=0))
overlap(mydists)
Probability of a date lying within a cal BP range
Description
Find the probability of a calibrated date lying within an age range
Usage
p.range(
x1,
x2,
y,
er,
cc = 1,
postbomb = FALSE,
deltaR = 0,
deltaSTD = 0,
normal = TRUE,
as.F = FALSE,
is.F = FALSE,
t.a = 3,
t.b = 4,
BCAD = FALSE,
threshold = 0
)
Arguments
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 |
is.F |
Use this if the provided date is in the F14C realm. |
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 |
Details
The function can only deal with one date at a time.
Value
The probability of a date lying within a certain calendar age range.
Author(s)
Maarten Blaauw
Examples
p.range(2800, 2400, 2450, 20)
To be deprecated. Use pMCtoC14 instead.
Description
Will be deprecated. Use pMCtoC14 instead.
Usage
pMC.age(mn, sdev = c(), ratio = 100, decimals = 0, lambda = 8033)
Arguments
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) |
Details
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.
Value
Radiocarbon ages from pMC values. If pMC values are above 100%, the resulting radiocarbon ages will be negative.
Calculate C14 ages from pMC values.
Description
Calculate C14 ages from pMC values of radiocarbon dates.
Usage
pMCtoC14(pMC, er = NULL, decimals = 0, lambda = 8033)
Arguments
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) |
Details
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.
Value
Radiocarbon ages from pMC values. If pMC values are above 100%, the resulting radiocarbon ages will be negative.
Examples
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 instead
Transform F14C into D14C
Description
Transform F14C into D14C
Usage
pMCtoD14C(pMC, er = NULL, t)
Arguments
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 |
Details
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.
Value
The corresponding D14C value
Examples
pMCtoD14C(0.985, .1, 222)
Calculate pMC ages from F14C values.
Description
Calculate pMC values from F14C values of radiocarbon dates.
Usage
pMCtoF14C(pMC, er = NULL)
Arguments
pMC |
Reported mean of the F14C |
er |
Reported error of the pMC value. Returns just the mean if left empty. |
Details
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.
Value
The F14C values from the pMC values. Basically the original values divided by 100.
Examples
pMCtoF14C(110, 5)
Calculate a point estimate
Description
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.
Usage
point.estimates(
calib,
wmean = TRUE,
median = TRUE,
mode = TRUE,
midpoint = TRUE,
prob = 0.95,
rounded = 1,
every = 1
)
Arguments
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 |
Value
The chosen point estimates
Examples
point.estimates(caldist(130,20))
plot(tmp <- caldist(2450,50), type='l')
abline(v=point.estimates(tmp), col=1:4)
Test if a set of radiocarbon dates can be combined
Description
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.
Usage
pool(
y,
er,
deltaR = 0,
deltaSTD = 0,
threshold = 0.05,
roundby = 1,
talk = TRUE
)
Arguments
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 |
talk |
It's better than staying silent. |
Details
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).
Value
The pooled mean and error if the p-value is above the threshold - a warning if it is not.
Author(s)
Maarten Blaauw
Examples
data(shroud)
pool(shroud$y,shroud$er)
Zu <- grep("ETH", shroud$ID) # Zurich lab only
pool(shroud$y[Zu],shroud$er[Zu])
Add a gamma distribution to a calibrated date
Description
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)
Usage
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,
is.F = FALSE,
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),
heights = 0.3,
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)
)
Arguments
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., |
is.F |
Use this if the provided date is in the F14C realm. |
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). |
heights |
Heights of the calibrated and 'pushed' distributions. Defaults to 0.3 of the device's height. |
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. |
Details
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.
Value
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
Examples
push.gamma(250, 25, 50, 2, add=FALSE) # subtract a gamma distribution
Add a normal distribution to a calibrated date
Description
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)
Usage
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),
heights = 0.3,
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)
)
Arguments
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). |
heights |
Heights of the calibrated and 'pushed' distributions. Defaults to 0.3 of the device's height. |
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. |
Details
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.
Value
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
Examples
push.normal(250, 25, 50, 10)
return a random calendar age from a calibrated distribution
Description
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.
Usage
r.calib(
n,
y,
er,
cc = 1,
postbomb = FALSE,
deltaR = 0,
deltaSTD = 0,
as.F = FALSE,
is.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
)
Arguments
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 |
is.F |
Use this if the provided date is in the F14C realm. |
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., |
Value
n randomly sampled calendar ages
Author(s)
Maarten Blaauw
Examples
r.calib(10,130,20) # 10 random cal BP ages
plot(density(r.calib(1e6, 2450, 20)))
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 uses the calibration curves from the data package 'rintcal'.
Provides equations for the handling of radiocarbon dates, for example to calculate different radiocarbon realms (C14 age, F14C, pMC, D14C), for their calibration, and estimating the effects of contamination. This package accompanies the data package rintcal.
Author(s)
Maintainer: Maarten Blaauw maarten.blaauw@qub.ac.uk (ORCID)
Maarten Blaauw <maarten.blaauw@qub.ac.uk>
shells Data
Description
A dataset containing the deltaR values and accompanying data from the marine database
Usage
shells
Format
A data frame with 1968 rows and 15 variables.
- lon
Longitude of the datapoint
- lat
Latitude of the datapoint
- no
Map or ID number of the datapoint
- taxonN
Taxon number of the datapoint
- dR
calculated deltaR of the datapoint
- dSTD
uncertainty of the deltaR of the datapoint
- collected
Collection year for the datapoint
- res
Reservoir effect of the datapoint
- res.error
Uncertainty of the reservoir effect of the datapoint
- C14
Radiocarbon age of the datapoint
- er
Error of the radiocarbon age of the datapoint
- lab
Lab code of the datapoint
- ref
Reference for the datapoint
- taxon
Taxon of the datapoint
- feeding
Feeding ecology of the datapoint (if known)
Source
Data downloaded from calib.org/marine
Examples
data(shells)
head(shells)
Plot and summarize the dR values
Description
After selecting a relevant range of shell values, plot them and calculate the weighted mean and variance.
Usage
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),
talk = TRUE
)
Arguments
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, |
talk |
Report details of the found values. |
Value
A plot of the dR values, as well as the weighted mean (vertical line) and (weighted) error (rectangle).
Examples
N_UK <- map.shells(53, -11, 60, 2, mapsize="small")
shells.mean(N_UK)
nearby <- find.shells(0,56,20) # somewhere in Scotland
shells.mean(nearby, distance=TRUE) # distance matters
shroud Data
Description
A dataset containing the radiocarbon dates on the Shroud of Turin, from three labs
Usage
shroud
Format
A data frame with 1968 rows and 15 variables.
- ID
Lab numbers. Replicates are indicates with .1, .2, etc.
- y
Radiocarbon year
- er
Lab error
Source
Data taken from Damon et al. 1989 [Nature] <doi:10.1038/337611a0>, see also Christen 1994 [Applied Statistics] <doi:10.2307/2986273>
Examples
data(shroud)
head(shroud)
Smooth a calibration curve
Description
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.
Usage
smooth.ccurve(
smooth = 30,
cc = 1,
postbomb = FALSE,
cc.dir = c(),
thiscurve = c(),
resample = 0,
name = "smoothed.csv",
save = FALSE,
sep = "\t"
)
Arguments
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, |
Details
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.
Author(s)
Maarten Blaauw
Examples
mycurve <- smooth.ccurve(smooth=50)
calibrate(2450,20, thiscurve=mycurve)
The time span between two calibrated dates
Description
Calculates the timespan between two calibrated radiocarbon dates. It does this by randomly sampling ages from both calibrated dates, followed by calculating the differences between all samples ages.
Usage
span(
y1,
er1,
y2,
er2,
n = 1e+05,
positive = FALSE,
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"
)
Arguments
y1 |
The first radiocarbon date. |
er1 |
The lab error of the first radiocarbon date. |
y2 |
The second radiocarbon date. |
er2 |
The lab error of the second radiocarbon date. |
n |
The number of iterations to base the calculations on. Defaults to 100,000. Different values for n could significantly alter performance and accuracy. |
positive |
Whether or not to enforce the span to be positive. If set to TRUE, then negative span values are removed. Defaults to FALSE. |
cc |
Calibration curve(s) 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). Can be a vector of length 2. |
deltaSTD |
Uncertainty of the age offset (1 standard deviation). Can be a vector of length 2. |
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). Can be a vector of length 2. |
t.b |
Value b of the t distribution (defaults to 4). Can be a vector of length 2. |
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 time span. |
talk |
Whether or not to report a summary of the span. |
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 |
Value
The time span.
Examples
span(2300, 20, 2350, 20)
The spread among calibrated dates
Description
Calculates the spread among multiple calibrated radiocarbon dates. It does this by randomly sampling ages from the calibrated dates, and calculating the difference between one random date and all others for that iteration.
Usage
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"
)
Arguments
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. Different values for n could significantly alter performance and accuracy. |
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 |
Value
The spread of all calibrated probabilities.
Examples
data(shroud)
spread(shroud$y,shroud$er)
Zu <- grep("ETH", shroud$ID) # Zurich lab only
spread(shroud$y[Zu],shroud$er[Zu])
Calculate the weighted mean of C14 ages
Description
Calculating the weighted mean of multiple C14 ages, using their means and lab errors.
Usage
weighted_means(y, er, round = 1, talk = TRUE)
Arguments
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. |
Value
The weighted mean and error (the latter is the maximum of the weighted error and the square root of the variance).
Examples
N_UK <- map.shells(53, -11, 60, 2, mapsize="small")
weighted_means(N_UK$dR, N_UK$dSTD)
Find the probability of a calibrated date being of a certain age or younger than it
Description
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).
Usage
younger(
x,
y,
er,
cc = 1,
postbomb = FALSE,
deltaR = 0,
deltaSTD = 0,
normal = TRUE,
as.F = FALSE,
is.F = FALSE,
t.a = 3,
t.b = 4,
BCAD = FALSE,
threshold = 0
)
Arguments
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 |
is.F |
Use this if the provided date is in the F14C realm. |
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 |
Details
The function can only deal with one date at a time.
Value
The probability of a date being of a certain calendar age or younger than it.
Author(s)
Maarten Blaauw
Examples
younger(2800, 2450, 20)
younger(2400, 2450, 20)
calibrate(160, 20, BCAD=TRUE)
younger(1750, 160, 20, BCAD=TRUE)