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.1
Built: 2025-02-11 05:28:21 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 Phases dates. If given, for each name a boundary is returned. If not given, one Boundary without name is returned.

Value

a string containing the respective Oxcal code

Plots calibrated dates on the calibration curve

Description

Plots calibrated dates on the calibration curve

Usage

calcurve_plot(
  x,
  dates_sigma_ranges = NULL,
  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 error bars ("two_sigma", "one_sigma" or "three_sigma")
uncal_range

logical. If TRUE (default), the plot contains error bars for the the uncalibrated age
cal_range

logical. If TRUE (default), the plot contains error bars for the the calibrated age

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

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

a variable

Value

true if x is a 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

a variable

Value

true if x is a oxcAARCalibratedDatesList, false otherwise

oxcAAR Calibrated Dates Object

Description

The function oxcAARCalibratedDate is used to create an object for a calibrated date.

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 ("R_Date", "R_Simulate", ...)
bp

a integer giving the BP value for the date
std

a integer giving the standard deviation for the date
cal_curve

a list containing information about the calibration curve (name, resolution, bp, bc, sigma)
sigma_ranges

a list of three elements (one, two, three sigma), each a data frame with start, end and probability giving
raw_probabilities

a data frame of dates and the related probabilities for each date
posterior_probabilities

a data frame of dates and the related posterior probabilities for each date
posterior_sigma_ranges

a list of three elements (one, two, three sigma), each a data frame with start, end and probability giving for the posterior probabilities

Value

an object of the class 'oxcAARCalibratedDate'

oxcAAR Calibrated Dates List

Description

A List of oxcAARCalibratedDate

Value

an object of the class 'oxcAARCalibratedDatesList'

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
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 = T)

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

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

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 = 1:length(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
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 Phases, one Phase for each string. 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)

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.

Value

a string containing the respective Oxcal code