MatCal: Open Source Bayesian 14C Age Calibration in Matlab

The matcal function provides radiocarbon (14C) age calibration in Matlab using the Bayesian highest posterior density (HPD). The function produces a probability distribution function (PDF) of calibrated ages, as well as 1 sigma (68.27%) and 2 sigma (95.45%) probability calibrated age credible intervals, calculated using HPD. Publication ready calibration plots are also produced, with the option to save to disk. Calibration output can be in either Cal BP or BCE/CE (BC/AD), and a reservoir age can be specified if necessary. The user can choose from a number of calibration curves, including the latest version of IntCal.


Introduction
Radiocarbon ( 14 C) age calibration is a necessary process for estimating the true age range of a 14 C determination. Atmospheric 14 C activity (Δ 14 C) has not been constant throughout history, due to changes in the rate of 14 C production in the upper atmosphere, as well as changes in the Earth's carbon cycle. Simply knowing the 14 C activity of a given sample and applying the half-life of 14 C is, therefore, in itself not sufficient to determine the true age range; one must also have knowledge of past Δ 14 C.
Reconstructions of past Δ 14 C have been carried out using independently dated terrestrial archives, including tree-ring, speleothem and lake records. Additionally, independently dated marine archives have also been used to indirectly reconstruct past Δ 14 C. The aforementioned Δ 14 C records can be combined to produce what is known as a calibration curve, a continuous record of past atmospheric 14 C activity. The most commonly used calibration curves are produced by the IntCal group of scientists, the most recent versions of which were published in 2013 [1,2]. The latest calibration curves are IntCal13 (a global atmospheric calibration curve), SHCal13 (a southern hemisphere atmospheric calibration curve) and Marine13 (a calibration curve for the surface mixed layer of the global oceans). All calibration curves include a 1 sigma uncertainty range of possible 14 C ages ( 14 C yr BP) corresponding to a certain true age, or calibrated age (Cal yr BP). 14 C age determinations produced by radiocarbon laboratories are given in the form of a normal (Gaussian) distribution, whereby mean and 1 sigma values for the 14 C age are reported. The age calibration process involves using the shape of the calibration curve and its associated 1 sigma value to produce a probable calibrated age range for the 14 C age determination. A number of software tools offering 14 C calibration functionality have been authored and are widely used by researchers. Two of the most widely used such tools are the standalone calibration programs Calib [3] and the age modelling software OxCal [4]. Additionally, 14 C calibration routines are built into the R-based, open source age modelling software packages Clam [5] and Bacon [6]. More recently, a Python-based, open source 14 C age calibration script (IOSACal) has also been written [7].
Many researchers within geosciences and archaeology make use of Matlab when analysing data. Some of these researchers also carry out 14 C determinations as part of their work. MatCal provides a 14 C calibration function that can easily be implemented into a Matlab-based workflow.

Implementation and architecture
The first methods used for 14 C age calibration, including in the earliest versions of Calib, involved using the so called 'intercept method', where one essentially uses the calibration curve as a lookup table to find the calibration curve values directly associated with median, 1 sigma and 2 sigma values of the normal distribution of the 14 C age determination. Later, OxCal [4] and BCal [8] pioneered 14 C age calibration by using the normal distribution of the 14 C age determination and the 1 sigma range of the calibration curve to calculate a probability density function (PDF) of calibrated ages, which is subsequently analysed using the Bayesian highest posterior density (HPD) method, resulting in a superior calibrated age range determination [9]. MatCal also employs HPD analysis of a PDF.
The matcal function loads a chosen calibration curve into the Matlab workspace and then linearly interpolates the full range of calibration curve calibrated years to annual resolution. Following Bronk Ramsey [10], an age probability (P) is calculated (Eq. 1) for each annual calibrated year (t), where the normal distribution of the 14 C age determination is represented by D ± σ D (input variables c14age and c14err), and the calibration curve 14 C age for each calibrated year (t) is represented as f(t) ± σ f (t). Both the calibration curve 14 C data and the user inputted 14 C data are converted to F14C space when calculating P(t), which is a more suitable approach, especially for older ages [10].

Equation 1:
A resulting n by 2 array containing calibrated years and associated probabilities (normalised to between zero and one) is subsequently analysed using the Bayesian highest posterior density (HPD) method in order to calculate the calibrated age probability range associated with the 1 sigma (68.27%) and 2 sigma (95.45%) confidence levels (CL). Specifically, the HPD method is implemented as follows: the aforementioned n by 2 array is sorted by probability, after which a cumulative P is calculated. All calibrated years with a cumulative probability falling between 1-CL and 1 are subsequently selected and sorted by calibrated year, after which all continuous annual intervals of calibrated years represent the discrete HPD confidence intervals. The probability associated with each HPD interval is determined by taking the sum of the probability for all calibrated years within the interval itself. All relevant information is also plotted in a Matlab figure with handle '14' (Figure 1).
It is also possible to include a reservoir age (R(t) or ΔR) and reservoir age uncertainty (σ R ) when calibrating a 14 C determination, using the input variables resage and reserr. Reservoir age is applied before the calibration  MatCal has been tested against the two most commonly used 14 C calibration tools, the aforementioned Calib and Oxcal ( Table 1). MatCal is found to agree very well with both tools. The very minor differences are most likely due to the slightly different methods used to interpolate the calibration curve. OxCal, for example, interpolates the calibration curve to sub-annual resolution, whereas MatCal interpolates to annual resolution. Seeing as the pre-bomb calibration curves are published in five and ten year resolution, an equal case can be made to apply either annual or sub-annual interpolation. It can be noted that both MatCal and OxCal provide superior calibration for the very oldest dates and/or dates with very large uncertainty, due to the calculation of calibrated age probability in F14C space. Further quality control has been carried out for Matlab in the form of user testing, which has led to the implementation of a number of error and warning messages. For example, if the user attempts to calibrate a 14 C age which produces a calibrated age PDF partially exceeding the range of the chosen calibration curve (e.g. <0 cal yr BP or >50000 cal yr BP in the case of IntCal13), a warning message is returned to the command window and also displayed on any subsequent output plots. Furthermore, user interpretable error messages are returned when, for example, an invalid calibration curve name is selected or if invalid and/or not enough input parameters are set.

Operating system
Any system capable of running Matlab R2012a or higher.

Programming language
Tested as working in Matlab R2012a, likely to work in earlier versions also.

Additional system requirements
Unknown.

Dependencies
The MatLab plotting toolbox is required if the user decides to make use of the plotting functions.

List of contributors
Bryan C. Lougheed (wrote 14 C calibration routine, plotting module and manuscript) Stephen P. Obrochta (wrote input parser and rewrote parts of code to increase compatibility across multiple Matlab versions)

Software location
Archive (e.g. institutional repository, general repository) (required -please see instructions on journal website for depositing archive copy of software in a suitable repository) Name:  (p68_2 and p95_4) outputs are also ideal for implementation within a geochronological age modelling routine, e.g. Monte Carlo techniques.