Package 'oxcAAR'

Title: Interface to 'OxCal' Radiocarbon Calibration
Description: A set of tools that enables using 'OxCal' from within R. 'OxCal' (<https://c14.arch.ox.ac.uk/oxcal.html>) is a standard archaeological tool intended to provide 14C calibration and analysis of archaeological and environmental chronological information. 'OxcAAR' allows simple calibration with 'Oxcal' and plotting of the results as well as the execution of sophisticated ('OxCal') code and the import of the results of bulk analysis and complex Bayesian sequential calibration.
Authors: Hinz Martin [aut, cre], Clemens Schmid [aut], Daniel Knitter [aut], Carolin Tietze [aut]
Maintainer: Hinz Martin <[email protected]>
License: GPL-2 | file LICENSE
Version: 1.1.2
Built: 2026-05-12 08:33:40 UTC
Source: https://github.com/isaakiel/oxcaar

Help Index

Returns the Oxcal code for a Boundary

Description

Boundary returns the OxCal code for a Boundary. For details concerning the Oxcal simulation please consult the help page of Oxcal.

Usage

Boundary(names = "")

Arguments

names

a optional vector of names for the resulting boundary. If missing or empty, an unnamed boundary is returned.

Value

a string containing the respective Oxcal code

Plot calibrated dates on the calibration curve

Description

Draws the calibration curve (with 1-sigma envelope) and overlays one or more calibrated dates as points and/or error bars (uncalibrated and calibrated ranges).

Usage

calcurve_plot(
  x,
  dates_sigma_ranges = c("two_sigma", "one_sigma", "three_sigma"),
  uncal_range = TRUE,
  cal_range = TRUE
)

Arguments

x

An object of class oxcAARCalibratedDate or oxcAARCalibratedDatesList.
dates_sigma_ranges

Character. The sigma range used for the calibrated error bars. One of "two_sigma" (default), "one_sigma", "three_sigma".
uncal_range

Logical. If TRUE (default), the plot contains vertical error bars for the uncalibrated age (BP ±\pm k * std).
cal_range

Logical. If TRUE (default), the plot contains horizontal error bars for the calibrated age (sigma range in calendar years).

Value

NULL (called for its side effect: base graphics plot).

Executes an Oxcal Script

Description

Takes an Oxcal Script, hands it over to oxcal and receives the output that is read from the output file

Usage

executeOxcalScript(oxcal_script, file = NULL)

Arguments

oxcal_script

A string containing the Oxcal commands that should be processed.
file

A string naming a file for writing. Elements of the path other than the last will be created if needed. If 'NULL' (the default), a temporary file will be used.

Value

The path to the js output file

Author(s)

Martin Hinz

Format an oxcAARCalibratedDate

Description

Format an oxcAARCalibratedDate

Usage

## S3 method for class 'oxcAARCalibratedDate'
format(x, ...)

Arguments

x

An oxcAARCalibratedDate.
...

Unused (kept for S3 consistency).

Value

A character string (invisibly).

get bp values (ages)

Description

queries values from date objects

Usage

get_bp(x)

## Default S3 method:
get_bp(x)

## S3 method for class 'oxcAARCalibratedDate'
get_bp(x)

## S3 method for class 'oxcAARCalibratedDatesList'
get_bp(x)

Arguments

x

an object of class oxcAARCalibratedDate or oxcAARCalibratedDatesList

Value

an integer or a numeric vector

See Also

Other getter functions: get_cal_curve(), get_name(), get_posterior_probabilities(), get_posterior_sigma_ranges(), get_raw_probabilities(), get_sigma_ranges(), get_std()

Examples

## Not run: 
x <- oxcalCalibrate(c(5000, 4500, 3000), c(20, 50, 60))
get_bp(x)
y <- oxcalCalibrate(5000, 20)[[1]]
get_bp(y)

## End(Not run)

get calibration curve names

Description

queries values from date objects

Usage

get_cal_curve(x)

## Default S3 method:
get_cal_curve(x)

## S3 method for class 'oxcAARCalibratedDate'
get_cal_curve(x)

## S3 method for class 'oxcAARCalibratedDatesList'
get_cal_curve(x)

Arguments

x

an object of class oxcAARCalibratedDate or oxcAARCalibratedDatesList

Value

a string or a character vector

See Also

Other getter functions: get_bp(), get_name(), get_posterior_probabilities(), get_posterior_sigma_ranges(), get_raw_probabilities(), get_sigma_ranges(), get_std()

Examples

## Not run: 
x <- oxcalCalibrate(c(5000, 4500, 3000), c(20, 50, 60))
get_cal_curve(x)
y <- oxcalCalibrate(5000, 20)[[1]]
get_cal_curve(y)

## End(Not run)

get names (labcodes)

Description

queries values from date objects

Usage

get_name(x)

## Default S3 method:
get_name(x)

## S3 method for class 'oxcAARCalibratedDate'
get_name(x)

## S3 method for class 'oxcAARCalibratedDatesList'
get_name(x)

Arguments

x

an object of class oxcAARCalibratedDate or oxcAARCalibratedDatesList

Value

a string or a character vector

See Also

Other getter functions: get_bp(), get_cal_curve(), get_posterior_probabilities(), get_posterior_sigma_ranges(), get_raw_probabilities(), get_sigma_ranges(), get_std()

Examples

## Not run: 
x <- oxcalCalibrate(c(5000, 4500, 3000), c(20, 50, 60))
get_name(x)
y <- oxcalCalibrate(5000, 20)[[1]]
get_name(y)

## End(Not run)

get posterior raw probabilities

Description

queries values from date objects

Usage

get_posterior_probabilities(x)

## Default S3 method:
get_posterior_probabilities(x)

## S3 method for class 'oxcAARCalibratedDate'
get_posterior_probabilities(x)

## S3 method for class 'oxcAARCalibratedDatesList'
get_posterior_probabilities(x)

Arguments

x

an object of class oxcAARCalibratedDate or oxcAARCalibratedDatesList

Value

a list of three data.frames or a list of those lists

See Also

Other getter functions: get_bp(), get_cal_curve(), get_name(), get_posterior_sigma_ranges(), get_raw_probabilities(), get_sigma_ranges(), get_std()

get posterior sigma ranges

Description

queries values from date objects

Usage

get_posterior_sigma_ranges(x)

## Default S3 method:
get_posterior_sigma_ranges(x)

## S3 method for class 'oxcAARCalibratedDate'
get_posterior_sigma_ranges(x)

## S3 method for class 'oxcAARCalibratedDatesList'
get_posterior_sigma_ranges(x)

Arguments

x

an object of class oxcAARCalibratedDate or oxcAARCalibratedDatesList

Value

a list of three data.frames or a list of those lists

See Also

Other getter functions: get_bp(), get_cal_curve(), get_name(), get_posterior_probabilities(), get_raw_probabilities(), get_sigma_ranges(), get_std()

get raw probabilities

Description

queries values from date objects

Usage

get_raw_probabilities(x)

## Default S3 method:
get_raw_probabilities(x)

## S3 method for class 'oxcAARCalibratedDate'
get_raw_probabilities(x)

## S3 method for class 'oxcAARCalibratedDatesList'
get_raw_probabilities(x)

Arguments

x

an object of class oxcAARCalibratedDate or oxcAARCalibratedDatesList

Value

a data.frame or a list of data.frames

See Also

Other getter functions: get_bp(), get_cal_curve(), get_name(), get_posterior_probabilities(), get_posterior_sigma_ranges(), get_sigma_ranges(), get_std()

Examples

## Not run: 
x <- oxcalCalibrate(c(5000, 4500, 3000), c(20, 50, 60))
get_raw_probabilities(x)
y <- oxcalCalibrate(5000, 20)[[1]]
get_raw_probabilities(y)

## End(Not run)

get sigma ranges

Description

queries values from date objects

Usage

get_sigma_ranges(x)

## Default S3 method:
get_sigma_ranges(x)

## S3 method for class 'oxcAARCalibratedDate'
get_sigma_ranges(x)

## S3 method for class 'oxcAARCalibratedDatesList'
get_sigma_ranges(x)

Arguments

x

an object of class oxcAARCalibratedDate or oxcAARCalibratedDatesList

Value

a list of three data.frames or a list of those lists

See Also

Other getter functions: get_bp(), get_cal_curve(), get_name(), get_posterior_probabilities(), get_posterior_sigma_ranges(), get_raw_probabilities(), get_std()

Examples

## Not run: 
x <- oxcalCalibrate(c(5000, 4500, 3000), c(20, 50, 60))
get_sigma_ranges(x)
y <- oxcalCalibrate(5000, 20)[[1]]
get_sigma_ranges(y)

## End(Not run)

get std values (standard deviations)

Description

queries values from date objects

Usage

get_std(x)

## Default S3 method:
get_std(x)

## S3 method for class 'oxcAARCalibratedDate'
get_std(x)

## S3 method for class 'oxcAARCalibratedDatesList'
get_std(x)

Arguments

x

an object of class oxcAARCalibratedDate or oxcAARCalibratedDatesList

Value

an integer or a numeric vector

See Also

Other getter functions: get_bp(), get_cal_curve(), get_name(), get_posterior_probabilities(), get_posterior_sigma_ranges(), get_raw_probabilities(), get_sigma_ranges()

Examples

## Not run: 
x <- oxcalCalibrate(c(5000, 4500, 3000), c(20, 50, 60))
get_std(x)
y <- oxcalCalibrate(5000, 20)[[1]]
get_std(y)

## End(Not run)

tidy output

Description

Transforms oxcAAR output to a tidy data format. See http://vita.had.co.nz/papers/tidy-data.html and https://CRAN.R-project.org/package=broom

Usage

get_tidy_oxcalresult(x)

## Default S3 method:
get_tidy_oxcalresult(x)

## S3 method for class 'oxcAARCalibratedDate'
get_tidy_oxcalresult(x)

## S3 method for class 'oxcAARCalibratedDatesList'
get_tidy_oxcalresult(x)

Arguments

x

an object of class oxcAARCalibratedDate or oxcAARCalibratedDatesList

Value

a data.frame (with list columns)

Examples

## Not run: 
x <- oxcalCalibrate(c(5000, 4500, 3000), c(20, 50, 60))
get_tidy_oxcalresult(x)
y <- oxcalCalibrate(5000, 20)[[1]]
get_tidy_oxcalresult(y)

## End(Not run)

Checks if a variable is of class oxcAARCalibratedDate

Description

Checks if a variable is of class oxcAARCalibratedDate

Usage

is.oxcAARCalibratedDate(x)

Arguments

x

An object to test.

Value

TRUE if x inherits from "oxcAARCalibratedDate", FALSE otherwise.

Checks if a variable is of class oxcAARCalibratedDatesList

Description

Checks if a variable is of class oxcAARCalibratedDatesList

Usage

is.oxcAARCalibratedDatesList(x)

Arguments

x

An object to test.

Value

TRUE if x inherits from "oxcAARCalibratedDatesList", FALSE otherwise.

oxcAAR Calibrated Dates Object

Description

The function oxcAARCalibratedDate() creates an object representing a single calibrated radiocarbon date (and optionally its posterior, if a model was run in OxCal).

Usage

oxcAARCalibratedDate(
  name,
  type,
  bp,
  std,
  cal_curve,
  sigma_ranges,
  raw_probabilities,
  posterior_probabilities = NA,
  posterior_sigma_ranges = NA
)

Arguments

name

A string giving the name of the date (usually the lab number).
type

A string giving the type of the date in OxCal terminology (e.g. "R_Date", "R_Simulate").
bp

An integer/numeric giving the uncalibrated BP value.
std

An integer/numeric giving the standard deviation.
cal_curve

A list with calibration curve information (name, resolution, bp, bc, sigma).
sigma_ranges

A list of three elements (one, two, three sigma), each a data frame with columns start, end, probability.
raw_probabilities

A data frame with columns dates and probabilities.
posterior_probabilities

A data frame with columns dates and probabilities, or NA if not available.
posterior_sigma_ranges

A list of three elements (one, two, three sigma), each a data frame with columns start, end, probability, or NA if not available.

Value

An object of class "oxcAARCalibratedDate".

oxcAAR Calibrated Dates List

Description

A list of calibrated dates, i.e. objects of class oxcAARCalibratedDate.

Value

An object of class "oxcAARCalibratedDatesList" (a list).

Wraps an Oxcal string into a Oxcal sum function

Description

Wraps an Oxcal string into a Oxcal sum function

Usage

oxcal_Sum(oxcal_string, name = " Sum ")

Arguments

oxcal_string

The Oxcal script that should be wrapped (vector or single string)
name

The name attribute for the resulting sum function

Value

A new oxcal script as string

Calibrates a 14C date using oxcal

Description

Calibrates a 14C date using oxcal

Usage

oxcalCalibrate(bp, std, names = 1:length(bp))

Arguments

bp

A vector containing the bp dates of the measurements
std

A vector containing the standard deviations of the measurements
names

The names of the measurements, usually the Laboratory numbers

Value

An object of class oxcAARCalibratedDatesList

Simulates 14C dates using oxcal

Description

Simulates 14C dates using oxcal

Usage

oxcalSimulate(c_date, std, names = 1:length(c_date))

Arguments

c_date

A vector containing the calendar dates to be simulated
std

A vector containing the standard deviations for the simulated dates
names

The names of the measurements, usually the Laboratory numbers

Value

An object of class oxcAARCalibratedDatesList

Sum calibration for simulated dates

Description

Sum calibration for simulated dates

Usage

oxcalSumSim(
  timeframe_begin,
  timeframe_end,
  n,
  stds,
  date_distribution = c("equidist", "uniform")
)

Arguments

timeframe_begin, timeframe_end

beginning and end of the time frame for which dates should be simulated
n

the number of dates that should be simulated
stds

either one standard deviation for all dates or a vector of standard deviations with length n
date_distribution

a character string indicating which method should be used to distribute the dates in the given time frame, can be abbreviated

Details

The dates can be distributed using one of the following methods: 'equidist' distributed the n dates within the time frame with equal distance, 'uniform' random samples n dates from the given time interval with uniform distribution

Value

A list containing the following components:

dates

the dates for the simulated sum calibration
probabilities

the probabilities for the simulated sum calibration
date_distribution

the distribution method used for the dates

Parses an Oxcal Output File completely into R

Description

Takes the output of Oxcal as vector of strings (one string per line) and parse it as list.

Usage

parseFullOxcalOutput(output)

Arguments

output

The output of Oxcal as vector of strings (one string per line).

Value

A list containing all informations provided by Oxcal as list.

Parses an Oxcal Output File into R

Description

Takes the output of Oxcal as vector of strings (one string per line) and parse it as list.

Usage

parseOxcalOutput(result, first = FALSE, only.R_Date = TRUE)

Arguments

result

The output of Oxcal as vector of strings (one string per line).
first

Return the first date only
only.R_Date

Return the informations for R_Dates

Value

A list containing all informations provided by Oxcal as list.

Returns the Oxcal code for Phase

Description

Phase takes a set of R_Dates as vectors, and returns a bit of oxcal code that can be used to feed it into oxcal. In this code the R_Dates are encapsulated in an OxCal Phases, one Phase for each string. For details concerning the Oxcal simulation please consult the help page of Oxcal.

Usage

Phase(r_dates_strings, names = "")

Arguments

r_dates_strings

a vector containing strings of OxCal code, usually consisting of R_Date commands, but any other code strings might be used that can be interpreted by OxCal within a Phase
names

a optional vector of names for the resulting Phases

Value

a string containing the respective Oxcal code

Plot an oxcAARCalibratedDate

Description

Plot an oxcAARCalibratedDate

Usage

## S3 method for class 'oxcAARCalibratedDate'
plot(x, use_ggplot = TRUE, ...)

Arguments

x

An oxcAARCalibratedDate.
use_ggplot

Logical. If TRUE (default) and ggplot2 is available, a ggplot2 plot is produced.
...

Further arguments passed to the underlying plotting function.

Plot an oxcAARCalibratedDatesList

Description

For lists of length 1, this dispatches to plot() for oxcAARCalibratedDate. For longer lists, it uses either ggplot2 (ridge plots) or base graphics.

Usage

## S3 method for class 'oxcAARCalibratedDatesList'
plot(x, use_ggplot = TRUE, ...)

Arguments

x

An oxcAARCalibratedDatesList.
use_ggplot

Logical. If TRUE (default) and the required packages are available, a ggplot2-based ridge plot is produced.
...

Further arguments passed to the underlying plotting function.

Print an oxcAARCalibratedDate

Description

Print an oxcAARCalibratedDate

Usage

## S3 method for class 'oxcAARCalibratedDate'
print(x, ...)

Arguments

x

An oxcAARCalibratedDate.
...

Passed to format().

Print an oxcAARCalibratedDatesList

Description

Print an oxcAARCalibratedDatesList

Usage

## S3 method for class 'oxcAARCalibratedDatesList'
print(x, ...)

Arguments

x

An oxcAARCalibratedDatesList.
...

Further arguments passed to print() of single dates.

Quick OxCal setup

Description

Downloads the latest version of Oxcal and sets the executable path correctly

Usage

quickSetupOxcal(os = Sys.info()["sysname"], path = tempdir())

Arguments

os

The operating system of the workstation. Default: automatic determination. Options:

  • Linux

  • Windows

  • Darwin

path

The path to the directory where Oxcal is or should be stored. Default: "tempdir()". I recommend thought to install it permanently.

Author(s)

Clemens Schmid

Examples

## Not run: 
  quickSetupOxcal()

## End(Not run)

Returns the Oxcal code for the calibration of 14C dates

Description

R_Date takes names, BP dates and standard deviation for those dates as vectors, and returns a bit of oxcal code that can be used to feed it into oxcal. For details concerning the Oxcal calibration please consult the help page of Oxcal.

Usage

R_Date(names, r_dates, stds)

Arguments

names

a vector of names for the dates
r_dates

a vector containing the BP dates that should be calibrated
stds

a vector containing the standard deviation that should be calibrated (length 1 or same length as r_dates)

Value

a string containing the respective Oxcal code

Returns the Oxcal code for the simulation of 14C dates

Description

R_Simulate takes names, calendar dates and standard deviation for those dates as vectors, and returns a bit of oxcal code that can be used to feed it into oxcal. For details concerning the Oxcal simulation please consult the help page of Oxcal.

Usage

R_Simulate(c_dates, stds, names = seq_along(c_dates))

Arguments

c_dates

a vector containing the calendar dates that should be simulated
stds

a vector containing the standard deviation that should be simulated (length 1 or same length as c_dates)
names

a vector of names for the resulting simulated dates

Value

a string containing the respective Oxcal code

Reads the content of the Oxcal js output file

Description

Reads the content of the Oxcal js output file as vector of strings for each line.

Usage

readOxcalOutput(output_file)

Arguments

output_file

The path to a Oxcal js output file.

Value

The content of the Oxcal js output file as vector of strings for each line.

Author(s)

Martin Hinz

Returns the Oxcal code for Sequence

Description

Sequence takes a set of Phases or R_Dates as vectors, and returns a bit of oxcal code that can be used to feed it into OxCal. In this code the Phases and/or R_Dates are encapsulated in an OxCal Sequence. For details concerning the Oxcal simulation please consult the help page of Oxcal.

Usage

Sequence(sequence_elements, names = "")

Arguments

sequence_elements

a vector containing strings of OxCal code, usually consisting of Phase or R_Date commands, but any other code strings might be used that can be interpreted by OxCal within a Sequence
names

a optional vector of names for the resulting Sequences

Value

a string containing the respective Oxcal code

Setting the Oxcal program path for further use

Description

Stores the path to the oxcal executable it in internally for other functions.

Usage

setOxcalExecutablePath(path)

Arguments

path

The path to the Oxcal executable

Author(s)

Martin Hinz

Examples

## Not run: 
connectOxcal('/home/martin/Documents/scripte/OxCal/bin/OxCalLinux')

## End(Not run)

Wrap OxCal commands in Boundary commands

Description

wrap_in_boundaries takes a set of Phases or R_Dates as vectors, and returns a bit of oxcal code that can be used to feed it into OxCal. In this code the Phases and/or R_Dates are interleaved and wrapped in OxCal Boundaries, the number of Boundaries is equal to the number of strings + 1. The resulting string starts with a boundary, than the OxCal strings from the vector are interleaved with Boundary commands. For details concerning the Oxcal simulation please consult the help page of Oxcal.

Usage

wrap_in_boundaries(phases_strings, boundary_names = NA, collapse = FALSE)

Arguments

phases_strings

a vector containing strings of OxCal code, usually consisting of Phase or R_Date commands, but any other code strings might be used that can be interpreted by OxCal inbetween a Boundary
boundary_names

a optional vector of names for the resulting Boundaries (length of phases_strings + 1). If not given, the boundaries are named with consecutive numbers.
collapse

if TRUE, return a single string; if FALSE (default), return a character vector (backwards compatible)

Value

OxCal code (character vector or single string depending on collapse)