calibrate: Calibrate radiocarbon dates

In rcarbon: Calibration and Analysis of Radiocarbon Dates

Calibrate radiocarbon dates

Description

Function for calibrating radiocarbon dates or uncalibrated SPDs.

Function for calibrating a SPD generated by summing uncalibrated dates.

Usage

calibrate(x, ...)

## Default S3 method:
calibrate(
  x,
  errors,
  ids = NA,
  dateDetails = NA,
  calCurves = "intcal20",
  resOffsets = 0,
  resErrors = 0,
  timeRange = c(55000, 0),
  normalised = TRUE,
  F14C = FALSE,
  calMatrix = FALSE,
  eps = 1e-05,
  ncores = 1,
  verbose = TRUE,
  ...
)

## S3 method for class 'UncalGrid'
calibrate(
  x,
  errors = 0,
  calCurves = "intcal20",
  timeRange = c(55000, 0),
  eps = 1e-05,
  type = "fast",
  datenormalised = FALSE,
  spdnormalised = FALSE,
  verbose = TRUE,
  ...
)

Arguments

x	A vector of uncalibrated radiocarbon ages or a UncalGrid class object.
...	ignored
errors	A vector of standard deviations corresponding to each estimated radiocarbon age.
ids	An optional vector of IDs for each date.
dateDetails	An optional vector of details for each date which will be returned in the output metadata.
calCurves	Either a character string naming a calibration curve already provided with the rcarbon package (currently 'intcal20','intcal13','intcal13nhpine16','shcal20','shcal13','shcal13shkauri16',”marine13','marine20' and 'normal'(i.e. no calibration) are possible; default is 'intcal20') or a custom calibration curve as three-column matrix or data.frame (calibrated year BP, uncalibrated age bp, standard deviation). Different existing curves can be specified per dated sample, but only one custom curve can be provided for all dates.
resOffsets	A vector of offset values for any marine reservoir effect (default is no offset).
resErrors	A vector of offset value errors for any marine reservoir effect (default is no offset).
timeRange	Earliest and latest data to calibrate for, in calendar years. Posterior probabilities beyond this range will be excluded (the default is sensible in most cases).
normalised	A logical variable indicating whether the calibration should be normalised or not. Default is TRUE.
F14C	A logical variable indicating whether calibration should be carried out in F14C space or not. Default is FALSE.
calMatrix	a logical variable indicating whether the age grid should be limited to probabilities higher than eps
eps	Cut-off value for density calculation. Default is 1e-5.
ncores	Number of cores/workers used for parallel execution. Default is 1 (>1 requires doSnow package).
verbose	A logical variable indicating whether extra information on progress should be reported. Default is TRUE.
type	Currently, two options are available. With "fast", a look-up is conducted for each calendar year that picks up the amplitude of the nearest CRA age. With "full", each CRA is calibrated individually and then summed (much slower).
datenormalised	Controls for calibrated dates with probability mass outside the timerange of analysis. If set to TRUE the total probability mass within the time-span of analysis is normalised to sum to unity. Should be set to FALSE when the parameter normalised in calibrate is set to FALSE. Default is FALSE.
spdnormalised	A logical variable indicating whether the total probability mass of the SPD is normalised to sum to unity.

Details

This function computes one or more calibrated radiocarbon ages using the method described in Bronk Ramsey 2008 (see also Parnell 2017). It is possible to specify different calibration curves or reservoir offsets individually for each date, and control whether the resulting calibrated distribution is normalised to 1 under-the-curve or not. Calculations can also be executed in parallel to reduce computing time. The function was modified from the BchronCalibrate function in the Bchron package developed by A.Parnell (see references below).

Value

An object of class CalDates with the following elements:

• metadata A data.frame containing relevant information regarding each radiocarbon date and the parameter used in the calibration process.

• grids A list of calGrid class objects, containing the posterior probabilities for each calendar year. The most memory-efficient way to store calibrated dates, as only years with non-zero probability are stored, but aggregation methods such as spd() may then take longer to extract and combine multiple dates. NA when the parameter calMatrix is set to TRUE.

• calMatrix A matrix of probability values, one row per calendar year in timeRange and one column per date. By storing all possible years, not just those with non-zero probability, this approach takes more memory, but speeds up spd() and is suggested whenever the latter is to be used. NA when the parameter calMatrix is set to FALSE.

References

Bronk Ramsey, C. 2008. Radiocarbon dating: revolutions in understanding, Archaeometry 50.2: 249-75. DOI: https://doi.org/10.1111/j.1475-4754.2008.00394.x
Parnell, A. 2017. Bchron: Radiocarbon Dating, Age-Depth Modelling, Relative Sea Level Rate Estimation, and Non-Parametric Phase Modelling, R package: https://CRAN.R-project.org/package=Bchron

Examples

x1 <- calibrate(x=4000, errors=30)
plot(x1)
summary(x1)
# Example with a Marine Date, using a DeltaR of 300 and a DeltaR error of 30
x2 <- calibrate(x=4000, errors=30, calCurves='marine20', resOffsets=300, resErrors=30)
plot(x2)

rcarbon documentation built on Aug. 24, 2023, 5:11 p.m.