User’s manual

The current version of IOSACal is in beta state (i.e. suitable for experimental production use), but has already all the basic functionality, like calibration, generation of publication-quality plots and determination of probability intervals.

Basic usage

The command line program is called iosacal. It can generate both text output and image plots.

The typical usage is:

$ iosacal -d 7505 -s 93 --id "P-769"

Output will look like the following:

# P-769

Calibration of P-769: 7505 ± 93 BP

## Calibrated age

Atmospheric data from Reimer et al (2013);

### 68.2% probability

* 8392 CalBP ‒ 8284 CalBP (45.6%)
* 8264 CalBP ‒ 8205 CalBP (22.3%)

### 95.4% probability

* 8516 CalBP ‒ 8493 CalBP (1.1%)
* 8480 CalBP ‒ 8157 CalBP (92.7%)
* 8115 CalBP ‒ 8114 CalBP (0.1%)
* 8089 CalBP ‒ 8058 CalBP (1.5%)

----

IOSACal v0.3

If you want an image instead of text output, just add the -p flag:

$ iosacal -d 7505 -s 93 --id "P-769" -p

The result will be saved into the image file named P-769_7505_93.pdf in the same directory. It will look more or less like this:

_images/P-769_7505_93.png

Other calibration curves

By default, iosacal uses the IntCal13 calibration curve. IOSACal is however able to read any calibration curve that uses the same format as intcal13.14c, like those available on <http://www.radiocarbon.org/>. If you want to specify a different calibration curve provide the canonical name of the curve in lower case (e.g. intcal09, marine09).

To specify a calibration curve, use the -c command line option:

$ iosacal -d 7505 -s 93 --id "P-769" -p -c intcal04

Please note that IOSACal already includes the calibration curves listed below:

  • IntCal13
  • Marine13
  • ShCal13
  • IntCal09
  • Marine09
  • IntCal04
  • Marine04
  • ShCal04
  • IntCal98
  • Marine98

Multiple dates

It is also possible to give IOSACal more than one radiocarbon determination, to see how 2 or more samples relate between themselves.

To use the multiple dates feature, just pass multiple -d, -s and --id options on the command line:

$ iosacal \
  -d 7729 -s 80 --id "P-1365" \
  -d 7661 -s 99 --id "P-1375" \
  -d 7579 -s 86 --id "P-827" \
  -d 7572 -s 92 --id "P-772" \
  -d 7538 -s 89 --id "P-778" \
  -d 7505 -s 93 --id "P-769" \
  -p -m -n "Catalhöyük East level VI A"

The order in which values are passed to IOSACal matters, so the first date will be matched to the first standard deviation and so on.

This way, you will get 6 different single plots. The -m flag is used to indicate you want a compound plot. It’s also useful to use the -n option to give a name to the image and a title to the plot.

The resulting compound plot looks like this:

_images/catalhuyuk-level6a.png

Warning

Currently IOSACal doesn’t perform any Bayesian matching of calibrated ages. This feature will be added in future versions.

Command line options

IOSACal works from the command line. These are the available options.

-h

Show an help message and exit

-d <date>, --date=<date>

Conventional radiocarbon age, i.e. the non-calibrated radiocarbon BP date for the sample

-s <sigma>, --sigma=<sigma>

Error at 1 standard deviation for the non-calibrated date given with the above option.

--id <sample_id>

Lab ID of the sample, e.g. P-1244, OxA-3311 or BETA-248559

-c <curve>, --curve=<curve>

Calibration curve to be used [default: intcal13]

If you want to specify a different calibration curve provide the curve canonical name in lower case (e.g. intcal09, marine13).

Plot output

-p, --plot

Enables the graphical plot output.

-o, --oxcal

Plots will be more similar to OxCal [default: False]

-n <name>, --name <name>

Specify a name for the output plot [default: “iosacal”]

-1, --single

Generate single plots for each sample. The default action.

--no-single

Don’t generate single plots for each sample.

-m, --stacked

Generate stacked plot with all samples.

BP or calendar dates

Use these mutually exclusive options to choose which type of dates you like as output.

--bp

Express date in Calibrated BP Age (default action)

--ad

Express date in Calibrated BC/AD calendar Age

--ce

Express date in Calibrated BCE/CE calendar Age