Type: | Package |
Title: | Interface to 'OxCal' Radiocarbon Calibration |
Version: | 1.1.1 |
Date: | 2021-06-06 |
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. |
License: | GPL-2 | file LICENSE |
Imports: | stringi, stringr, jsonlite |
Suggests: | knitr, testthat, rmarkdown, ggplot2, ggridges, methods |
VignetteBuilder: | knitr |
RoxygenNote: | 7.1.1 |
Encoding: | UTF-8 |
NeedsCompilation: | no |
Packaged: | 2021-07-05 16:51:43 UTC; martin |
Author: | Hinz Martin [aut, cre], Clemens Schmid [aut], Daniel Knitter [aut], Carolin Tietze [aut] |
Maintainer: | Hinz Martin <martin.hinz@iaw.unibe.ch> |
Repository: | CRAN |
Date/Publication: | 2021-07-05 17:20:02 UTC |
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
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
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
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
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)
Arguments
oxcal_script |
A string containing the Oxcal commands that should be processed. |
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'
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 |
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
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.
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:
|
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)
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
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