calibrate: Plot individual calibrated dates.

In Maarten14C/IntCal: Radiocarbon Calibration Curves

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,
  reservoir = 0,
  prob = 0.95,
  BCAD = FALSE,
  ka = FALSE,
  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.2),
  dist.fill = rgb(0, 0, 0, 0.2),
  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,
  threshold = c(),
  edge = TRUE,
  normal = TRUE,
  t.a = 3,
  t.b = 4,
  rounded = 1,
  extend.range = 0.05,
  legend.cex = 0.8,
  legend1.loc = "topleft",
  legend2.loc = "topright",
  mgp = c(2, 1, 0),
  mar = c(3, 3, 1, 1),
  xaxs = "i",
  yaxs = "i",
  bty = "l",
  cc.dir = NULL,
  ...
)

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.
reservoir	Reservoir age, or reservoir age and age offset.
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.
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.col=rgb(0,.5,0,0.7).
cc.fill	Colour of the inner part of the calibration curve. Defaults to semi-transparent dark green; cc.col=rgb(0,.5,0,0.7).
date.col	Colour of the "dot-bar" plot of the C14 date. Defaults to date.col="red".
dist.col	Colour of the outer lines of the distributions. Defaults to semi-transparent grey, dist.col=rgb(0,0,0,0.2).
dist.fill	Colour of the inner part of the distributions. Defaults to semi-transparent grey, dist.col=rgb(0,0,0,0.2).
hpd.fill	Colour of the highest posterior density. Defaults to semi-transparent grey, dist.col=rgb(0,0,0,0.3).
dist.height	Maximum height of the C14 and calibrated distributions (as proportion of the invisible secondary axes). Defaults to 0.3.
dist.float	The probability distributions float a bit above the axes by default. Can be set to distinct heights of the axes, e.g.: dist.float=c(0.05, 0.1), or to dist.float=0.
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.
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 a of the t distribution (defaults to 4).
rounded	Rounding of the percentages of the reported hpd ranges. Defaults to 1 decimal.
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.
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 xaxs="i" which does not extend the limits.
yaxs	Whether or not to extend the limits of the vertical axis. Defaults to yaxs="i" which does not extend the limits.
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.dir="curves".
...	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))

Maarten14C/IntCal documentation built on Oct. 11, 2023, 1:25 a.m.