draw.dates: add calibrated distributions to a plot.

In rice: Radiocarbon Equations

add calibrated distributions to a plot.

Description

Add individual or multiple calibrated dates to a plot.

Usage

draw.dates(
  age,
  error,
  depth = c(),
  cc = 1,
  postbomb = FALSE,
  deltaR = 0,
  deltaSTD = 0,
  thiscurve = c(),
  oncurve = FALSE,
  realm = "C",
  reservoir = c(),
  normal = TRUE,
  t.a = 3,
  t.b = 4,
  prob = 0.95,
  threshold = 0.001,
  BCAD = FALSE,
  draw.hpd = TRUE,
  hpd.border = NA,
  hpd.col = rgb(0, 0, 1, 0.7),
  cal.hpd.col = rgb(0, 0.5, 0.5, 0.35),
  rounded = 0.1,
  every = 1,
  mirror = TRUE,
  up = TRUE,
  draw.base = TRUE,
  col = rgb(0, 0, 1, 0.3),
  border = rgb(0, 0, 1, 0.5),
  cal.col = rgb(0, 0.5, 0.5, 0.35),
  cal.border = rgb(0, 0.5, 0.5, 0.35),
  add = FALSE,
  ka = FALSE,
  rotate.axes = FALSE,
  ex = 0.8,
  normalise = TRUE,
  cc.col = rgb(0, 0.5, 0, 0.5),
  cc.border = rgb(0, 0.5, 0, 0.5),
  cc.resample = 5,
  age.lab = c(),
  age.lim = c(),
  age.rev = FALSE,
  d.lab = c(),
  d.lim = c(),
  d.rev = TRUE,
  labels = c(),
  label.x = 1,
  label.y = c(),
  label.cex = 0.8,
  label.col = border,
  label.offset = c(0, 0),
  label.adj = c(1, 0),
  label.rot = 0,
  cc.dir = NULL,
  dist.res = 100,
  ...
)

Arguments

age	Mean of the uncalibrated C-14 age (or multiple ages).
error	Error of the uncalibrated C-14 age (or ages).
depth	Depth(s) of the date(s). Defaults to their relative positions if no depths are provided.
cc	Calibration curve for C-14 dates (1, 2, 3, or 4, or, e.g., "IntCal20", "Marine20", "SHCal20", "nh1", "sh3", or "mixed"). If there are multiple dates but all use the same calibration curve, one value can be provided.
postbomb	Whether or not this is a postbomb age. Defaults to FALSE.
deltaR	Age offset (e.g. for marine samples). Can also be provided as option 'reservoir'.
deltaSTD	Uncertainty of the age offset (1 standard deviation). Can also be provided within option 'reservoir'.
thiscurve	As an alternative to providing cc and/or postbomb, the data of a specific curve can be provided (3 columns: cal BP, C14 age, error). Defaults to c().
oncurve	Whether or not to plot the calibration curve and then plot the dates onto this curve. Defaults to FALSE.
realm	If oncurve is used, by default the calibration curve is plotted in the C14 age realm. Alternatively, it can be provided as realm="F14C" or realm="pMC"
reservoir	Reservoir age, or reservoir age and age offset.
normal	Use the normal distribution to calibrate dates (default TRUE). The alternative is to use the t model (Christen and Perez 2009).
t.a	Value a of the t distribution (defaults to 3).
t.b	Value b of the t distribution (defaults to 4).
prob	Probability confidence intervals (between 0 and 1).
threshold	Report only values above a threshold. Defaults to threshold=0.001.
BCAD	Use BC/AD or cal BP scale (default cal BP).
draw.hpd	Whether or not to draw the hpd ranges as a line
hpd.border	Colour of the border of the hpd intervals. Not drawn by default.
hpd.col	Colour of the hpd rectangle for all dates or radiocarbon dates
cal.hpd.col	Colour of the hpd rectangle for cal BP dates
rounded	Rounding for probabilities of reported hpd ranges. Defaults to 1 decimal.
every	Yearly precision of hpds (defaults to every=1).
mirror	Plot distributions mirrored, a bit like a swan. Confuses some people but looks nice to the author so is the default.
up	If mirror is set to FALSE, the distribution can be plotted facing upwards or downwards.
draw.base	By default, the base of the calibrated distributions is plotted. This can be avoided by supplying draw.base=FALSE as an option.
col	Colour of the inside of the distribution
border	Colour of the border of the distribution
cal.col	Colour of the inside of distribution of non-radiocarbon dates that didn't need calibration
cal.border	Colour of the border of the distribution of non-radiocarbon dates that didn't need calibration
add	Whether or not to add the dates to an existing plot. If set to FALSE (default), a plot will be set up.
ka	Whether or not to plot ages as thousands of years. Defaults to ka=FALSE.
rotate.axes	By default, the calendar age axis is plotted on the horizontal axis, and depth/position on the vertical one. Use rotate.axes=TRUE to rotate the axes.
ex	Exaggeration of the height of the distribution, defaults to ex=1.
normalise	If TRUE, the age distributions are normalised by plotting each distribution with the same total area. Precise dates will therefore peak higher than less precise dates (default). If normalise=FALSE, the peak of each date will be drawn at the same height.
cc.col	Colour of the calibration curve. Default semi-transparent darkgreen.
cc.border	Colour of the edges of the calibration curve. Default semi-transparent darkgreen.
cc.resample	The IntCal20 curves have different densities (every year between 0 and 5 kcal BP, then every 5 yr up to 15 kcal BP, then every 10 yr up to 25 kcal BP, and then every 20 yr up to 55 kcal BP). If calibrated ages span these density ranges, their drawn heights can differ, as can their total areas (which should ideally all sum to the same size). To account for this, resample to a constant time-span, using, e.g., cc.resample=5 for 5-yr timespans.
age.lab	Title of the calendar axis (if present)
age.lim	Limits of the calendar axis (if present)
age.rev	Reverse the age axis. Defaults to TRUE
d.lab	Title of the vertical axis (if present)
d.lim	Limits of the vertical axis (if present)
d.rev	Reverse the y-axis. Defaults to TRUE
labels	Add labels to the dates. Empty by default.
label.x	Horizontal position of the date labels. By default draws them before the youngest age (1), but can also draw them after the oldest age (2), or above its mean (3).
label.y	Vertical positions of the depths/labels. Defaults to 0 (or 1 if label.x is 3 or 4).
label.cex	Size of labels.
label.col	Colour of the labels. Defaults to the colour given to the borders of the dates.
label.offset	Offsets of the positions of the depths/labels, giving the x and y offsets. Defaults to c(0,0).
label.adj	Justification of the labels. Follows R's adj option: A value of "0" produces left-justified text, "0.5" (the default) centered text and "1" right-justified text.
label.rot	Rotation of the label. 0 by default (horizontal).
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".
dist.res	Resolution of the distribution polygons. Defaults to dist.res=100.
...	Additional plotting options

Value

A plot of the (calibrated) dates

Examples

  plot(0, xlim=c(500,0), ylim=c(0, 2))
  draw.dates(130, 20, depth=1) 
  x <- sort(runif(10, 1000, 10000)) # draw 10 random calendar ages
  cc <- rintcal::ccurve() # get the calibration curve
  y <- approx(cc[,1], cc[,2], x)$y # find the IntCal 14C ages
  er <- .01 * y
  draw.dates(y, er, 1:length(x))
  # or draw on the calibration curve
  draw.dates(y, er, y, d.lab="Radiocarbon age (BP)")
  draw.ccurve(add=TRUE, cc1.col=rgb(0,.5,0,.5))

rice documentation built on April 11, 2025, 5:53 p.m.