Package 'ananke'

Title: Quantitative Chronology in Archaeology
Description: Simple radiocarbon calibration and chronological analysis. This package allows the calibration of radiocarbon ages and modern carbon fraction values using multiple calibration curves. It allows the calculation of highest density region intervals and credible intervals. The package also provides tools for visualising results and estimating statistical summaries.
Authors: Nicolas Frerebeau [aut, cre] (ORCID: <https://orcid.org/0000-0001-5759-4944>), Université Bordeaux Montaigne [fnd] (ROR: <https://ror.org/03pbgwk21>), CNRS [fnd] (ROR: <https://ror.org/02feahw73>)
Maintainer: Nicolas Frerebeau <[email protected]>
License: GPL (>= 3)
Version: 0.2.0.9000
Built: 2026-05-12 19:47:28 UTC
Source: https://codeberg.org/tesselle/ananke

Help Index

Coerce to a Data Frame

Description

Coerce to a Data Frame

Usage

## S4 method for signature 'CalibratedAges'
as.data.frame(x, ..., level = 0.954, calendar = get_calendar())

## S4 method for signature 'CalibratedIntervals'
as.data.frame(x, ..., calendar = get_calendar())

## S4 method for signature 'RECE'
as.data.frame(x, ..., calendar = get_calendar())

## S4 method for signature 'ProxyRecord'
as.data.frame(x, ..., calendar = get_calendar())

Arguments

x

An R object.
...

Currently not used.
level

A length-one numeric vector giving the confidence level (see interval_hdr()).
calendar

An aion::TimeScale object specifying the target calendar (see aion::calendar()). If NULL, rata die are returned.

Value

A data.frame.

Author(s)

N. Frerebeau

See Also

Other mutators: as.list(), labels(), mutators, subset

Examples

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)

as.data.frame(cal)

as.data.frame(cal, calendar = BP())

Coerce to a list

Description

Coerce to a list

Usage

## S4 method for signature 'CalibratedIntervals'
as.list(x, ..., calendar = get_calendar())

Arguments

x

An R object.
...

Currently not used.
calendar

An aion::TimeScale object specifying the target calendar (see aion::calendar()). If NULL, rata die are returned.

Value

A list.

Author(s)

N. Frerebeau

See Also

Other mutators: as.data.frame, labels(), mutators, subset

Examples

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)

as.data.frame(cal)

as.data.frame(cal, calendar = BP())

14C Calibration

Description

Calibrates radiocarbon ages.

Usage

c14_calibrate(values, errors, ...)

## S4 method for signature 'numeric,numeric'
c14_calibrate(
  values,
  errors,
  curves = "intcal20",
  names = NULL,
  positions = NULL,
  reservoir_offsets = 0,
  reservoir_errors = 0,
  from = 55000,
  to = 0,
  resolution = 1,
  normalize = TRUE,
  F14C = FALSE,
  method = c("student", "normal"),
  dfs = 100,
  drop = TRUE,
  eps = 1e-06,
  verbose = getOption("ananke.verbose")
)

Arguments

values

A numeric vector giving the BP ages or F14C values to be calibrated (conventional ages).
errors

A numeric vector giving the errors associated to the values to be calibrated.
...

Currently not used.
curves

A character vector specifying the calibration curve to be used. Different curves can be specified per sample.
names

A character vector specifying the names of the samples (e.g. laboratory codes).
positions

A numeric vector giving the position values (e.g. depths) for each age.
reservoir_offsets

A numeric vector giving the offset values for any marine reservoir effect (defaults to 0; i.e. no offset).
reservoir_errors

A numeric vector giving the offset value errors for any marine reservoir effect (defaults to 0; i.e. no offset).
from

length-one numeric vector specifying the earliest data to calibrate for, in cal. BP years.
to

A length-one numeric vector specifying the latest data to calibrate for, in cal. BP years.
resolution

A length-one numeric vector specifying the temporal resolution (in years) of the calibration.
normalize

A logical scalar: should the calibration be normalized?
F14C

A logical scalar: should the calibration be carried out in F14C space? If TRUE, values must be expressed as F14C.
method

A character string specifying the distribution assumed for the 14C ages. It must be one of "student" (the default) or "normal. Only used if F14C is FALSE.
dfs

A character vector giving the degrees-of-freedom values for the student t-distribution associated with the calibration calculation. Only used if method is "student".
drop

A logical scalar: should years with zero probability be discarded? If TRUE (the default), results in a narrower time range.
eps

A length-one numeric value giving the cutoff below which calibration values will be removed.
verbose

A logical scalar: should extra information be reported (e.g. warning message for dates out of calibration range)?

Value

A CalibratedAges object.

Note

Adapted from Bchron BchronCalibrate() by Andrew Parnell and rcarbon calibrate() by Andrew Bevan and Enrico Crema.

Author(s)

N. Frerebeau

References

Bronk Ramsey, C. (2008). Radiocarbon Dating: Revolutions in Understanding. Archaeometry, 50:249-275. doi:10.1111/j.1475-4754.2008.00394.x.

See Also

Other radiocarbon tools: F14C, c14_combine(), c14_count(), c14_curve(), c14_plot, c14_sample(), c14_spd(), c14_uncalibrate(), rec_plot, ridgelines()

Examples

## Calibrate a single date
cal <- c14_calibrate(300, 20)
plot(cal, panel.first = graphics::grid())

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)
plot(cal)

## Calibrate F14C
cal <- c14_calibrate(
  values = 0.0062,
  errors = 0.0006,
  F14C = TRUE
)
plot(cal)


## Out of 14C range?
out <- c14_calibrate(130, 20)
plot(out)

Combine 14C

Description

Combines radiocarbon dates.

Usage

c14_combine(values, errors, ...)

## S4 method for signature 'numeric,numeric'
c14_combine(values, errors, groups = NULL)

Arguments

values

A numeric vector giving the BP ages to be calibrated.
errors

A numeric vector giving the standard deviation of the ages to be calibrated.
...

Currently not used.
groups

A factor in the sense that as.factor(groups) defines the the groups to combine with. If NULL (the default), all dates are combined. NAs will be treated as isolated dates.

Value

A data.frame with the following columns:

groups Group names
ages Combined 14C ages
errors Combined 14C standard deviations
chi2 Chi-squared test statistic
p Chi-squared test p-value

Author(s)

N. Frerebeau

References

Ward, G. K. and Wilson, S. R. (1978). Procedures for Comparing and Combining Radiocarbon Age Determinations: A Critique. Archaeometry 20(1): 19‑31. doi:10.1111/j.1475-4754.1978.tb00208.x.

See Also

Other radiocarbon tools: F14C, c14_calibrate(), c14_count(), c14_curve(), c14_plot, c14_sample(), c14_spd(), c14_uncalibrate(), rec_plot, ridgelines()

Examples

## Replicate Ward and Wilson (1978), p. 28
polach1972 <- data.frame(
  samples = c("ANU-7", "ANU-7", "ANU-7", "W-1571", "ANU-5",
              "C-800", "L-698D", "FSU-3", "Tx-44"),
  ages = c(14550, 15000, 13700, 14650, 11700, 10860, 11840, 11245, 10700),
  errors = c(270, 600, 300, 500, 260, 410, 100, 450, 210)
)

c14_combine(
  values = polach1972$ages,
  errors = polach1972$errors,
  groups = polach1972$samples
)

Radiocarbon Event Count

Description

Radiocarbon Event Count

Usage

c14_count(object, ...)

## S4 method for signature 'CalibratedAges'
c14_count(
  object,
  from = NULL,
  to = NULL,
  by = 10,
  n = 100,
  calendar = BP(),
  progress = getOption("ananke.progress")
)

Arguments

object

A CalibratedAges object.
...

Currently not used.
from

length-one numeric vector specifying the earliest data to calibrate for (in cal BP years).
to

A length-one numeric vector specifying the latest data to calibrate for (in cal BP years).
by

A length-one numeric vector specifying the temporal resolution (in years) of the calibration.
n

An integer specifying the number of item to choose randomly.
calendar

An aion::TimeScale object specifying the target calendar (see aion::calendar()). Defaults to aion::CE(). If NULL, rata die are returned.
progress

A logical scalar: should a progress bar be displayed?

Value

An RECE object.

Note

This function is currently experimental.

Author(s)

N. Frerebeau

References

Carleton, W. C. (2021). Evaluating Bayesian Radiocarbon‐dated Event Count (REC) Models for the Study of Long‐term Human and Environmental Processes. Journal of Quaternary Science, 36(1): 110‑23. doi:10.1002/jqs.3256.

See Also

Other radiocarbon tools: F14C, c14_calibrate(), c14_combine(), c14_curve(), c14_plot, c14_sample(), c14_spd(), c14_uncalibrate(), rec_plot, ridgelines()

Examples

## Radiocarbon data from Bosch et al. 2015
data("ksarakil")

## Calibrate
cal <- c14_calibrate(
  values = ksarakil$date,
  errors = ksarakil$error,
  names = ksarakil$code,
  curves = "marine13",
  reservoir_offsets = 53,
  reservoir_errors = 43,
  from = 50000, to = 0
)

## RECE
tmp <- c14_count(cal, n = 500)
plot(tmp, col = grDevices::hcl.colors(12, "Viridis", rev = TRUE))

14C Calibration Curve

Description

14C Calibration Curve

Usage

c14_curve(name, ...)

## S4 method for signature 'character'
c14_curve(name)

## S4 method for signature 'CalibratedAges'
c14_curve(name)

Arguments

name

A character vector naming calibration curves (see details).
...

Currently not used.

Details

The following calibration curves are available:

Curve Reference
intcal04 Reimer et al. 2004
intcal09 Reimer et al. 2009
intcal13 Reimer et al. 2013
intcal20 Reimer et al. 2020
marine04 Hughen et al. 2004
marine09 Reimer et al. 2009
marine13 Reimer et al. 2013
marine20 Heaton et al. 2020
shcal04 McCormac et al. 2004
shcal13 Hogg et al. 2013
shcal20 Hogg et al. 2020

Value

A list of three-column data.frame:

CALBP Calibrated age BP
AGE Uncalibrated radiocarbon age
ERROR Standard deviation

Author(s)

N. Frerebeau

References

Heaton, Timothy J, Peter Köhler, Martin Butzin, Edouard Bard, Ron W Reimer, William E N Austin, Christopher Bronk Ramsey, et al. (2020). Marine20 The Marine Radiocarbon Age Calibration Curve (0-55,000 Cal BP). Radiocarbon, 62(4): 779-820. doi:10.1017/RDC.2020.68.

Hogg, Alan G, Timothy J Heaton, Quan Hua, Jonathan G Palmer, Chris SM Turney, John Southon, Alex Bayliss, et al. (2020). SHCal20 Southern Hemisphere Calibration, 0-55,000 Years Cal BP. Radiocarbon, 62(4): 759-78. doi:10.1017/RDC.2020.59.

Hogg, Alan G, Quan Hua, Paul G Blackwell, Mu Niu, Caitlin E Buck, Thomas P Guilderson, Timothy J Heaton, et al. (2013). SHCal13 Southern Hemisphere Calibration, 0-50,000 Years Cal BP. Radiocarbon, 55(4): 1889-1903. doi:10.2458/azu_js_rc.55.16783.

Hua, Quan, and Mike Barbetti (2004). Review of Tropospheric Bomb 14C Data for Carbon Cycle Modeling and Age Calibration Purposes. Radiocarbon, 46(3): 1273-1298. doi:10.1017/S0033822200033142.

Hua, Quan, Mike Barbetti, and Andrzej Z Rakowski (2013). Atmospheric Radiocarbon for the Period 1950-2010. Radiocarbon, 55(4): 2059‑2072. doi:10.2458/azu_js_rc.v55i2.16177.

Hua, Quan, Jocelyn C Turnbull, Guaciara M Santos, Andrzej Z Rakowski, Santiago Ancapichún, Ricardo De Pol-Holz, Samuel Hammer, et al. (2022). Atmospheric Radiocarbon for the Period 1950-2019. Radiocarbon, 64(4): 723‑745. doi:10.1017/RDC.2021.95.

Hughen, K., S. Lehman, J. Southon, J. Overpeck, O. Marchal, C. Herring, and J. Turnbull (2004). 14C Activity and Global Carbon Cycle Changes over the Past 50,000 Years. Science, 303(5655): 202‑207. doi:10.1126/science.1090300.

Hughen, Konrad A, Mike G L Baillie, Edouard Bard, J Warren Beck, Chanda J H Bertrand, Paul G Blackwell, Caitlin E Buck, et al. (2004). Marine04 Marine Radiocarbon Age Calibration, 0-26 cal kyr BP. Radiocarbon, 46(3): 1059‑1086. doi:10.1017/S0033822200033002.

Kueppers, Lara M., John Southon, Paul Baer, and John Harte (2004). Dead Wood Biomass and Turnover Time, Measured by Radiocarbon, along a Subalpine Elevation Gradient. Oecologia, 141(4): 641‑651. doi:10.1007/s00442-004-1689-x.

McCormac, F G, A G Hogg, P G Blackwell, C E Buck, T F G Higham, and P J Reimer (2004). Shcal04 Southern Hemisphere Calibration, 0-11.0 cal kyr BP. Radiocarbon, 46(3): 1087‑1092. doi:10.1017/S0033822200033014.

Reimer, P J, M G L Baillie, E Bard, A Bayliss, J W Beck, P G Blackwell, C Bronk Ramsey, et al. (2009). IntCal09 and Marine09 Radiocarbon Age Calibration Curves, 0-50,000 Years cal BP. Radiocarbon, 51(4): 1111‑1150. doi:10.1017/S0033822200034202.

Reimer, Paula J, William E N Austin, Edouard Bard, Alex Bayliss, Paul G Blackwell, Christopher Bronk Ramsey, Martin Butzin, et al. (2020). The IntCal20 Northern Hemisphere Radiocarbon Age Calibration Curve (0-55 cal kBP). Radiocarbon, 62(4): 725‑757. doi:10.1017/RDC.2020.41.

Reimer, Paula J, Mike G L Baillie, Edouard Bard, Alex Bayliss, J Warren Beck, Chanda J H Bertrand, Paul G Blackwell, et al. (2004). Intcal04 Terrestrial Radiocarbon Age Calibration, 0-26 cal kyr BP. Radiocarbon, 46(3): 1029‑1058. doi:10.1017/S0033822200032999.

Reimer, Paula J, Edouard Bard, Alex Bayliss, J Warren Beck, Paul G Blackwell, Christopher Bronk Ramsey, Caitlin E Buck, et al. (2013). IntCal13 and Marine13 Radiocarbon Age Calibration Curves 0-50,000 Years cal BP. Radiocarbon, 55(4): 1869‑1887. doi:10.2458/azu_js_rc.55.16947.

Stuiver, Minze, Paula J. Reimer, Edouard Bard, J. Warren Beck, G. S. Burr, Konrad A. Hughen, Bernd Kromer, Gerry McCormac, Johannes van der Plicht, and Marco Spurk (1998). INTCAL98 Radiocarbon Age Calibration, 24,000-0 cal BP. Radiocarbon, 40(3): 1041‑1083. doi:10.1017/S0033822200019123.

Stuiver, Minze, Paula J. Reimer, and Thomas F. Braziunas. (1998). High-Precision Radiocarbon Age Calibration for Terrestrial and Marine Samples. Radiocarbon, 40(3): 1127‑1151. doi:10.1017/S0033822200019172.

See Also

Other radiocarbon tools: F14C, c14_calibrate(), c14_combine(), c14_count(), c14_plot, c14_sample(), c14_spd(), c14_uncalibrate(), rec_plot, ridgelines()

Examples

## IntCal20
intcal20 <- c14_curve("intcal20")
head(intcal20[[1]])

## IntCal
intcal <- c14_curve(c("intcal09", "intcal13", "intcal20"))
lapply(X = intcal, FUN = head)

Plot Calibrated Radiocarbon Ages

Description

Plot Calibrated Radiocarbon Ages

Usage

## S4 method for signature 'CalibratedAges,missing'
plot(
  x,
  calendar = get_calendar(),
  interval = c("hdr", "credible"),
  level = 0.954,
  sort = TRUE,
  decreasing = FALSE,
  col = "grey",
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = TRUE,
  panel.first = NULL,
  panel.last = NULL,
  ...
)

## S4 method for signature 'CalibratedSPD,missing'
plot(
  x,
  calendar = get_calendar(),
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = TRUE,
  panel.first = NULL,
  panel.last = NULL,
  ...
)

Arguments

x

A CalibratedAges or CalibratedSPD object.
calendar

An aion::TimeScale object specifying the target calendar (see aion::calendar()). If NULL, rata die are returned.
interval

A character string specifying the intervals to be drawn. It must be one of "hrd" (the default) or "credible". Any unambiguous substring can be given.
level

A length-one numeric vector giving the confidence level. Only used if interval is TRUE.
sort

A logical scalar: should ages be arranged in chronological order?
decreasing

A logical scalar: should the sort order be decreasing?
col

A specification for the plotting colors.
main

A character string giving a main title for the plot.
sub

A character string giving a subtitle for the plot.
ann

A logical scalar: should the default annotation (title and x and y labels) appear on the plot?
axes

A logical scalar: should axes be drawn on the plot?
frame.plot

A logical scalar: should a box be drawn around the plot?
panel.first

An an expression to be evaluated after the plot axes are set up but before any plotting takes place. This can be useful for drawing background grids.
panel.last

An expression to be evaluated after plotting has taken place but before the axes, title and box are added.
...

Further parameters to be passed to aion::plot().

Value

plot() is called it for its side-effects: it results in a graphic being displayed. Invisibly returns x.

Author(s)

N. Frerebeau

See Also

Other radiocarbon tools: F14C, c14_calibrate(), c14_combine(), c14_count(), c14_curve(), c14_sample(), c14_spd(), c14_uncalibrate(), rec_plot, ridgelines()

Examples

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)

## Specify calendar
plot(cal, calendar = b2k(), flip = TRUE)

## HDR intervals (default)
plot(cal, interval = "hdr", level = 0.95)

## Credible intervals
plot(cal, interval = "credible", level = 0.95)

## No intervals
plot(cal, level = 0)

Sample Calibrated Ages

Description

Sample Calibrated Ages

Usage

c14_sample(object, ...)

## S4 method for signature 'CalibratedAges'
c14_sample(object, n = 100, calendar = get_calendar())

Arguments

object

A CalibratedAges object.
...

Currently not used.
n

An integer specifying the number of random samples.
calendar

An aion::TimeScale object specifying the target calendar (see aion::calendar()). Defaults to aion::CE(). If NULL, rata die are returned.

Value

An numeric matrix.

Author(s)

N. Frerebeau

See Also

Other radiocarbon tools: F14C, c14_calibrate(), c14_combine(), c14_count(), c14_curve(), c14_plot, c14_spd(), c14_uncalibrate(), rec_plot, ridgelines()

Examples

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)

## Sample
spl <- c14_sample(cal, n = 100)

Summed Probability Distributions

Description

Computes summed probability distributions (SPD) of radiocarbon dates.

Usage

c14_spd(object, ...)

## S4 method for signature 'CalibratedAges'
c14_spd(object, normalize_date = FALSE, normalize_spd = FALSE)

Arguments

object

A CalibratedAges object.
...

Currently not used.
normalize_date

A logical scalar: should the total probability mass of the calibrated dates be normalised (to sum to unity within the time-span of analysis)?
normalize_spd

A logical scalar: should the total probability mass of the SPD be normalised (to sum to unity)?

Details

Summed probability distributions (SPD) are not statistically valid estimators of the calendar age of a potential future sample. They should not be used in any dates-as-data approach to provide a population proxy.

Value

A CalibratedSPD object.

Author(s)

N. Frerebeau

See Also

Other radiocarbon tools: F14C, c14_calibrate(), c14_combine(), c14_count(), c14_curve(), c14_plot, c14_sample(), c14_uncalibrate(), rec_plot, ridgelines()

Examples

## Radiocarbon data from Bosch et al. 2015
data("ksarakil")

## Calibrate
cal <- c14_calibrate(
  values = ksarakil$date,
  errors = ksarakil$error,
  names = ksarakil$code,
  curves = "marine13",
  reservoir_offsets = 53,
  reservoir_errors = 43,
  from = 50000, to = 0
)
plot(cal, level = 0.68)

## SPD
s <- c14_spd(cal)
plot(s)

Uncalibrate a Radiocarbon Date

Description

Uncalibrate a Radiocarbon Date

Usage

c14_uncalibrate(object, ...)

## S4 method for signature 'numeric'
c14_uncalibrate(object, curves = "intcal20")

## S4 method for signature 'CalibratedAges'
c14_uncalibrate(object, n = 10000, rounding = getOption("ananke.round"), ...)

Arguments

object

A CalibratedAges object or a numeric vector of calibrated ages (in years BP).
...

Currently not used.
curves

A character vector specifying the calibration curve to be used. Different curves can be specified.
n

An integer specifying the number of random samples.
rounding

A character string specifying the rounding convention. It can be one of "none" (the default, no rounding) or "stuiver". Any unambiguous substring can be given.

Author(s)

N. Frerebeau

See Also

Other radiocarbon tools: F14C, c14_calibrate(), c14_combine(), c14_count(), c14_curve(), c14_plot, c14_sample(), c14_spd(), rec_plot, ridgelines()

Examples

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)

## Uncalibrate
c14_uncalibrate(cal, rounding = "stuiver")

Data Description

Description

Data Description

Usage

## S4 method for signature 'CalibratedAges'
describe(x, calendar = get_calendar(), level = 0.954, ...)

Arguments

x

A CalibratedAges object.
calendar

An aion::TimeScale object specifying the target calendar (see aion::calendar()).
level

A length-one numeric vector giving the confidence level.
...

Further parameters to be passed to cat().

Value

describe() is called for its side-effects. Invisibly returns x.

Author(s)

N. Frerebeau

References

Millard, A. R. (2014). Conventions for Reporting Radiocarbon Determinations. Radiocarbon, 56(2): 555-559. doi:10.2458/56.17455.

See Also

Other summary: summary()

Examples

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)

## Full text description
describe(cal)

F14C

Description

Converts F14C values to 14C ages.

Usage

c14_f14c(values, errors, ...)

f14c_c14(values, errors, ...)

## S4 method for signature 'numeric,numeric'
c14_f14c(values, errors, tau = 8033)

## S4 method for signature 'numeric,numeric'
f14c_c14(
  values,
  errors,
  tau = 8033,
  asymmetric = FALSE,
  rounding = getOption("ananke.round")
)

Arguments

values

A numeric vector giving the radiocarbon ages or the F14C values.
errors

A numeric vector giving the standard deviations.
...

Currently not used.
tau

A length-one numeric vector specifying the mean-life of radiocarbon (defaults to 14C half-life value as introduced by Libby 1952).
asymmetric

A logical scalar: should asymmetric 14C errors be returned (van der Plicht & Hogg, 2006)?
rounding

A character string specifying the rounding convention. It can be one of "none" (the default, no rounding) or "stuiver". Any unambiguous substring can be given.

Details

f14c_c14() calculates the conventional radiocarbon age:

t=−1λln⁡F14C=−τln⁡F14Ct = -\frac{1}{\lambda}\ln{F^{14}C} = -\tau\ln{F^{14}C}

c14_f14c() calculates the inverse:

F14C=e−λt=e−tτF^{14}C = e^{-\lambda t} = e^{-\frac{t}{\tau}}

Value

A data.frame.

Author(s)

N. Frerebeau

References

Bronk Ramsey, C. (2008). Radiocarbon Dating: Revolutions in Understanding. Archaeometry, 50:249-275. doi:10.1111/j.1475-4754.2008.00394.x.

Stuiver, M., Polach, H. A. (1977). Discussion Reporting of 14C Data. Radiocarbon, 19(3): 355-363. doi:10.1017/S0033822200003672.

van der Plicht, J., Hogg, A. (2006). A Note on Reporting Radiocarbon. Quaternary Geochronology, 1(4): 237-240. doi:10.1016/j.quageo.2006.07.001.

See Also

Other radiocarbon tools: c14_calibrate(), c14_combine(), c14_count(), c14_curve(), c14_plot, c14_sample(), c14_spd(), c14_uncalibrate(), rec_plot, ridgelines()

Examples

## Asymmetric 14C errors (van der Plicht and Hogg 2006)
f14c_c14(0.0052, 0.0006, asym = TRUE)

## Symmetric 14C errors (Bronk Ramsey 2008)
f14c_c14(0.0052, 0.0006, asym = FALSE)

Bayesian Credible Interval

Description

Bayesian Credible Interval

Usage

## S4 method for signature 'CalibratedAges'
interval_credible(x, level = 0.954, n = 100, ...)

Arguments

x

A CalibratedAges object.
level

A length-one numeric vector giving the confidence level.
n

An integer specifying the number of random samples.
...

Currently not used.

Value

A CalibratedIntervals object.

Author(s)

N. Frerebeau

See Also

arkhe::interval_credible()

Other statistics: interval_hdr, mean(), median(), quantile(), radialplot()

Examples

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)

## Credible intervals
crd68 <- interval_credible(cal, level = 0.683)
crd95 <- interval_credible(cal, level = 0.954)
crd99 <- interval_credible(cal, level = 0.997)

## Coerce to data.frame
as.data.frame(crd95, calendar = BC())

## Plot
plot(cal, interval = "credible")

Highest Density Regions

Description

Highest Density Regions

Usage

## S4 method for signature 'CalibratedAges,missing'
interval_hdr(x, level = 0.954, ...)

Arguments

x

A CalibratedAges object.
level

A length-one numeric vector giving the confidence level.
...

Currently not used.

Value

A CalibratedIntervals object.

Author(s)

N. Frerebeau

References

Hyndman, R. J. (1996). Computing and graphing highest density regions. American Statistician, 50: 120-126. doi:10.2307/2684423.

See Also

stats::density(), arkhe::interval_hdr()

Other statistics: interval_credible, mean(), median(), quantile(), radialplot()

Examples

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)

## HDR
hdr68 <- interval_hdr(cal, level = 0.683)
hdr95 <- interval_hdr(cal, level = 0.954)
hdr99 <- interval_hdr(cal, level = 0.997)

## Coerce to a data.frame
as.data.frame(hdr95, calendar = BC())
## Coerce to a list
as.list(hdr95)

## Plot
plot(hdr95, lwd = 3)

Ksâr 'Akil Radiocarbon Dates

Description

Ksâr 'Akil Radiocarbon Dates

Usage

ksarakil

Format

A data.frame with 16 rows and 5 variables:

code

Laboratory code.

date

Radiocarbon date (year BP).

error

Radiocarbon error (year).

layer

Stratigraphic layer.

phase

Chronological phase.

Source

Bosch, M. D., Mannino, M. A., Prendergast, A. L., O'Connell, T. C., Demarchi, B., Taylor, S. M., Niven, L., van der Plicht, J. and Hublin, J.-J. (2015). New Chronology for Ksâr 'Akil (Lebanon) Supports Levantine Route of Modern Human Dispersal into Europe. Proceedings of the National Academy of Sciences 112(25): 7683-8. doi:10.1073/pnas.1501529112.

Find Labels from Object

Description

Find a suitable set of labels from an object for use in printing or plotting, for example.

Usage

## S4 method for signature 'CalibratedAges'
labels(object, ...)

Arguments

object

An object from which to find labels.
...

Currently not used.

Value

A character vector.

Author(s)

N. Frerebeau

See Also

Other mutators: as.data.frame, as.list(), mutators, subset

Mean

Description

Mean

Usage

## S4 method for signature 'CalibratedAges'
mean(x, na.rm = FALSE, ..., calendar = get_calendar())

## S4 method for signature 'ProxyRecord'
mean(x, na.rm = FALSE, ...)

Arguments

x

A CalibratedAges object.
na.rm

A logical scalar: should NA values be stripped before the computation proceeds?
...

Currently not used.
calendar

An aion::TimeScale object specifying the target calendar (see aion::calendar()). If NULL, rata die are returned.

Value

A numeric vector.

Author(s)

N. Frerebeau

See Also

Other statistics: interval_credible, interval_hdr, median(), quantile(), radialplot()

Examples

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)

## Statistics
quantile(cal)
median(cal)
mean(cal)

## Plot
plot(cal, calendar = CE())

## Need to set 'calendar'
abline(v = median(cal, calendar = CE()), lty = 2, col = "blue")
abline(v = mean(cal, calendar = CE()), lty = 2, col = "red")

Median

Description

Median

Usage

## S4 method for signature 'CalibratedAges'
median(x, na.rm = FALSE, ..., calendar = get_calendar())

Arguments

x

A CalibratedAges object.
na.rm

A logical scalar: should NA values be stripped before the computation proceeds?
...

Currently not used.
calendar

An aion::TimeScale object specifying the target calendar (see aion::calendar()). If NULL, rata die are returned.

Value

A numeric vector.

Author(s)

N. Frerebeau

See Also

Other statistics: interval_credible, interval_hdr, mean(), quantile(), radialplot()

Examples

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)

## Statistics
quantile(cal)
median(cal)
mean(cal)

## Plot
plot(cal, calendar = CE())

## Need to set 'calendar'
abline(v = median(cal, calendar = CE()), lty = 2, col = "blue")
abline(v = mean(cal, calendar = CE()), lty = 2, col = "red")

Get or Set Parts of an Object

Description

Getters and setters to extract or replace parts of an object.

Arguments

x

An object from which to get or set element(s).
value

A possible value for the element(s) of x.

Value

An object of the same sort as x with the new values assigned.

Author(s)

N. Frerebeau

See Also

Other mutators: as.data.frame, as.list(), labels(), subset

Geological Model Age from Lead Isotope Analysis

Description

Compute geological model age (T) and U/Pb (mu) and Th/U (kappa) ratios from lead isotopic measurements.

Usage

pb_age(x, y, z, ...)

## S4 method for signature 'numeric,numeric,numeric'
pb_age(
  x,
  y,
  z,
  t0 = 3.8,
  x_star = 18.75,
  y_star = 15.63,
  z_star = 38.86,
  mu = 9.66,
  kappa = 3.9,
  th232 = 0.049475,
  u238 = 0.155125,
  u235 = 0.98485,
  u238_235 = 137.79,
  tolerance = sqrt(.Machine$double.eps),
  stop = 100
)

## S4 method for signature 'list,missing,missing'
pb_age(
  x,
  t0 = 3.8,
  x_star = 18.75,
  y_star = 15.63,
  z_star = 38.86,
  mu = 9.66,
  kappa = 3.9,
  th232 = 0.049475,
  u238 = 0.155125,
  u235 = 0.98485,
  u238_235 = 137.79,
  tolerance = sqrt(.Machine$double.eps),
  stop = 100
)

Arguments

x

A numeric vector of 206Pb/204Pb ratios. If y and z are missing, must be a list (or a data.frame) with numeric components (columns) x, y and z.
y

A numeric vector of 207Pb/204Pb ratios. If missing, an attempt is made to interpret x in a suitable way.
z

A numeric vector of 208Pb/204Pb ratios. If missing, an attempt is made to interpret x in a suitable way.
...

Currently not used.
t0

A numeric value giving the time of the second stage of the reference model.
x_star

A numeric value giving the 206Pb/204Pb ratio at t=0t = 0.
y_star

A numeric value giving the 207Pb/204Pb ratio at t=0t = 0.
z_star

A numeric value giving the 208Pb/204Pb ratio at t=0t = 0.
mu

A numeric value giving the 238U/204Pb ratio of the reference model.
kappa

A numeric value giving the 232Th/238U ratio of the reference model.
th232

A numeric value giving the decay constants of 232Th.
u238

A numeric value giving the decay constants of 238U.
u235

A numeric value giving the decay constants of 235U.
u238_235

A numeric value giving the actual 238U/235U ratio.
tolerance

A numeric value specifying the tolerance (stopping criteria for the Newton–Raphson method).
stop

An integer giving the stopping rule (i.e. maximum number of iterations) to avoid infinite loop.

Value

A four columns data.frame:

age

Geological model age (in Ma).

mu

238U/204Pb ratio.

kappa

232Th/238U ratio.

residual

Newton loop residual.

Note

Reference values from Albarede & Juteau (1984).

Author(s)

N. Frerebeau, F. Albarede (original Matlab code)

References

Albarède, F., Desaulty, A.-M. & Blichert-Toft, J. (2012). A Geological Perspective on the Use of Pb Isotopes in Archaeometry. Archaeometry, 54: 853-867. doi:10.1111/j.1475-4754.2011.00653.x.

Albarède, F. & Juteau, M. (1984). Unscrambling the Lead Model Ages. Geochimica et Cosmochimica Acta, 48(1): 207-12. doi:10.1016/0016-7037(84)90364-8.

Allègre, C. (2005). Géologie isotopique. Belin sup. Paris: Belin.

Examples

Pb <- data.frame(
  x = c(18.23247, 18.22936, 18.23102), # Pb206/Pb204
  y = c(15.65199, 15.65216, 15.65097), # Pb207/Pb204
  z = c(38.5167, 38.51516, 38.51601)   # Pb208/Pb204
)

## Default reference values from Albarede & Juteau (1984)
pb_age(
  Pb,
  t0 = 3.8,
  x_star = 18.75, y_star = 15.63, z_star = 38.86,
  mu = 9.66, kappa = 3.90, th232 = 0.049475,
  u238 = 0.155125, u235 = 0.98485, u238_235 = 137.79
)

## Reference values from Albarede et al. (2012)
pb_age(
  Pb,
  t0 = 4.43,
  x_star = 18.75, y_star = 15.63, z_star = 38.83,
  mu = 9.66, kappa = 3.90, th232 = 0.049475,
  u238 = 0.155125, u235 = 0.98485, u238_235 = 137.79
)

Layer-Counted Proxy Records Uncertainties

Description

Represents layer-counted proxy records as sequences of probability distributions on absolute, error-free time axes.

Usage

proxy_ensemble(positions, ...)

## S4 method for signature 'numeric'
proxy_ensemble(
  positions,
  proxy_values,
  proxy_errors,
  proxy_step,
  time_values,
  time_errors,
  calendar,
  from = NULL,
  to = NULL,
  by = NULL,
  n = 30,
  progress = getOption("ananke.progress"),
  verbose = getOption("ananke.verbose")
)

Arguments

positions

A positive numeric vector giving the positions (e.g. depths) at which proxy values and calendar ages were measured. In the case of layers of non-zero thickness, this should be the middle value of the slice. It must be in decreasing order (i.e. in chronological order).
...

Currently not used.
proxy_values

A numeric vector giving the proxy values.
proxy_errors

A numeric vector giving the proxy uncertainties.
proxy_step

A length-one numeric vector specifying the step size (in units of proxy_values) at which proxy records densities are to be estimated.
time_values

A numeric vector giving the calendar ages (in years).
time_errors

A numeric vector giving the calendar age uncertainties (in years).
calendar

An aion::TimeScale object specifying the calendar of time (see aion::calendar()).
from

A length-one numeric vector specifying the starting value of the temporal sequence at which densities are to be estimated (in years).
to

A length-one numeric vector specifying the end value of the temporal sequence at which densities are to be estimated (in cal BP years).
by

A length-one numeric vector specifying the increment of the temporal sequence at which densities are to be estimated (in years).
n

An integer specifying the number of item to choose randomly.
progress

A logical scalar: should a progress bar be displayed?
verbose

A logical scalar: should extra information be reported?

Value

A ProxyRecord object.

Note

This function is currently experimental.

Author(s)

N. Frerebeau

References

Boers, N., Goswami, B. & Ghil, M. (2017). A Complete Representation of Uncertainties in Layer-Counted Paleoclimatic Archives. Climate of the Past, 13(9): 1169-1180. doi:10.5194/cp-13-1169-2017.

See Also

Other proxy tools: proxy_plot

Examples

## Get NGRIP records
data("ngrip2010", package = "folio")
ngrip2010 <- subset(ngrip2010, !is.na(MCE))
ngrip2010 <- ngrip2010[nrow(ngrip2010):1, ] # Sort in chronological order

## Replicate fig. 3d from Boers et al. (2017)
## /!\ This may take a while... /!\
ngrip_record <- proxy_ensemble(
  positions = ngrip2010$depth,
  proxy_values = ngrip2010$delta,
  proxy_errors = 0.01,
  proxy_step = 0.01,
  time_values = ngrip2010$age,
  time_errors = ngrip2010$MCE,
  calendar = b2k(), # /!\
  by = 20,
  n = 30
)

plot(ngrip_record)

Plot Layer-Counted Proxy Records Uncertainties

Description

Plot Layer-Counted Proxy Records Uncertainties

Usage

## S4 method for signature 'ProxyRecord,missing'
plot(
  x,
  calendar = get_calendar(),
  iqr = TRUE,
  xlab = NULL,
  ylab = NULL,
  col = grDevices::hcl.colors(12, "YlOrRd", rev = TRUE),
  col.mean = "black",
  col.iqr = col.mean,
  lty.mean = 1,
  lty.iqr = 3,
  lwd.mean = 2,
  lwd.iqr = lwd.mean,
  ...
)

Arguments

x

A ProxyRecord object.
calendar

An aion::TimeScale object specifying the target calendar (see aion::calendar()). If NULL, rata die are returned.
iqr

A logical scalar: should the mean and IQR be displayed?
xlab, ylab

A character string giving a label for the x and y axis.
col

A list of colors such as that generated by grDevices::hcl.colors().
col.mean, col.iqr

A specification for the line colors. Only used if iqr is TRUE.
lty.mean, lty.iqr

A specification for the line types. Only used if iqr is TRUE.
lwd.mean, lwd.iqr

A specification for the line widths. Only used if iqr is TRUE.
...

Further parameters to be passed to graphics::image().

Value

plot() is called it for its side-effects: it results in a graphic being displayed. Invisibly returns x.

Author(s)

N. Frerebeau

See Also

Other proxy tools: proxy_ensemble()

Examples

## Get NGRIP records
data("ngrip2010", package = "folio")
ngrip2010 <- subset(ngrip2010, !is.na(MCE))
ngrip2010 <- ngrip2010[nrow(ngrip2010):1, ] # Sort in chronological order

## Replicate fig. 3d from Boers et al. (2017)
## /!\ This may take a while... /!\
ngrip_record <- proxy_ensemble(
  positions = ngrip2010$depth,
  proxy_values = ngrip2010$delta,
  proxy_errors = 0.01,
  proxy_step = 0.01,
  time_values = ngrip2010$age,
  time_errors = ngrip2010$MCE,
  calendar = b2k(), # /!\
  by = 20,
  n = 30
)

plot(ngrip_record)

Quantiles of a Density Estimate

Description

Quantiles of a Density Estimate

Usage

## S4 method for signature 'CalibratedAges'
quantile(
  x,
  probs = seq(0, 1, 0.25),
  na.rm = FALSE,
  ...,
  calendar = get_calendar()
)

## S4 method for signature 'ProxyRecord'
quantile(x, probs = seq(0, 1, 0.25), na.rm = FALSE, ...)

Arguments

x

A CalibratedAges object.
probs

A numeric vector of probabilities with values in [0,1][0,1].
na.rm

A logical scalar: should NA values be stripped before the computation proceeds?
...

Currently not used.
calendar

An aion::TimeScale object specifying the target calendar (see aion::calendar()). If NULL, rata die are returned.

Value

A numeric matrix containing the quantiles.

Author(s)

N. Frerebeau

See Also

Other statistics: interval_credible, interval_hdr, mean(), median(), radialplot()

Examples

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)

## Statistics
quantile(cal)
median(cal)
mean(cal)

## Plot
plot(cal, calendar = CE())

## Need to set 'calendar'
abline(v = median(cal, calendar = CE()), lty = 2, col = "blue")
abline(v = mean(cal, calendar = CE()), lty = 2, col = "red")

Radial Plot

Description

Radial Plot

Usage

radialplot(values, errors, ...)

## S4 method for signature 'numeric,numeric'
radialplot(
  values,
  errors,
  log = TRUE,
  centrality = c("weighted.mean", "mean", "median"),
  bar = FALSE,
  grid = TRUE,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  ...
)

## S4 method for signature 'CalibratedAges,missing'
radialplot(
  values,
  log = TRUE,
  centrality = c("weighted.mean", "mean", "median"),
  bar = FALSE,
  grid = TRUE,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  ...
)

Arguments

values

A numeric vector giving the BP ages or F14C values to be calibrated (conventional ages) or a CalibratedAges object.
errors

A numeric vector giving the errors associated to the values to be calibrated.
...

Further graphical parameters to be passed to graphics::points().
log

A logical scalar: should the z-axis be displayed in logarithmic scale?
centrality

A character string specifying a measure of centrality, used for centering the plot. It must be one of "weighted.mean" (the default), "mean" or "median". Any unambiguous substring can be given.
bar

A logical scalar: should a bar showing the 2-sigma range around the central value be displayed?
grid

A logical scalar: should a grid (originating at [0,0][0,0] and stretching to the z-scale) be displayed?
main

A character string giving a main title for the plot.
sub

A character string giving a subtitle for the plot.
ann

A logical scalar: should the default annotation (title and x and y labels) appear on the plot?

Value

radialplot() is called it for its side-effects: it results in a graphic being displayed.

Author(s)

N. Frerebeau

References

Galbraith, Rex F. (1988). Graphical Display of Estimates Having Differing Standard Errors. Technometrics, 30(3): 271-281. doi:10.1080/00401706.1988.10488400.

Galbraith, Rex F. (1990). The Radial Plot: Graphical Assessment of Spread in Ages. International Journal of Radiation Applications and Instrumentation. Part D. Nuclear Tracks and Radiation Measurements, 17(3): 207-214. doi:10.1016/1359-0189(90)90036-W.

Galbraith, Rex F. (1994). Some Applications of Radial Plots. Journal of the American Statistical Association, 89(428): 1232-1242. doi:10.1080/01621459.1994.10476864.

See Also

Other statistics: interval_credible, interval_hdr, mean(), median(), quantile()

Examples

## Data from Bosch et al. 2015
data("ksarakil")

## Radialplot
radialplot(ksarakil$date, ksarakil$error, pch = 16)

## Linear z-scale
radialplot(ksarakil$date, ksarakil$error, log = FALSE, pch = 16)

Plot a Radiocarbon Event Count Ensemble

Description

Plot a Radiocarbon Event Count Ensemble

Usage

## S4 method for signature 'RECE,missing'
plot(x, calendar = get_calendar(), ...)

Arguments

x

An RECE object.
calendar

An aion::TimeScale object specifying the target calendar (see aion::calendar()). If NULL, rata die are returned.
...

Further parameters to be passed to graphics::image().

Value

plot() is called it for its side-effects: it results in a graphic being displayed (invisibly returns x).

Author(s)

N. Frerebeau

References

Carleton, W. C. (2021). Evaluating Bayesian Radiocarbon‐dated Event Count (REC) Models for the Study of Long‐term Human and Environmental Processes. Journal of Quaternary Science, 36(1): 110‑23. doi:10.1002/jqs.3256.

See Also

Other radiocarbon tools: F14C, c14_calibrate(), c14_combine(), c14_count(), c14_curve(), c14_plot, c14_sample(), c14_spd(), c14_uncalibrate(), ridgelines()

Examples

## Radiocarbon data from Bosch et al. 2015
data("ksarakil")

## Calibrate
cal <- c14_calibrate(
  values = ksarakil$date,
  errors = ksarakil$error,
  names = ksarakil$code,
  curves = "marine13",
  reservoir_offsets = 53,
  reservoir_errors = 43,
  from = 50000, to = 0
)

## RECE
tmp <- c14_count(cal, n = 500)
plot(tmp, col = grDevices::hcl.colors(12, "Viridis", rev = TRUE))

Ridgeline Plot of Calibrated Radiocarbon Ages

Description

Ridgeline Plot of Calibrated Radiocarbon Ages

Usage

ridgelines(x, ...)

## S4 method for signature 'CalibratedAges'
ridgelines(
  x,
  calendar = get_calendar(),
  interval = c("hdr", "credible"),
  level = 0.954,
  fixed = TRUE,
  decreasing = FALSE,
  col = "grey",
  ...
)

Arguments

x

A CalibratedAges or CalibratedSPD object.
...

Further parameters to be passed to aion::plot().
calendar

An aion::TimeScale object specifying the target calendar (see aion::calendar()). If NULL, rata die are returned.
interval

A character string specifying the intervals to be drawn. It must be one of "hrd" (the default) or "credible". Any unambiguous substring can be given.
level

A length-one numeric vector giving the confidence level. Only used if interval is TRUE.
fixed

A logical scalar: should a fixed y scale be used? If TRUE (the default), ages are equally spaced along the y axis and arranged in chronological order. If FALSE, age positions are used (see c14_calibrate()).
decreasing

A logical scalar: should the sort order be decreasing?
col

A specification for the plotting colors.

Value

ridgelines() is called it for its side-effects: it results in a graphic being displayed (invisibly returns x).

Author(s)

N. Frerebeau

See Also

Other radiocarbon tools: F14C, c14_calibrate(), c14_combine(), c14_count(), c14_curve(), c14_plot, c14_sample(), c14_spd(), c14_uncalibrate(), rec_plot

Examples

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)

## Ridgelines plot
ridgelines(cal, panel.first = graphics::grid())

## Change colors
ridgelines(cal, col = c("red", "blue"))

Extract or Replace Parts of an Object

Description

Operators acting on objects to extract or replace parts.

Usage

## S4 method for signature 'CalibratedAges'
x[i, j, k, drop = FALSE]

Arguments

x

An object from which to extract element(s) or in which to replace element(s).
i, j, k

Indices specifying elements to extract or replace.
drop

A logical scalar: should the result be coerced to the lowest possible dimension? This only works for extracting elements, not for the replacement.

Value

A subsetted object.

Author(s)

N. Frerebeau

See Also

Other mutators: as.data.frame, as.list(), labels(), mutators

Object Summaries

Description

Object Summaries

Usage

## S4 method for signature 'CalibratedAges'
summary(object, ..., digits = NULL, calendar = get_calendar())

Arguments

object

A CalibratedAges object.
...

Currently not used.
digits

An integer (or NULL) used for number formatting (see base::format()).
calendar

An aion::TimeScale object specifying the target calendar (see aion::calendar()). If NULL, rata die are returned.

Value

An object of class table.

Author(s)

N. Frerebeau

See Also

Other summary: describe

Examples

## Calibrate multiple dates
cal <- c14_calibrate(
  values = c(5000, 4500),
  errors = c(45, 35),
  names = c("X", "Y")
)

## Summary
summary(cal, calendar = CE())