Bchron: Radiocarbon dating, age-depth modelling, relative sea level rate estimation, and non-parametric phase modelling

Description

This package enables quick calibration of radiocarbon dates under various calibration curves (including user generated ones); Age-depth modelling as per the algorithm of Haslett and Parnell (2008); Relative sea level rate estimation incorporating time uncertainty in polynomial regression models; and non-parametric phase modelling via Gaussian mixtures as a means to determine the activity of a site (and as an alternative to the Oxcal function SUM)

Bchron functions

The most important functions are BchronCalibrate to calibrate radiocarbon (and non-radiocarbon) dates, Bchronology for the age-depth model of Haslett and Parnell (2008), BchronRSL to get rate estimates for relative sea level data, BchronDensity and BchronDensityFast for non-parametric phase modelling of age data. See the help files for these functions for examples. See the vignette for more complete documentation

Author(s)

Maintainer: Andrew Parnell Andrew.Parnell1@ucd.ie

Other contributors:

• Nathan McJames [contributor]

• Bruna Wundervald [contributor]

• Keefe Murphy [contributor]

• Mateus Maia [contributor]

• Amin Shoari Nejad [contributor]

• Yong Chen Goh [contributor]

See Also

Useful links:

• https://andrewcparnell.github.io/Bchron/

• Report bugs at https://github.com/andrewcparnell/Bchron/issues

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Value

a connection objects as described in magrittr::%>%

Fast radiocarbon calibration

Description

A fast function for calibrating large numbers of radiocarbon dates involving multiple calibration curves

Usage

BchronCalibrate(
  ages,
  ageSds,
  calCurves = rep("intcal20", length(ages)),
  ids = NULL,
  positions = NULL,
  pathToCalCurves = system.file("data", package = "Bchron"),
  allowOutside = FALSE,
  eps = 1e-05,
  dfs = rep(100, length(ages))
)

Arguments

Details

This function provides a direct numerical integration strategy for computing calibrated radiocarbon ages. The steps for each 14C age are approximately as follows: 1) Create a grid of ages covering the range of the calibration curve 2) Calculate the probability of each age according to the 14C age, the standard deviation supplied and the calibration curve 3) Normalise the probabilities so that they sum to 1 4) Remove any probabilities that are less than the value given for eps Multiple calibration curves can be specified so that each 14C age can have a different curve. For ages that are not 14C, use the 'normal' calibration curve which treats the ages as normally distributed with given standard deviation

Value

A list of lists where each element corresponds to a single age. Each element contains:

ages

The original age supplied

ageSds

The original age standard deviation supplied

positions

The position of the age (usually the depth)

calCurves

The calibration curve used for that age

ageGrid

A grid of age values over which the density was created

densities

A vector of probability values indicating the probability value for each element in ageGrid

ageLab

The label given to the age variable

positionLab

The label given to the position variable

See Also

Bchronology, BchronRSL, BchronDensity, BchronDensityFast, createCalCurve

Examples

# Calibrate a single age
ages1 <- BchronCalibrate(
  ages = 11553,
  ageSds = 230,
  calCurves = "intcal20",
  ids = "Date-1"
)
summary(ages1)
plot(ages1)

# Or plot with Calibration curve
plot(ages1, includeCal = TRUE)

# Calibrate multiple ages with different calibration curves
ages2 <- BchronCalibrate(
  ages = c(3445, 11553, 7456),
  ageSds = c(50, 230, 110),
  calCurves = c("intcal20", "intcal20", "shcal20")
)
summary(ages2)
plot(ages2)

# Calibrate multiple ages with multiple calibration curves and including depth
ages3 <- BchronCalibrate(
  ages = c(3445, 11553),
  ageSds = c(50, 230),
  positions = c(100, 150),
  calCurves = c("intcal20", "normal")
)
summary(ages3)
plot(ages3, withPositions = TRUE)

Check data for input into BchronCalibrate or Bchronology

Description

Function to be used for checking the data formats in BchronCalibrate and Bchronology. Mostly to be used internally to avoid Bchron running into problems with bad data specifications, but might also be useful for

Usage

BchronCheck(
  ages,
  ageSds,
  positions = NULL,
  pathToCalCurves = NULL,
  calCurves = NULL,
  positionThicknesses = NULL,
  ids = NULL,
  outlierProbs = NULL,
  predictPositions = NULL,
  artificialThickness = NULL,
  allowOutside = NULL,
  iterations = NULL,
  thetaStart = NULL,
  burn = NULL,
  thin = NULL,
  extractDate = NULL,
  maxExtrap = NULL,
  thetaMhSd = NULL,
  muMhSd = NULL,
  psiMhSd = NULL,
  ageScaleVal = NULL,
  positionEps = NULL,
  positionNormalise = NULL,
  eps = NULL,
  dfs = NULL,
  type = c("BchronCalibrate", "Bchronology")
)

Arguments

Value

This function returns nothing other than a message.

Examples

data(Glendalough)

# Check the Glendalough data are in the right format
with(
  Glendalough,
  BchronCheck(ages,
    ageSds,
    position,
    pathToCalCurves = system.file("data", package = "Bchron"),
    calCurves,
    type = "BchronCalibrate"
  )
)

Non-parametric phase model

Description

This function runs a non-parametric phase model on 14C and non-14C ages via Gaussian Mixture density estimation

Usage

BchronDensity(
  ages,
  ageSds,
  calCurves,
  pathToCalCurves = system.file("data", package = "Bchron"),
  dfs = rep(100, length(ages)),
  numMix = 50,
  iterations = 10000,
  burn = 2000,
  thin = 8,
  updateAges = FALSE,
  store_density = TRUE
)

Arguments

Details

This model places a Gaussian mixture prior distribution on the calibrated ages and so estimates the density of the overall set of radiocarbon ages. It is designed to be a probabilistic version of the Oxcal SUM command which takes calibrated ages and sums the probability distributions with the aim of estimating activity through age as a proxy.

Value

An object of class BchronDensityRun with the following elements:

theta

The posterior samples of the restricted ages

p

Posterior samples of the mixture proportions

mu

Values of the means of each Gaussian mixture

calAges

The calibrated ages from BchronCalibrate

G

The number of mixture components. Equal to numMix

age_grid

A grid of ages used for the final density estimate

density

The density estimate based on the above age grid

See Also

Bchronology, BchronRSL, BchronDensityFast for a faster approximate version of this function

Examples

# Read in some data from Sluggan Moss
data(Sluggan)

# Run the model
SlugDens <- with(
  Sluggan,
  BchronDensity(
    ages = ages,
    ageSds = ageSds,
    calCurves = calCurves
  )
)

# plot it
plot(SlugDens)

Non-parametric phase model (faster version)

Description

This function runs a non-parametric phase model on 14C and non-14C ages via Gaussian Mixture density estimation through the mclust package

Usage

BchronDensityFast(
  ages,
  ageSds,
  calCurves,
  pathToCalCurves = system.file("data", package = "Bchron"),
  dfs = rep(100, length(ages)),
  samples = 2000,
  G = 30
)

Arguments

Details

This is a faster approximate version of BchronDensity that uses the densityMclust function to compute the Gaussian mixtures for a set of calibrated ages. The method is an approximation as it does not fit a fully Bayesian model as BchronDensity does. It is designed to be a probabilistic version of the Oxcal SUM command which takes calibrated ages and sums the probability distributions with the aim of estimating activity through age as a proxy.

Value

An object of class BchronDensityRunFast with the following components:

out

The output from the run of densityMclust with the given number of mixture components

calAges

The calibrated ages from the BchronDensity function

See Also

Bchronology, BchronCalibrate, BchronRSL, BchronDensity for a slower exact version of this function

Examples

# Read in some data from Sluggan Moss
data(Sluggan)

# Run the model
SlugDensFast <- with(
  Sluggan,
  BchronDensityFast(
    ages = ages,
    ageSds = ageSds,
    calCurves = calCurves
  )
)

# plot it
plot(SlugDensFast)

Relative sea level rate (RSL) estimation

Description

Relative sea level rate (RSL) estimation

Usage

BchronRSL(
  BchronologyRun,
  RSLmean,
  RSLsd,
  degree = 1,
  iterations = 10000,
  burn = 2000,
  thin = 8
)

Arguments

Details

This function fits an errors-in-variables regression model to relative sea level (RSL) data. An errors-in-variables regression model allows for uncertainty in the explanatory variable, here the age of sea level data point. The algorithm is more fully defined in the reference below

Value

An object of class BchronRSLRun with elements

BchronologyRun

The output from the run of Bchronology

samples

The posterior samples of the regression parameters

degree

The degree of the polynomial regression

RSLmean

The RSL mean values given to the function

RSLsd

The RSL standard deviations as given to the function

const

The mean of the predicted age values. Used to standardise the design matrix and avoid computational issues

References

Andrew C. Parnell and W. Roland Gehrels (2013) 'Using chronological models in late holocene sea level reconstructions from salt marsh sediments' In: I. Shennan, B.P. Horton, and A.J. Long (eds). Handbook of Sea Level Research. Chichester: Wiley

See Also

BchronCalibrate, Bchronology, BchronDensity, BchronDensityFast

Examples

# Load in data
data(TestChronData)
data(TestRSLData)

# Run through Bchronology
RSLrun <- with(TestChronData, Bchronology(
  ages = ages,
  ageSds = ageSds,
  positions = position,
  positionThicknesses = thickness,
  ids = id,
  calCurves = calCurves,
  predictPositions = TestRSLData$Depth
))

# Now run through BchronRSL
RSLrun2 <- BchronRSL(RSLrun, RSLmean = TestRSLData$RSL, RSLsd = TestRSLData$Sigma, degree = 3)

# Summarise it
summary(RSLrun2)

# Plot it
plot(RSLrun2)

Runs the Compound Poisson-Gamma chronology model of Haslett and Parnell (2008)

Description

Fits a non-parametric chronology model to age/position data according to the Compound Poisson-Gamma model defined by Haslett and Parnell (2008) <DOI:10.1111/j.1467-9876.2008.00623.x>. This version uses a slightly modified Markov chain Monte Carlo fitting algorithm which aims to converge quicker and requires fewer iterations. It also a slightly modified procedure for identifying outliers

Usage

Bchronology(
  ages,
  ageSds,
  positions,
  positionThicknesses = rep(0, length(ages)),
  calCurves = rep("intcal20", length(ages)),
  ids = NULL,
  outlierProbs = rep(0.01, length(ages)),
  predictPositions = seq(min(positions), max(positions), length = 100),
  pathToCalCurves = system.file("data", package = "Bchron"),
  artificialThickness = 0.01,
  allowOutside = FALSE,
  iterations = 10000,
  burn = 2000,
  thin = 8,
  extractDate = 1950 - as.numeric(format(Sys.time(), "%Y")),
  maxExtrap = 1000,
  thetaStart = NULL,
  thetaMhSd = 0.5,
  muMhSd = 0.1,
  psiMhSd = 0.1,
  ageScaleVal = 1000,
  positionEps = 1e-05,
  positionNormalise = TRUE
)

Arguments

Details

The Bchronology function fits a compound Poisson-Gamma distribution to the increments between the dated levels. This involves a stochastic linear interpolation step where the age gaps are Gamma distributed, and the position gaps are Exponential. Radiocarbon and non-radiocarbon dates (including outliers) are updated within the function also by MCMC.

Value

A list of class BchronologyRun which include elements:

References

Haslett, J., and Parnell, A. C. (2008). A simple monotone process with application to radiocarbon-dated depth chronologies. Journal of the Royal Statistical Society, Series C, 57, 399-418. DOI:10.1111/j.1467-9876.2008.00623.x Parnell, A. C., Haslett, J., Allen, J. R. M., Buck, C. E., and Huntley, B. (2008). A flexible approach to assessing synchroneity of past events using Bayesian reconstructions of sedimentation history. Quaternary Science Reviews, 27(19-20), 1872-1885. DOI:10.1016/j.quascirev.2008.07.009

See Also

BchronCalibrate, BchronRSL, BchronDensity, BchronDensityFast

Examples

# Data from Glendalough
data(Glendalough)

# Run in Bchronology - all but first age uses intcal20
GlenOut <- with(
  Glendalough,
  Bchronology(
    ages = ages,
    ageSds = ageSds,
    calCurves = calCurves,
    positions = position,
    positionThicknesses = thickness,
    ids = id,
    predictPositions = seq(0, 1500, by = 10)
  )
)

# Summarise it a few different ways
summary(GlenOut) # Default is for quantiles of ages at predictPosition values
summary(GlenOut, type = "convergence") # Check model convergence
summary(GlenOut, type = "outliers") # Look at outlier probabilities

# Predict for some new positions
predictAges <- predict(GlenOut,
  newPositions = c(150, 725, 1500),
  newPositionThicknesses = c(5, 0, 20)
)

# Plot the output
plot(GlenOut) +
  ggplot2::labs(
    title = "Glendalough",
    xlab = "Age (cal years BP)",
    ylab = "Depth (cm)"
  )

# If you need to specify your own starting values
startingAges <- c(0, 2000, 10000, 11000, 13000, 13500)
GlenOut <- with(
  Glendalough,
  Bchronology(
    ages = ages,
    ageSds = ageSds,
    calCurves = calCurves,
    positions = position,
    positionThicknesses = thickness,
    ids = id,
    predictPositions = seq(0, 1500, by = 10),
    thetaStart = startingAges
  )
)

Glendalough data

Description

Chronology data for Glendalough data set

Usage

data(Glendalough)

Format

A data frame with 6 observations on the following 6 variables:

id

ID of each age

ages

Age in (14C) years BP

ageSds

Age standard deviations

position

Depths in cm

thickness

Thicknesses in cm

calCurves

Calibration curve for each age

Details

This Glendalough data can be used with Bchronology or BchronDensity

Source

Haslett, J., Whiley, M., Bhattacharya, S., Mitchell, F. J. G., Allen, J. R. M., Huntley, B., & Salter-Townshend, M. (2006). Bayesian palaeoclimate reconstruction. Journal of the Royal Statistical Society, Series A, 169, 395-438.

Sluggan Moss data

Description

Chronology data for Sluggan Moss data set

Usage

data(Sluggan)

Format

A data frame with 31 observations on the following 6 variables:

id

ID of each age

ages

Age in (14C) years BP

ageSds

Age standard deviations

position

Depths in cm

thickness

Thicknesses in cm

calCurves

Calibration curve for each age

Details

This Sluggan Moss data can be downloaded from the European Pollen Database: https://epdweblog.org/. For usage see Bchronology or BchronDensity

Source

Smith, A. G., & Goddard, I. C. (1991). A 12,500 year record of vegetational history at Sluggan Bog, Co. Antrim, N. Ireland (incorporating a pollen zone scheme for the non-specialist). New Phytologist, 118, 167-187.

Example chronology file for use with the BchronRSL function.

Description

Some example chronology data for use with the BchronRSL function

Usage

data(TestChronData)

Format

A data frame with 27 observations on the following 6 variables:

id

ID names

ages

Ages in years BP

ageSds

Ages standard deviations in years BP

position

Depths in cm

thickness

Thicknesses in cm

calCurves

Calibration curve for each age

Source

Andrew C. Parnell and W. Roland Gehrels (2013) 'Using chronological models in late holocene sea level reconstructions from salt marsh sediments' In: I. Shennan, B.P. Horton, and A.J. Long (eds). Handbook of Sea Level Research. Chichester: Wiley

Relative sea level data

Description

A set of relative sea level data for use with BchronRSL

Usage

data(TestRSLData)

Format

A data frame with 24 observations on the following 3 variables:

Depth

Depth in cm

RSL

Relative sea level in m

Sigma

Standard deviation of RSL measurement

Source

Andrew C. Parnell and W. Roland Gehrels (2013) 'Using chronological models in late holocene sea level reconstructions from salt marsh sediments' In: I. Shennan, B.P. Horton, and A.J. Long (eds). Handbook of Sea Level Research. Chichester: Wiley

Compute positions to date next which result in maximal decrease of chronological uncertainty

Description

This function finds, for a given current chronology, created via Bchronology, which positions (depths) to date next If N = 1 it just finds the position with the biggest uncertainty If N>1 it puts a date at the N = 1 position and re-runs Bchronology with the extra psuedo date. It uses the unCalibrate function with the un-calibrated age estimated at the median of the chronology and the sd as specified via the newSds argument. Other arguments specify the new thicknesses, calibration curves, and outlier probabilities for newly inserted psuedo-dates.

Usage

choosePositions(
  bchrRun,
  N = 1,
  newSds = 30,
  newThicknesses = 0,
  positions = bchrRun$predictPositions,
  newCalCurve = "intcal20",
  newOutlierProb = 0.05,
  level = 0.5,
  plot = TRUE,
  count = 1,
  linesAt = NULL
)

Arguments

Value

Some plots and the positions to date next

See Also

Bchronology for the main function to create chronologies, unCalibrate for the ability to invert calendar dates for a given calibration curve.

Examples

data(Glendalough)
GlenOut <- Bchronology(
  ages = Glendalough$ages,
  ageSds = Glendalough$ageSds,
  calCurves = Glendalough$calCurves,
  positions = Glendalough$position,
  positionThicknesses = Glendalough$thickness,
  ids = Glendalough$id,
  predictPositions = seq(0, 1500, by = 10)
)

# Find out which two positions (depths) to date if we have room for two more dates
# Here going to choose 3 new positions to date
newPositions <- choosePositions(GlenOut, N = 3)
print(newPositions)

# Suppose you are only interested in dating the new depths at 500, 600, or 700 cm
newPositions2 <- choosePositions(GlenOut,
  N = 2,
  positions = seq(500, 700, by = 10)
)
print(newPositions2)

Find the influence of dates in a pair of Bchronology runs across the core

Description

This function takes as input two Bchronology runs and compares the uncertainty intervals. It does this by computing the mean uncertainty across the core (type = 'mean') at a specified percentile level (e.g. 95%) and subsequently reporting the reduction/increase in uncertainty between the two runs. Both cores must have the same set of depths/positions at regular intervals.

Usage

coreInfluence(
  bchrRun1,
  bchrRun2,
  percentile = 0.95,
  type = c("plot", "summary", "max"),
  ageTolerance = 500,
  ...
)

Arguments

Details

For example, if the ageTolerance value is 500 years, then coreInfluence will return all of the positions at which the uncertainty reduction is bigger than 500.

Value

Depending on type will outputs some text and plots providing the influence values for the cores in question.

See Also

Bchronology, choosePositions, dateInfluence for finding the influence of removing a single date from a core

Examples

data(Glendalough)
# Start with a run that remove two dates
GlenOut1 <- Bchronology(
  ages = Glendalough$ages[-c(3:4)],
  ageSds = Glendalough$ageSds[-c(3:4)],
  calCurves = Glendalough$calCurves[-c(3:4)],
  positions = Glendalough$position[-c(3:4)],
  positionThicknesses = Glendalough$thickness[-c(3:4)],
  ids = Glendalough$id[-c(3:4)],
  predictPositions = seq(0, 1500, by = 10)
)
GlenOut2 <- Bchronology(
  ages = Glendalough$ages,
  ageSds = Glendalough$ageSds,
  calCurves = Glendalough$calCurves,
  positions = Glendalough$position,
  positionThicknesses = Glendalough$thickness,
  ids = Glendalough$id,
  predictPositions = seq(0, 1500, by = 10)
)

# Now compare their influence
coreInfluence(GlenOut1,
  GlenOut2,
  type = c("max", "plot"),
  xlab = "Age (cal years BP)",
  ylab = "Depth (cm)",
  main = "Chronology difference at 95% for
              Glendalough removing two dates",
  las = 1
)

Create a new calibration curve

Description

A function for creating a new calibration curve not already available in Bchron

Usage

createCalCurve(
  name,
  calAges,
  uncalAges,
  oneSigma = rep(0, length(calAges)),
  pathToCalCurves = getwd(),
  createFile = TRUE
)

Arguments

Details

All calibration curves are stored by Bchron in the standard R gzipped text format. You can find the location of the calibration curves by typing system.file('data',package='Bchron'). Any created calibration curve will be converted to this format. However R packages are not allowed to write to this directory so it is up to the user to put the resulting calibration curve file in the appropriate directory. It can then be used as in the examples below. However note that re-installing Bchron will likely over-write previously created calibration curves so you should make sure to store the code used to create it. As a short-cut to copying it by hand you can instead use the file.copy command in the example below.

Value

No return value, creates a file in your working directory

See Also

BchronCalibrate

Examples

## Not run: 
# Load in the calibration curve with:
intcal09 <- read.table(system.file("extdata/intcal09.14c", package = "Bchron"), sep = ",")
# Run createCalCurve
createCalCurve(
  name = "intcal09", calAges = intcal09[, 1],
  uncalAges = intcal09[, 2], oneSigma = intcal09[, 3]
)

# Copy the file to the right place
file.copy(
  from = "intcal09.rda",
  to = system.file("data", package = "Bchron"),
  overwrite = TRUE
) # Only need this if you've run it more than once

# Calibrate the ages under two calibration curves
age_09 <- BchronCalibrate(
  ages = 15500, ageSds = 150,
  calCurves = "intcal09", ids = "My Date",
  pathToCalCurves = getwd()
)
age_20 <- BchronCalibrate(ages = 15500, ageSds = 150, calCurves = "intcal20")

# Finally plot the difference
library(ggplot2)
plot(age_09) +
  geom_line(
    data = as.data.frame(age_20$Date1),
    aes(x = ageGrid, y = densities), col = "red"
  ) +
  ggtitle("Intcal09 vs Intcal20")

## End(Not run)

Find the influence of the dates in a Bchronology run

Description

This function takes as input a Bchronology run and allows the user to estimate a value of 'influence' for either a particular date (by name or number), for all dates in a core (whichDate = 'all'), or for all internal dates (whichDate = 'internal'). It measures the influence by either the Kullback-Leibler divergence (KL), the absolute mean difference (absMeanDiff), or the absolute median difference (absMedianDiff).

Usage

dateInfluence(
  bchrRun,
  whichDate = "all",
  measure = c("KL", "absMeanDiff", "absMedianDiff")
)

Arguments

Details

The KL measure is preferred as it takes account of the full probability distributions but it lacks a simple interpretation. The best way to use it is with whichDate = 'all': the largest value corresponds to the most influential date in the chronology. For simpler interpretation use measure = 'absMeanDiff' or measure = 'absMedianDiff' as for these the influence is measured in years.

When the predictPositions from the original Bchronology run do not include those of the date(s) being left out then the function uses the closest position and reports the change.

Value

Outputs some text providing the influence values for the date(s) in question. If given an assignment value also return a list containing all the probability distributions.

See Also

Bchronology, summary.BchronologyRun, coreInfluence, choosePositions

Examples

data(Glendalough)
GlenOut <- Bchronology(
  ages = Glendalough$ages,
  ageSds = Glendalough$ageSds,
  calCurves = Glendalough$calCurves,
  positions = Glendalough$position,
  positionThicknesses = Glendalough$thickness,
  ids = Glendalough$id,
  predictPositions = seq(0, 1500, by = 10)
)
dateInfluence(GlenOut, whichDate = 4, measure = "absMeanDiff")

Calculate highest density regions for Bchron calibrated ages

Description

A function for computing highest density regions (HDRs)

Usage

hdr(date, prob = 0.95)

Arguments

Details

The output of this function is a list of contiguous ranges which cover the probability interval requested. A highest density region might have multiple such ranges if the calibrated date is multi-modal. These differ from credible intervals, which are always contiguous but will not be a good representation of a multi-modal probability distribution.

Value

A list where each element is one of the contiguous sets making up the HDR

See Also

BchronCalibrate

Examples

# Calibrate multiple ages and summarise them
ages <- BchronCalibrate(
  ages = 11553, ageSds = 230,
  calCurves = "intcal20"
)
# Get samples
hdr(ages$Date1)

Northern hemisphere 2013 calibration curve

Description

Northern hemisphere 2013 calibration curve. The first 3 columns are the calibrated age (in years BP), the radiocarbon age (in 14C years BP), and the 1 sigma standard error (also in 14C years BP).

Usage

data(intcal13)

Format

A data frame with 5141 observations on 5 variables.

Details

For full details and reference see http://intcal.org/blurb.html. For usage details see BchronCalibrate

Northern hemisphere 2020 calibration curve

Description

Northern hemisphere 2020 calibration curve. The first 3 columns are the calibrated age (in years BP), the radiocarbon age (in 14C years BP), and the 1 sigma standard error (also in 14C years BP).

Usage

data(intcal20)

Format

A data frame with 9501 observations on 5 variables.

Details

For full details and reference see http://intcal.org/blurb.html. For usage details see BchronCalibrate

Marine 2013 calibration curve

Description

Marine 2013 calibration curve. The first 3 columns are the calibrated age (in years BP), the radiocarbon age (in 14C years BP), and the 1 sigma standard error (also in 14C years BP).

Usage

data(marine13)

Format

A data frame with 4801 observations on 5 variables

Details

For full details and reference see http://intcal.org/blurb.html. For usage details see BchronCalibrate

Marine 2020 calibration curve

Description

Marine 2020 calibration curve. The first 3 columns are the calibrated age (in years BP), the radiocarbon age (in 14C years BP), and the 1 sigma standard error (also in 14C years BP).

Usage

data(marine20)

Format

A data frame with 5501 observations on 5 variables

Details

For full details and reference see http://intcal.org/blurb.html. For usage details see BchronCalibrate

Data for dummy calibration of normally distributed ages

Description

Data for dummy calibration of normally distributed ages

Usage

data(normal)

Format

A data frame with 2 observations on 3 variables.

Details

This is dummy data so that BchronCalibrate can calibrate normally distributed dates.

Plot calibrated dates from a BchronCalibrate run

Description

Plots calibrated radiocarbon dates from a BchronCalibrate run. Has options to plot on a position (usually depth) scale if supplied with the original run

Usage

## S3 method for class 'BchronCalibratedDates'
plot(
  x,
  date = NULL,
  withPositions = ifelse(length(x) > 1 & !is.null(x[[1]]$positions) & !includeCal, TRUE,
    FALSE),
  includeCal = FALSE,
  dateHeight = 100,
  dateLabels = TRUE,
  dateLabelSize = 2,
  nudgeX = 0,
  nudgeY = 0,
  fillCol = rgb(47/255, 79/255, 79/255, 0.5),
  withHDR = TRUE,
  ageScale = c("bp", "bc", "b2k"),
  scaleReverse = TRUE,
  pathToCalCurves = system.file("data", package = "Bchron"),
  ...
)

Arguments

Details

These plots are intended to be pretty basic and used simply for quick information. Users are encouraged to learn the R plotting features to produce publication quality graphics

Value

A ggplot object containing the plot of the calibrated dates

See Also

BchronCalibrate, Bchronology, BchronRSL, BchronDensity, BchronDensityFast

Plot output from BchronDensity

Description

Plot output from BchronDensity

Usage

## S3 method for class 'BchronDensityRun'
plot(
  x,
  plotDates = TRUE,
  plotRawSum = FALSE,
  plotPhase = TRUE,
  phaseProb = 0.95,
  dateTransparency = 0.4,
  ...
)

Arguments

Value

A plot object of the density run

See Also

See BchronDensity for examples, also Bchronology, BchronRSL, and BchronDensityFast for a faster approximate version of this function

Plot run from BchronDensityFast

Description

Plots output from BchronDensityFast

Usage

## S3 method for class 'BchronDensityRunFast'
plot(x, plotDates = TRUE, plotSum = FALSE, dateTransparency = 0.4, ...)

Arguments

Details

Creates a basic plot of output for a run of BchronDensityFast

Value

A plot object of the density run

See Also

Examples in BchronDensityFast, and see BchronDensity, for a slower, more accurate version of this function

Plot output from BchronRSL

Description

Plot output from the BchronRSL function

Usage

## S3 method for class 'BchronRSLRun'
plot(
  x,
  type = c("RSL", "rate", "accel"),
  alpha = 0.95,
  ellipseCol = "darkslategray",
  lineCol = "deepskyblue4",
  ...
)

Arguments

Value

A ggplot2 object of the RSL run

See Also

BchronCalibrate, Bchronology, BchronRSL, BchronDensity, BchronDensityFast

Plot output from Bchronology

Description

Plots output from a run of Bchronology

Usage

## S3 method for class 'BchronologyRun'
plot(
  x,
  dateHeight = 100,
  dateLabels = TRUE,
  dateLabelSize = 2,
  dateCol = rgb(47/255, 79/255, 79/255, 0.5),
  chronCol = "deepskyblue4",
  chronTransparency = 0.75,
  alpha = 0.95,
  nudgeX = 0,
  nudgeY = 0,
  expandX = if (dateLabels) {
     c(0.1, 0)
 } else {
     c(0, 0)
 },
  expandY = c(0.05, 0),
  ageScale = c("bp", "bc", "b2k"),
  scaleReverse = TRUE,
  ...
)

Arguments

Details

Creates a simple plot of the chronology output. The height of the date densities in the plots can be manipulated via the dateHeight argument which is represented in the same units as the positions/depths provided. More detailed plots can be created by manipulating the Bchronology object as required.

Value

A ggplot2 object of the chronology run

See Also

For examples see Bchronology. Also BchronCalibrate, BchronRSL, BchronDensity, BchronDensityFast

Predict ages of other positions for a BchronologyRun object

Description

This function will predict the ages of new positions (usually depths) based on a previous run of the function Bchronology. It will also allow for thickness uncertainties to be included in the resulting ages, for example when the age of a particular event is desired

Usage

## S3 method for class 'BchronologyRun'
predict(
  object,
  newPositions,
  newPositionThicknesses = NULL,
  maxExtrap = 500,
  ...
)

Arguments

Value

A matrix of dimension num_samples by num_positions so that each row represents a set of monotonic sample predicted ages

See Also

BchronCalibrate, Bchronology BchronRSL, BchronDensity, BchronDensityFast

Get sample ages from a set of Bchron calibrated dates

Description

A function for extracting sample ages from Bchron calibrated dates

Usage

sampleAges(CalDates, n_samp = 10000)

Arguments

Details

Sometimes it is useful to have a set of sample calendar ages for your calibrated dates. For example the samples might be required to create a credible/confidence interval, or to create another non-trivial function of calibrated dates, such as differences. By default the BchronCalibrate function provides a grid of ages and an associated density, similar to OxCal. This function extracts that information and uses the sample function to output the desired number of samples

Value

A vector of length n_samp containing sample ages for the specified date

See Also

BchronCalibrate

Examples

# Calibrate multiple ages and summarise them
ages <- BchronCalibrate(
  ages = c(3445, 11553, 7456), ageSds = c(50, 230, 110),
  calCurves = c("intcal20", "intcal20", "shcal20")
)
# Get samples
age_samples <- sampleAges(ages)
# Create a credible interval and the median for each date
apply(age_samples, 2, quantile, probs = c(0.05, 0.5, 0.95))

Southern hemisphere 2013 calibration curve

Description

Southern hemisphere 2013 calibration curve. The first 3 columns are the calibrated age (in years BP), the radiocarbon age (in 14C years BP), and the 1 sigma standard error (also in 14C years BP).

Usage

data(shcal13)

Format

A data frame with 5141 observations on 5 variables.

Details

For full details and reference see http://intcal.org/blurb.html. For usage details see BchronCalibrate

Southern hemisphere 2020 calibration curve

Description

Southern hemisphere 2020 calibration curve. The first 3 columns are the calibrated age (in years BP), the radiocarbon age (in 14C years BP), and the 1 sigma standard error (also in 14C years BP).

Usage

data(shcal20)

Format

A data frame with 9501 observations on 5 variables.

Details

For full details and reference see http://intcal.org/blurb.html. For usage details see BchronCalibrate

Summarise a BchronCalibrate object

Description

Produces summary output from a BchronCalibrate run, including the highest density regions for the calibrated ages for given probability levels

Usage

## S3 method for class 'BchronCalibratedDates'
summary(object, prob = 95, ..., digits = max(3, getOption("digits") - 3))

Arguments

Value

A list of highest density regions for each calibrated date in the object

See Also

BchronCalibrate, Bchronology, BchronRSL, BchronDensity, BchronDensityFast

Summarise a Bchron density object

Description

Summarise a BchronDensity object

Usage

## S3 method for class 'BchronDensityRun'
summary(object, prob = 0.95, ..., digits = max(3, getOption("digits") - 3))

Arguments

Value

A list of highest density regions for each phase in the object

See Also

BchronDensity

Summarise a BchronRSL run

Description

Summarise a BchronRSL run

Usage

## S3 method for class 'BchronRSLRun'
summary(
  object,
  type = c("parameters", "RSL", "rate", "accel"),
  age_grid = NULL,
  ...
)

Arguments

Value

A summary of the BchronRSL run, including posterior medians and credible intervals for the regression coefficients, RSL estimates, rate estimates, and acceleration estimates.

See Also

BchronCalibrate, Bchronology, BchronRSL, BchronDensity, BchronDensityFast

Summarise a Bchronology object

Description

Summarise a Bchronology object

Usage

## S3 method for class 'BchronologyRun'
summary(
  object,
  type = c("quantiles", "outliers", "convergence", "sed_rate", "acc_rate", "max_var"),
  probs = c(0.025, 0.25, 0.5, 0.75, 0.975),
  useExisting = TRUE,
  numPos = 3,
  ...,
  digits = max(3, getOption("digits") - 3)
)

Arguments

Value

A data frame summarising the Bchronology object depending on the type of summary requested. For quantiles, a data frame with the quantiles for each position. For outliers, a data frame with outlier probabilities. For convergence, a data frame with p-values for convergence diagnostics. For sedimentation and accumulation rates, a data frame with the rates at each position/age. For maximum variance, a vector of positions with maximum age variance.

See Also

BchronCalibrate, Bchronology BchronRSL, BchronDensity, BchronDensityFast

Uncalibrate a Radiocarbon date

Description

Uncalibrate a Radiocarbon date

Usage

unCalibrate(
  calAges,
  calCurve = "intcal20",
  type = c("samples", "ages"),
  pathToCalCurves = system.file("data", package = "Bchron"),
  ...
)

Arguments

Value

Either a vector of uncalibrated ages (type = 'ages') or a list containing the estimated mean age and standard deviation (type = 'samples')

Examples

# Single version outputting just an uncalibrated age
unCalibrate(2350, type = "ages")

# Vector version giving a vector of uncalibrated ages
unCalibrate(
  calAge = c(2350, 4750, 11440),
  calCurve = "shcal20",
  type = "ages"
)

# A version where calibrated standard deviations are required too
calAge <- BchronCalibrate(
  ages = 11255,
  ageSds = 25,
  calCurves = "intcal20"
)
calSampleAges <- sampleAges(calAge)

# Uncalibrate the above
unCalibrate(calSampleAges,
  type = "samples"
)