MATLAB scripts to produce OxCal chronologies for SISAL database (scripts V1)

These MATLAB scripts are developed for creating OxCal (Bronk Ramsey 2009) age models for a large number of speleothems from SISAL database. These scripts are created using MATLAB 2019 and are designed to work with current version of OxCal (4.3).

These scripts have been tested with SISALv2 (UoR link (https://doi.org/10.17864/1947.242), Comas-Bru et al 2020 (under review, https://doi.org/10.5194/essd-2020-39)). In order to assure traceability, any presentation, report, or publication that uses the automated OxCal scripts should cite ZENODO, UoR LINK and Database paper. These scripts are licensed by the rights-holder(s) under a Creative Commons Attribution 4.0 International Licence: https://creativecommons.org/licenses/by/4.0/.

A short description of all steps and the scripts and functions involved in each step are given below. For more detailed instructions and examples please read the Introduction, Notes, Instructions and naming conventions sections at the beginning of each MATLAB code (*.m file). For questions please contact sahar.amirnejad@gmail.com.

STEP 1) creating the input files for OxCal using script "SISAL_1_OxCal_Input_Generator_v1.m"
This script queries the SISAL database, removes records that are not suitable for creating age models and cleans the data. Then it translates the chronological data from SISAL database format into the Chronological Query Language (CQL2) notation of OxCal and writes them into an OxCal input file which is named by the entity ID (EID) from SISAL database (EID.oxcal).

STEP 2) running the OxCal program for all the oxcal input files that were created in the previous step using "SISAL_2_OxCal_cmdline_batch_executor_v1.m"
This script makes a list of all the *.oxcal files in the given directory and runs the OxCalWin.exe (available for download from https://c14.arch.ox.ac.uk/oxcal.html) for all of them. This step results in 4 other files for each entity:
    -EID.log which contains a text version of the output
    -EID.txt - which contains a tab delimited tabular output
    -EID.js - which is the ECMA-Script encoded version of the output used by the OxCal output viewer and the code in step 3
    -ensembles_EID.csv - which is the age ensemble for that entity

STEP 3) extracting the age depth model and quality metrics from V.js file using script "SISAL_3_OxCal_Output_Extractor_v1.m" and function "grep.m" (available for download from https://www.mathworks.com/matlabcentral/fileexchange/9647-grep-a-pedestrian-very-fast-grep-utility)
This script extracts all the necessary data and metadata of the age depth model from all the *.js files and tabulates and reports them. It also interpolates the age depth model for the isotope depths for each entity from SISAL database to produce the proxy chronologies. This script can also produce age depth plots and isotope timeseries plots for each entity for comparison of SISAL OxCal chronologies with the original chronologies.

STEP 4) extracting and post-processing the ensemble files ensembles_EID.csv using script "SISAL_4_OxCal_ensemble_interpolator_v1.m" and function "ensembleseader0.m"
This step is only necessary for extraction of ensembles.
This script reads the ensemble file for each entity, trims it to keep only the last 2000 iterations, corrects the age reference from CE/BCE back to BP (where present is 1950 CE)  and then interpolates the age depth model for the isotope depths.