calibrate: Calibrate radiocarbon dates

Description Usage Arguments Details Value References Examples

Description

Function for calibrating radiocarbon dates or uncalibrated SPDs.

Function for calibrating a SPD generated by summing uncalibrated dates.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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:

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

1
2
3
4
5
6
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 Jan. 13, 2021, 7:09 p.m.