draw.dates {rintcal}

add calibrated distributions to a plot.

Description

Add individual or multiple calibrated dates to a plot.

Usage

draw.dates(
  age,
  error,
  depth,
  cc = 1,
  postbomb = FALSE,
  reservoir = c(),
  normal = TRUE,
  t.a = 3,
  t.b = 4,
  prob = 0.95,
  threshold = 0.001,
  BCAD = FALSE,
  draw.hpd = TRUE,
  hpd.lwd = 2,
  hpd.col = rgb(0, 0, 1, 0.7),
  cal.hpd.col = rgb(0, 0.5, 0.5, 0.35),
  mirror = TRUE,
  up = FALSE,
  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 = 1,
  normalise = TRUE,
  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). Can also be their relative positions if no depths are available.

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.

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 a 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.lwd

Width of the line of the hpd ranges

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

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 up or down, depending on the direction of the axis.

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

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 <- 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))
  draw.dates(y, er, y, d.lab="Radiocarbon age (BP)")
  draw.ccurve(add=TRUE, cc1.col=rgb(0,.5,0,.5))