Intro to OxCal in geoChronR

Nick McKay

2024-09-11

Source: vignettes/oxCal.Rmd

Use oxCal to create an age model

Setting up oxCal

The oxcAAR package provides efficient access from R to the oxCal executables, which will need to be set up on your computer before you can use it. Once it’s installed you won’t need to repeat this step, just point to where it’s installed. If it’s already installed, it will tell you.

quickSetupOxcal(path = "~/OxCal")
#> Oxcal doesn't seem to be installed. Downloading it now:
#> Oxcal stored successful at /Users/runner/OxCal!
#> Oxcal path set!
#> NULL

OK, let’s get a LiPD file from the LinkedEarth Wiki:

L <- readLipd("https://lipdverse.org/geoChronR-examples/BJ8-03-70GGC.Linsley.2010.lpd")
#> [1] "Loading 1 datasets from /var/folders/py/lcjn3y352g1106vf1rqk521r0000gn/T//Rtmp33LPOE/BJ8-03-70GGC.Linsley.2010.lpd..."
#> [1] "reading: BJ8-03-70GGC.Linsley.2010.lpd"

Now we can run it through oxcal. First, we specify our oxcal path, then use the runOxcal function. Like the other run{AgeModel} functions in geoChronR, you can leave the parameters empty and specify the choicecs interactively, or you can specify everything for replicability. For choosing the variable names, if you did it interactively and would like to recall those choices, try the getLastVarString function.

Here, in addition to the variable choices, there are a few key parameters to note. First, we specify a “static” reservoir age and uncertainty. You can use this if you want to apply the same deltaR (and uncertainty) to all the ages. Alternatively, these can be columns in the chron measurement tables.

Also, note that we’ve specified the surface age and uncertainty, as that was not included in the measurent table.

Finally, there are two more key parameters, the depth.interval and the events.per.unit.length. These have a substantial impact the output. The depth.interval controls the spacing at which to calculate the age model uncertainty distributions, and the events.per.unit.length is the key parameter for the poisson distribution. As the number events increases, the modeled sequence will become more monitonic (linear) between ages. If you’re having trouble getting OxCal to produce a valid model for your sequence, tinker with these two parameters. Fewer events.per.unit.length and a larger depth.interval will increase the flexibility of the model and likelihood of convergence.

Optionally, you can set events.per.unit.length.uncertainty to a positive number to indicate a prior uncertainty estimate (in orders of magnitude) on events.per.unit.length. This will tell OxCal to treat events.per.unit.length as a variable and optimize it to fit the data. This often returns better results, especially in the absence of an informed prior on events.per.unit.length, but greatly increases the run time (expect a run to take multiple hours).

L <- runOxcal(L,
              lab.id.var = 'id', 
              age.14c.var = 'age14c', 
              age.14c.uncertainty.var = 'age14cuncertainty', 
              age.var = 'calendarage', 
              age.uncertainty.var = 'calendarageuncertainty', 
              depth.var = 'depth', 
              reservoir.age.14c.var = NULL, 
              reservoir.age.14c.uncertainty.var = NULL, 
              rejected.ages.var = NULL,
              static.reservoir.age = 70,
              static.reservoir.age.unc = 50,
              cal.curve = "intcal20",
              oxcal.path = "~/OxCal",
              surface.age = 0,
              surface.age.unc = 25,
              depth.interval = 10,
              events.per.unit.length = .1)
#> Looking for laboratory ID 
#> [1] "Found it! Moving on..."
#> Looking for radiocarbon ages 
#> [1] "Found it! Moving on..."
#> Looking for 1-sigma radiocarbon age uncertainty (+/-) 
#> [1] "Found it! Moving on..."
#> Looking for calibrated/calendar ages 
#> [1] "Found it! Moving on..."
#> Looking for 2-sigma calibrated age uncertainty (+/-) 
#> [1] "Found it! Moving on..."
#> Looking for depth or position 
#> [1] "Found it! Moving on..."
#> Looking for radiocarbon reservoir age offsets (deltaR) 
#> radiocarbon reservoir age offsets (deltaR) does not seem to exist, moving on.
#> Looking for radiocarbon reservoir age offsets (deltaR) uncertainties 
#> radiocarbon reservoir age offsets (deltaR) uncertainties does not seem to exist, moving on.
#> Looking for rejected ages 
#> rejected ages does not seem to exist, moving on.
#> [1] "Variable choices for reuse..."
#> For future reference: here are the options you chose:
#>  Find later with getLastVarString()
#> lab.id.var = 'id', age.14c.var = 'age14c', age.14c.uncertainty.var = 'age14cuncertainty', age.var = 'calendarage', age.uncertainty.var = 'calendarageuncertainty', depth.var = 'depth', reservoir.age.14c.var = NULL, reservoir.age.14c.uncertainty.var = NULL, rejected.ages.var = NULL, 
#> Oxcal is now running, depending on your settings and your computer, this may take a few minutes to several hours. The model is complete when a table of model diagnostics appears.
#> [1] "OxCal v4.4.4 Bronk Ramsey (2021); r:5\nAtmospheric data from Reimer et al (2020)\n405.5\n400\n393.5\n390\n380\n370\n361.5\n360\n350\n340\n330\n320.5\n320\n310\n300\n290\n280\n270\n260\n250\n241.5\n240\n230\n220\n210\n201.5\n200\n190\n180\n176\n170\n160\n150\n140\n130\n120\n110\n104\n100\n90\n80\n70\n63.5\n60\n50\n40\n30\n20\n10\n0\nWarning! Duplicate names - Atmospheric\nWarning! Duplicate names - Atmospheric\nWarning! Duplicate names - Atmospheric\nBoundary()\nAtmospheric Curve(IntCal20.14c)\nAtmospheric data from Reimer et al (2020)\nOS-45436 R_Date(12900,45)\n  68.3% probability\n    13563BC (68.3%) 13372BC\n  95.4% probability\n    13644BC (95.4%) 13310BC\nD \nAtmospheric Curve(IntCal20.14c)\nAtmospheric data from Reimer et al (2020)\nOS-65581 R_Date(12550,50)\n  68.3% probability\n    13106BC (59.4%) 12886BC\n    12728BC ( 8.9%) 12677BC\n  95.4% probability\n    13180BC (71.0%) 12847BC\n    12774BC (24.5%) 12560BC\nD \nD \nD \nAtmospheric Curve(IntCal20.14c)\nAtmospheric data from Reimer et al (2020)\nOS-60748 R_Date(10250,40)\n  68.3% probability\n    10049BC (58.3%) 9922BC\n    9912BC ( 9.9%) 9884BC\n  95.4% probability\n    10480BC ( 2.0%) 10450BC\n    10217BC ( 0.4%) 10206BC\n    10192BC ( 0.6%) 10176BC\n    10154BC (91.3%) 9864BC\n    9832BC ( 1.0%) 9811BC\nD \nD \nD \nD \nAtmospheric Curve(IntCal20.14c)\nAtmospheric data from Reimer et al (2020)\nOS-60737 R_Date(7190,45)\n  68.3% probability\n    6076BC (68.3%) 6010BC\n  95.4% probability\n    6217BC (10.2%) 6139BC\n    6096BC (83.9%) 5982BC\n    5940BC ( 1.3%) 5928BC\nD \nD \nD \nD \nAtmospheric Curve(IntCal20.14c)\nAtmospheric data from Reimer et al (2020)\nOS-54154 R_Date(6160,60)\n  68.3% probability\n    5208BC (68.3%) 5040BC\n  95.4% probability\n    5298BC ( 4.5%) 5258BC\n    5221BC (91.0%) 4941BC\nD \nD \nD \nAtmospheric Curve(IntCal20.14c)\nAtmospheric data from Reimer et al (2020)\nOS-60750 R_Date(5410,35)\n  68.3% probability\n    4330BC (68.3%) 4249BC\n  95.4% probability\n    4346BC (85.2%) 4228BC\n    4196BC ( 7.7%) 4166BC\n    4094BC ( 2.5%) 4070BC\nD \nD \nD \nD \nAtmospheric Curve(IntCal20.14c)\nAtmospheric data from Reimer et al (2020)\nOS-60747 R_Date(4850,40)\n  68.3% probability\n    3700BC ( 8.2%) 3684BC\n    3655BC (37.1%) 3626BC\n    3562BC (23.0%) 3533BC\n  95.4% probability\n    3708BC (14.5%) 3670BC\n    3660BC (81.0%) 3527BC\nD \nD \nD \nAtmospheric Curve(IntCal20.14c)\nAtmospheric data from Reimer et al (2020)\nOS-54153 R_Date(4240,50)\n  68.3% probability\n    2910BC (35.2%) 2861BC\n    2805BC (26.1%) 2754BC\n    2720BC ( 7.0%) 2703BC\n  95.4% probability\n    3004BC ( 0.8%) 2992BC\n    2928BC (43.7%) 2831BC\n    2822BC (49.6%) 2662BC\n    2652BC ( 1.4%) 2632BC\nD \nD \nD \nD \nD \nD \nD \nAtmospheric Curve(IntCal20.14c)\nAtmospheric data from Reimer et al (2020)\nOS-54152 R_Date(2750,50)\n  68.3% probability\n    964BC ( 1.5%) 961BC\n    930BC (66.8%) 826BC\n  95.4% probability\n    1006BC (95.4%) 810BC\nD \nD \nD \nD \nAtmospheric Curve(IntCal20.14c)\nAtmospheric data from Reimer et al (2020)\nOS-45435 R_Date(1310,30)\n  68.3% probability\n    664AD (29.2%) 689AD\n    698AD ( 3.2%) 701AD\n    742AD (35.9%) 772AD\n  95.4% probability\n    656AD (95.4%) 774AD\nD \nD \nD \nD \nD \nD \nsurface C_Date(1950,25)\n  68.3% probability\n    1923AD (68.3%) 1976AD\n  95.4% probability\n    1900AD (95.4%) 2000AD\nBoundary()\nMCMC_Sample()\n( P_Sequence \nP_Sequence(0.1)\n) P_Sequence \nWarning! No outlier model specified - use Outlier_Model()\nWarning! No outlier model specified - use Outlier_Model()\nWarning! No outlier model specified - use Outlier_Model()\nWarning! No outlier model specified - use Outlier_Model()\nWarning! No outlier model specified - use Outlier_Model()\nWarning! No outlier model specified - use Outlier_Model()\nWarning! No outlier model specified - use Outlier_Model()\nWarning! No outlier model specified - use Outlier_Model()\nWarning! No outlier model specified - use Outlier_Model()\nWarning! No outlier model specified - use Outlier_Model()\nWarning! No outlier model specified - use Outlier_Model()\nPosterior \n( MCMC(30000)\nOverall agreement 101.5%\nDynamic agreement 101.6%\nPosterior \n  68.3% probability\n    13541BC (68.3%) 13352BC\n  95.4% probability\n    13640BC (95.4%) 13292BC\nOS-45436 Posterior \n  68.3% probability\n    13541BC (68.3%) 13352BC\n  95.4% probability\n    13640BC (95.4%) 13292BC\n Agreement 100.0%\nD Posterior \n  68.3% probability\n    13452BC (68.3%) 13038BC\n  95.4% probability\n    13591BC (92.7%) 12849BC\n    12802BC ( 2.8%) 12712BC\nOS-65581 Posterior \n  68.3% probability\n    13118BC (63.6%) 12884BC\n    12721BC ( 4.7%) 12692BC\n  95.4% probability\n    13188BC (73.4%) 12843BC\n    12776BC (22.0%) 12566BC\n Agreement 101.8%\nD Posterior \n  68.3% probability\n    13101BC (68.3%) 12496BC\n  95.4% probability\n    13186BC (95.4%) 11522BC\nD Posterior \n  68.3% probability\n    12630BC (67.8%) 11092BC\n    11074BC ( 0.5%) 11062BC\n  95.4% probability\n    12934BC (95.4%) 10356BC\nD Posterior \n  68.3% probability\n    11050BC (68.3%) 9952BC\n  95.4% probability\n    12098BC (95.4%) 9892BC\nOS-60748 Posterior \n  68.3% probability\n    10049BC (58.5%) 9921BC\n    9912BC ( 9.8%) 9884BC\n  95.4% probability\n    10480BC ( 1.8%) 10450BC\n    10368BC ( 0.2%) 10364BC\n    10219BC ( 1.7%) 10172BC\n    10154BC (90.5%) 9861BC\n    9836BC ( 1.3%) 9808BC\n Agreement 100.0%\nD Posterior \n  68.3% probability\n    10096BC (68.3%) 9807BC\n  95.4% probability\n    10488BC ( 1.8%) 10395BC\n    10378BC ( 0.5%) 10346BC\n    10310BC ( 0.4%) 10275BC\n    10244BC (92.8%) 9012BC\nD Posterior \n  68.3% probability\n    9946BC (68.3%) 8482BC\n  95.4% probability\n    10065BC (95.4%) 7225BC\nD Posterior \n  68.3% probability\n    8824BC ( 0.2%) 8818BC\n    8814BC (68.1%) 6896BC\n  95.4% probability\n    9542BC (95.4%) 6338BC\nD Posterior \n  68.3% probability\n    7252BC ( 0.3%) 7244BC\n    7236BC (68.0%) 6038BC\n  95.4% probability\n    8489BC (95.4%) 6005BC\nOS-60737 Posterior \n  68.3% probability\n    6080BC (68.3%) 6002BC\n  95.4% probability\n    6220BC (15.2%) 6124BC\n    6101BC (79.6%) 5982BC\n    5938BC ( 0.6%) 5930BC\n Agreement  97.6%\nD Posterior \n  68.3% probability\n    6082BC (68.3%) 5986BC\n  95.4% probability\n    6221BC (95.4%) 5888BC\nD Posterior \n  68.3% probability\n    6046BC (68.3%) 5687BC\n  95.4% probability\n    6142BC (95.4%) 5391BC\nD Posterior \n  68.3% probability\n    5812BC (68.3%) 5339BC\n  95.4% probability\n    5985BC (95.4%) 5164BC\nD Posterior \n  68.3% probability\n    5474BC (68.3%) 5100BC\n  95.4% probability\n    5756BC (95.4%) 5008BC\nOS-54154 Posterior \n  68.3% probability\n    5208BC (68.3%) 5041BC\n  95.4% probability\n    5298BC ( 4.4%) 5256BC\n    5224BC (91.0%) 4942BC\n Agreement 101.3%\nD Posterior \n  68.3% probability\n    5114BC (68.3%) 4760BC\n  95.4% probability\n    5200BC (95.4%) 4510BC\nD Posterior \n  68.3% probability\n    4870BC (68.3%) 4446BC\n  95.4% probability\n    5051BC (95.4%) 4316BC\nD Posterior \n  68.3% probability\n    4548BC (68.3%) 4266BC\n  95.4% probability\n    4830BC (95.4%) 4183BC\nOS-60750 Posterior \n  68.3% probability\n    4330BC (68.3%) 4251BC\n  95.4% probability\n    4350BC (86.8%) 4224BC\n    4200BC ( 6.9%) 4164BC\n    4122BC ( 0.2%) 4118BC\n    4094BC ( 1.5%) 4072BC\n Agreement 102.6%\nD Posterior \n  68.3% probability\n    4332BC (68.3%) 4236BC\n  95.4% probability\n    4346BC (95.4%) 4060BC\nD Posterior \n  68.3% probability\n    4271BC (68.3%) 3990BC\n  95.4% probability\n    4317BC (95.4%) 3796BC\nD Posterior \n  68.3% probability\n    4072BC (68.3%) 3738BC\n  95.4% probability\n    4218BC (95.4%) 3634BC\nD Posterior \n  68.3% probability\n    3826BC (68.3%) 3575BC\n  95.4% probability\n    4028BC (95.4%) 3538BC\nOS-60747 Posterior \n  68.3% probability\n    3696BC ( 2.2%) 3691BC\n    3654BC (34.0%) 3626BC\n    3576BC (32.0%) 3532BC\n  95.4% probability\n    3708BC (95.4%) 3525BC\n Agreement  98.3%\nD Posterior \n  68.3% probability\n    3696BC ( 3.3%) 3684BC\n    3655BC (31.6%) 3600BC\n    3586BC (33.4%) 3521BC\n  95.4% probability\n    3749BC ( 0.2%) 3740BC\n    3714BC (95.2%) 3277BC\nD Posterior \n  68.3% probability\n    3538BC (68.3%) 3072BC\n  95.4% probability\n    3636BC (95.4%) 2866BC\nD Posterior \n  68.3% probability\n    3037BC (68.3%) 2755BC\n  95.4% probability\n    3336BC (95.4%) 2672BC\nOS-54153 Posterior \n  68.3% probability\n    2912BC (39.6%) 2858BC\n    2805BC (24.2%) 2757BC\n    2718BC ( 4.4%) 2706BC\n  95.4% probability\n    3008BC ( 1.6%) 2984BC\n    2935BC (92.9%) 2662BC\n    2650BC ( 1.0%) 2634BC\n Agreement 102.4%\nD Posterior \n  68.3% probability\n    2898BC (68.3%) 2600BC\n  95.4% probability\n    2958BC (95.4%) 2196BC\nD Posterior \n  68.3% probability\n    2762BC (68.3%) 2218BC\n  95.4% probability\n    2876BC (95.4%) 1803BC\nD Posterior \n  68.3% probability\n    2528BC (68.3%) 1844BC\n  95.4% probability\n    2730BC (95.4%) 1473BC\nD Posterior \n  68.3% probability\n    2221BC (68.3%) 1500BC\n  95.4% probability\n    2517BC (95.4%) 1206BC\nD Posterior \n  68.3% probability\n    1865BC (68.3%) 1188BC\n  95.4% probability\n    2239BC (95.4%) 996BC\nD Posterior \n  68.3% probability\n    1486BC (68.3%) 956BC\n  95.4% probability\n    1908BC (95.4%) 867BC\nD Posterior \n  68.3% probability\n    1107BC (68.3%) 839BC\n  95.4% probability\n    1488BC (95.4%) 810BC\nOS-54152 Posterior \n  68.3% probability\n    930BC (68.3%) 820BC\n  95.4% probability\n    1010BC (95.4%) 806BC\n Agreement 101.8%\nD Posterior \n  68.3% probability\n    972BC (68.3%) 691BC\n  95.4% probability\n    1036BC ( 0.1%) 1031BC\n    1020BC (95.4%) 205BC\nD Posterior \n  68.3% probability\n    812BC (67.8%) 122BC\n    117BC ( 0.5%) 111BC\n  95.4% probability\n    906BC (95.4%) 346AD\nD Posterior \n  68.3% probability\n    232BC (68.3%) 526AD\n  95.4% probability\n    615BC (95.4%) 672AD\nD Posterior \n  68.3% probability\n    386AD (68.3%) 760AD\n  95.4% probability\n    142BC (95.4%) 773AD\nOS-45435 Posterior \n  68.3% probability\n    662AD (39.0%) 700AD\n    742AD (29.3%) 770AD\n  95.4% probability\n    653AD (95.4%) 774AD\n Agreement  98.6%\nD Posterior \n  68.3% probability\n    664AD (68.3%) 798AD\n  95.4% probability\n    650AD (95.4%) 1058AD\nD Posterior \n  68.3% probability\n    736AD (68.3%) 1084AD\n  95.4% probability\n    677AD (95.4%) 1370AD\nD Posterior \n  68.3% probability\n    894AD (68.3%) 1358AD\n  95.4% probability\n    770AD (95.4%) 1611AD\nD Posterior \n  68.3% probability\n    1132AD (68.3%) 1624AD\n  95.4% probability\n    926AD (95.4%) 1801AD\nD Posterior \n  68.3% probability\n    1411AD (68.3%) 1841AD\n  95.4% probability\n    1136AD (95.4%) 1928AD\nD Posterior \n  68.3% probability\n    1690AD (68.3%) 1958AD\n  95.4% probability\n    1386AD (95.4%) 1988AD\nsurface Posterior \n  68.3% probability\n    1924AD (68.3%) 1977AD\n  95.4% probability\n    1893AD (95.4%) 2008AD\n Agreement 100.5%\nPosterior \n  68.3% probability\n    1924AD (68.3%) 1977AD\n  95.4% probability\n    1893AD (95.4%) 2008AD\n) MCMC(4992000)\n"
#> It looks like youre MCMC_Sample parameters aren't large enough.

Great. After OxCal finishes running successfully, it will return this table showing some diagnostics of the MCMC statistics for the dated levels. If the table is empty, that’s a sure sign that there was an error in your run.

Now that the age model has been generated, you can plot your age model with plotChronEns, just like with the other methods.

plotChronEns(L)
#> [1] "Found it! Moving on..."
#> [1] "Found it! Moving on..."
#> [1] "plotting your chron ensemble. This make take a few seconds..."

To map the the age ensembles onto the proxy data, use mapAgeEnsembleToPaleoData:

L <- mapAgeEnsembleToPaleoData(L,age.var = "ageEnsemble")
#> [1] "BJ8-03-70GGC.Linsley.2010"
#> [1] "Looking for age ensemble...."
#> [1] "Found it! Moving on..."
#> [1] "Found it! Moving on..."
#> [1] "getting depth from the paleodata table..."
#> [1] "Found it! Moving on..."
#> mapAgeEnsembleToPaleoData created new variable ageEnsemble in paleo 1 measurement table 1
#> mapAgeEnsembleToPaleoData also created new variable ageMedian in paleo 1 measurement table 1

Finally, let’s select the ageEnsemble and the SST variables…

ageEns <- selectData(L,var.name = "ageEnsemble")
SST <- selectData(L,var.name = "SST")

And plot up the output.

plotTimeseriesEnsRibbons(X = ageEns, Y = SST) %>% 
  plotTimeseriesEnsLines(X = ageEns, Y = SST,n.ens.plot = 10)
#> Scale for x is already present.
#> Adding another scale for x, which will replace the existing scale.

It looks reasonable, so we can now proceed to use this ensemble like any other.

Happy modeling!