Package 'ananke'

Title: Quantitative Chronology in Archaeology
Description: A toolbox for quantitative chronology in archaeology. This package provides functions for simple radiocarbon calibration and chronological analysis.
Authors: Nicolas Frerebeau [aut, cre] (<https://orcid.org/0000-0001-5759-4944>, Université Bordeaux Montaigne), Université Bordeaux Montaigne [fnd], CNRS [fnd]
Maintainer: Nicolas Frerebeau <[email protected]>
License: GPL (>= 3)
Version: 0.0.1.9000
Built: 2024-10-03 05:59:55 UTC
Source: https://github.com/tesselle/ananke

Help Index


14C Calibration

Description

Calibrates radiocarbon dates.

Usage

c14_calibrate(values, errors, ...)

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

Arguments

values

A numeric vector giving the BP ages or F14C values to be calibrated.

errors

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

...

Currently not used.

names

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

curves

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

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.

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_curve(), c14_ensemble(), c14_plot, c14_spd(), c14_uncalibrate(), c14_validate(), rec_plot

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, calendar = BP(), panel.first = graphics::grid())
plot(cal, interval = FALSE)
plot(cal[, 1, ], col.interval = "red")

plot(cal, density = FALSE, level = 0.68, lwd = 5)
plot(cal, density = FALSE, level = 0.95, lwd = 5)


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

Combine 14C

Description

Combines radiocarbon dates.

Usage

c14_combine(ages, errors, ...)

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

Arguments

ages

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_curve(), c14_ensemble(), c14_plot, c14_spd(), c14_uncalibrate(), c14_validate(), rec_plot

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(
  ages = polach1972$ages,
  errors = polach1972$errors,
  groups = polach1972$samples
)

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
bomb04nh1 Hua and Barbetti 2004
bomb04nh2 Hua and Barbetti 2004
bomb04nh3 Hua and Barbetti 2004
bomb04sh Hua and Barbetti 2004
bomb13nh1 Hua, Berbetti and Rakowski 2013
bomb13nh2 Hua, Berbetti and Rakowski 2013
bomb13nh3 Hua, Berbetti and Rakowski 2013
bomb13sh12 Hua, Berbetti and Rakowski 2013
bomb13sh3 Hua, Berbetti and Rakowski 2013
bomb21nh1 Hua et al. 2022
bomb21nh2 Hua et al. 2022
bomb21nh3 Hua et al. 2022
bomb21sh12 Hua et al. 2022
bomb21sh3 Hua et al. 2022
cariaco04 Hughen et al. 2004
intcal98 Stuiver et al. 1998
intcal04 Reimer et al. 2004
intcal09 Reimer et al. 2009
intcal13 Reimer et al. 2013
intcal20 Reimer et al. 2020
kueppers04 Kueppers et al. 2004
marine98 Stuiver, Reimer and Braziunas 1998
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_ensemble(), c14_plot, c14_spd(), c14_uncalibrate(), c14_validate(), rec_plot

Examples

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

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

Radiocarbon Event Count

Description

Radiocarbon Event Count

Usage

c14_ensemble(object, ...)

## S4 method for signature 'CalibratedAges'
c14_ensemble(
  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.

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_spd(), c14_uncalibrate(), c14_validate(), rec_plot


Plot Calibrated Radiocarbon Ages

Description

Plot Calibrated Radiocarbon Ages

Usage

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

## S4 method for signature 'CalibratedSPD,missing'
plot(
  x,
  calendar = getOption("ananke.calendar"),
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = FALSE,
  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.

density

A logical scalar: should density be drawn?

interval

A logical scalar: should highest density region be drawn?

level

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

sort

A logical scalar: should the data be sorted?

decreasing

A logical scalar: should the sort order be decreasing? Only used if sort is TRUE.

main

A character string giving a main title for the plot.

sub

A character string giving a subtitle for 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?

ann

A logical scalar: should the default annotation (title and x and y labels) appear on 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.

col.density, col.interval

A specification for the plotting colors.

...

Other graphical parameters may also be passed as arguments to this function.

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_curve(), c14_ensemble(), c14_spd(), c14_uncalibrate(), c14_validate(), rec_plot

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, calendar = BP(), panel.first = graphics::grid())
plot(cal, interval = FALSE)
plot(cal[, 1, ], col.interval = "red")

plot(cal, density = FALSE, level = 0.68, lwd = 5)
plot(cal, density = FALSE, level = 0.95, lwd = 5)


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

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.

Author(s)

N. Frerebeau

See Also

Other radiocarbon tools: F14C, c14_calibrate(), c14_combine(), c14_curve(), c14_ensemble(), c14_plot, c14_uncalibrate(), c14_validate(), rec_plot

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, flip = TRUE)

## 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, ...)

Arguments

object

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

...

Currently not used.

curves

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

Author(s)

N. Frerebeau

See Also

Other radiocarbon tools: F14C, c14_calibrate(), c14_combine(), c14_curve(), c14_ensemble(), c14_plot, c14_spd(), c14_validate(), rec_plot

Examples

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

## Uncalibrate
c14_uncalibrate(cal)

## End(Not run)

Check Calibrated Radiocarbon Dates

Description

Check Calibrated Radiocarbon Dates

Usage

c14_validate(object, ...)

## S4 method for signature 'CalibratedAges'
c14_validate(object)

Arguments

object

A CalibratedAges object.

...

Currently not used.

Value

c14_validate() is called it for its side-effects: it prints warning messages if calibrated agea are (partially) out of calibration range. Invisibly returns x.

Author(s)

N. Frerebeau

See Also

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

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, calendar = BP(), panel.first = graphics::grid())
plot(cal, interval = FALSE)
plot(cal[, 1, ], col.interval = "red")

plot(cal, density = FALSE, level = 0.68, lwd = 5)
plot(cal, density = FALSE, level = 0.95, lwd = 5)


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

Coerce to a Data Frame

Description

Coerce to a Data Frame

Usage

## S4 method for signature 'CalibratedAges'
as.data.frame(x, ..., calendar = getOption("ananke.calendar"))

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

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

Arguments

x

An object.

...

Further parameters to be passed to data.frame().

calendar

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

Value

A data.frame with an extra time column.

Author(s)

N. Frerebeau

See Also

Other mutators: labels(), mutators, subset()

Examples

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

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

Data Description

Description

Data Description

Usage

## S4 method for signature 'CalibratedAges'
describe(x, calendar = getOption("ananke.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.

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

BP14C_to_F14C(ages, errors, ...)

F14C_to_BP14C(values, errors, ...)

## S4 method for signature 'numeric,numeric'
BP14C_to_F14C(ages, errors, lambda = 8033)

## S4 method for signature 'numeric,numeric'
F14C_to_BP14C(values, errors, lambda = 8033, asymmetric = FALSE)

Arguments

ages

A numeric vector giving the radiocarbon ages.

errors

A numeric vector giving the standard deviations.

...

Currently not used.

values

A numeric vector giving the F14C values.

lambda

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?

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.

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_curve(), c14_ensemble(), c14_plot, c14_spd(), c14_uncalibrate(), c14_validate(), rec_plot

Examples

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

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

Highest Density Regions

Description

Highest Density Regions

Usage

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

Arguments

x

A CalibratedAges object.

level

A length-one numeric vector giving the confidence level.

calendar

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

...

Currently not used.

Value

Returns a list of numeric matrix.

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: mean(), median(), quantile()

Examples

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

## HDR
interval_hdr(cal, level = 0.683)
interval_hdr(cal, level = 0.954)
interval_hdr(cal, level = 0.997)

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: data.frame, mutators, subset()


Mean

Description

Mean

Usage

## S4 method for signature 'CalibratedAges'
mean(x, na.rm = FALSE, ..., calendar = getOption("ananke.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: hdr, median(), quantile()

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 = getOption("ananke.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: hdr, mean(), quantile()

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: data.frame, 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)
)

## 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)
)

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).

Value

A four columns data.frame:

age Geological model age (in Ma)
mu 238U/204Pb ratio
kappa 232Th/238U ratio
f

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
)

## Reference values from Albarede & Juteau (1984)
pb_age(Pb)

## 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(depth, ...)

## S4 method for signature 'numeric'
proxy_ensemble(
  depth,
  proxy,
  proxy_error,
  step,
  time,
  time_error,
  calendar,
  from = NULL,
  to = NULL,
  by = NULL,
  n = 30,
  progress = getOption("ananke.progress"),
  verbose = getOption("ananke.verbose")
)

Arguments

depth

A positive numeric vector giving the depth at which proxy values and calendar ages were measured. It must be in decreasing order (i.e. in chronological order).

...

Currently not used.

proxy

A numeric vector giving the proxy values.

proxy_error

A numeric vector giving the proxy uncertainties.

step

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

time

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

time_error

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

calendar

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

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.

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

## Not run: 
## 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(
  depth = ngrip2010$depth,
  proxy = ngrip2010$delta,
  proxy_error = 0.01,
  step = 0.001,
  time = ngrip2010$age,
  time_error = ngrip2010$MCE,
  calendar = b2k(), # /!\
  by = 20,
  n = 30
)

plot(ngrip_record)

## End(Not run)

Plot Layer-Counted Proxy Records Uncertainties

Description

Plot Layer-Counted Proxy Records Uncertainties

Usage

## S4 method for signature 'ProxyRecord,missing'
plot(
  x,
  calendar = getOption("ananke.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

## Not run: 
## 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(
  depth = ngrip2010$depth,
  proxy = ngrip2010$delta,
  proxy_error = 0.01,
  step = 0.001,
  time = ngrip2010$age,
  time_error = ngrip2010$MCE,
  calendar = b2k(), # /!\
  by = 20,
  n = 30
)

plot(ngrip_record)

## End(Not run)

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 = getOption("ananke.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: hdr, mean(), median()

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")

Plot a Radiocarbon Event Count Ensemble

Description

Plot a Radiocarbon Event Count Ensemble

Usage

## S4 method for signature 'RECE,missing'
plot(x, calendar = getOption("ananke.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

image() 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_curve(), c14_ensemble(), c14_plot, c14_spd(), c14_uncalibrate(), c14_validate()


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: data.frame, labels(), mutators