Basic Usage

In oxcAAR: Interface to 'OxCal' Radiocarbon Calibration

The package oxcAAR is designed to represent an interface between R and Oxcal. It offers the possibility to parse Oxcal scripts from data within R, execute them and reread the results from the Oxcal output files. There are other packages that can also calibrate ¹⁴C data, like eg. Bchron, which will be sufficient and probably also faster than using oxcAAR. But this package is intended to use especially the algorithms of Oxcal, which is a quasi-standard for archaeological research these days.

Calibration (R_Date)

Lets assume we want to calibrate the date 5000 BP +- 25 years. oxcAAR has the function oxcalCalibrate for doing so. But at first we have to load the package and tell it where to find the local path to the Oxcal distribution. Afterwards you can calibrate the date using bp, std and name.

library(ggplot2)
library(oxcAAR)
quickSetupOxcal()
#setOxcalExecutablePath("~/OxCal/bin/OxCalLinux")
my_date <- oxcalCalibrate(5000,25,"KIA-12345")
my_date
plot(my_date)

You can also calibrate multiple dates at once:

my_uncal_dates <- data.frame(bp=c(5000,4500,4000),
                             std=c(45,35,25),
                             names=c("Date 1", "Date 2", "Date 3")
                             )
my_cal_dates <- oxcalCalibrate(my_uncal_dates$bp, my_uncal_dates$std, my_uncal_dates$names)
my_cal_dates
plot(my_cal_dates)

And you might like to plot them on the calibration curve:

calcurve_plot(my_cal_dates)

The resulting object from the calibration is a list of class oxcAARCalibratedDatesList, containing elements of class oxcAARCalibratedDate. Each of these dates is again a list of the essential informations of the calibrated date including the raw probabilities, which can be extracted for additional analysis:

str(my_cal_dates, max.level = 1)
my_cal_dates[[1]] # equivalent to my_cal_dates[["Date 1"]] or my_cal_dates$`Date 1`
str(my_cal_dates$`Date 1`)
plot(
  my_cal_dates$`Date 1`$raw_probabilities$dates,
  my_cal_dates$`Date 1`$raw_probabilities$probabilities,
  type = "l",
  xlab = "years",
  ylab = "probs"
  )

Simulation (R_Simulate)

You can also use oxcAAR to simulate ¹⁴C dates the same way as the OxCal R_Simulate function works. You enter a calibrated year (1000 for 1000 AD, -1000 for 1000 BC) and OxCal will simulate a BP value using a bit of randomisation. Resulting in the fact that each run will have a slightly different BP value.

my_cal_date <- data.frame(bp=c(-3400),
                             std=c(25),
                             names=c("SimDate_1")
                             )
my_simulated_dates <- oxcalSimulate(my_cal_date$bp,
                                    my_cal_date$std,
                                    my_cal_date$names
                                    )
# equivalent to
my_simulated_dates <- oxcalSimulate(-3400, 25, "SimDate_1")
my_simulated_dates
plot(my_simulated_dates)

Simulate Sum Calibration

This package was originally intended to support a series of articles dealing with the investigation of sum calibration. This is why a function is implemented to simulate sum calibration. You can use it to simulate a series of ¹⁴C dates and explore the sum calibrated results. You can specify the beginning and end of the time span that should be used for the simulation (in calendar years), the number of ¹⁴C dates that should be simulated, their standard deviation, either as vector of length n or as one number for all dates, and the type of distribution that should be used (either equally spaced in time, or random uniform). The result is again of class oxcAARCalibratedDate so you can access the raw probabilities for further analysis.

my_sum_sim<-oxcalSumSim(
  timeframe_begin = -4000,
  timeframe_end = -3000,
  n = 50,
  stds = 35,
  date_distribution = "uniform"
  )
str(my_sum_sim)
plot(my_sum_sim)

Execute custom OxCal code

You can also use the package to execute your own OxCal code from within R, and import the results back into the workspace. You can use R_Date, R_Simulate and oxcal_Sum to produce that OxCal code:

library(knitr)
hook_output <- knit_hooks$get("output")
knit_hooks$set(output = function(x, options) {
   lines <- options$output.lines
   if (is.null(lines)) {
     return(hook_output(x, options))  # pass to default hook
   }
   x <- unlist(strsplit(x, "\n"))
   more <- "..."
   if (length(lines)==1) {        # first n lines
     if (length(x) > lines) {
       # truncate the output, but add ....
       x <- c(head(x, lines), more)
     }
   } else {
     x <- c(more, x[lines], more)
   }
   # paste these lines together
   x <- paste(c(x, ""), collapse = "\n")
   hook_output(x, options)
 })

R_Simulate(-4000, 25, "MySimDate")
my_dates <- R_Date(c("Lab-12345","Lab-54321"), c(5000,4500), 25)
cat(my_dates)
my_sum <- oxcal_Sum(my_dates)
cat(my_sum)

or use your own script as string variable.

knitr::opts_chunk$set(cache=TRUE)
my_oxcal_code <- ' Plot()
 {
  Sequence("Sequence1")
  {
   Boundary("Beginn");
   Phase("Phase1")
   {
    R_Date("Lab-1",5000,25);
    R_Date("Lab-2",4900,37);
   };
   Boundary("Between");
   Phase("Phase2")
   {
    R_Date("Lab-3",4800,43);
   };
   Boundary("End");
  };
 };'
my_result_file <- executeOxcalScript(my_oxcal_code)
my_result_text <- readOxcalOutput(my_result_file)

You can either parse the result to a 'standard' oxcAAR object:

my_result_data <- parseOxcalOutput(my_result_text)
str(my_result_data)
print(my_result_data)

Or you get the whole output of Oxcal as object:

my_result_data <- parseFullOxcalOutput(my_result_text)
str(my_result_data)

oxcAAR documentation built on July 6, 2021, 1:06 a.m.