# IOSACal: open source radiocarbon calibration#

IOSACal is an open source tool for radiocarbon calibration. It has a command-line program:

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

which also creates nice plots like this:

```from iosacal import R, iplot
r = R(7505, 93, 'P-769')
cal_r = r.calibrate('intcal20')
iplot(cal_r)
``` The same features are available as a Python 3 library:

```from iosacal import R
from iosacal.text import single_text
r = R(7505, 93, 'P-769')
cal_r = r.calibrate('intcal20')
print(single_text(cal_r))
```
```# P-769

Calibration of P-769: 7505 ± 93 BP

## Calibrated age

Atmospheric data from Reimer et al (2020)

### 68.2% probability

* 8386 CalBP - 8283 CalBP (42.1%)
* 8266 CalBP - 8199 CalBP (26.0%)

### 95.4% probability

* 8515 CalBP - 8500 CalBP (0.8%)
* 8457 CalBP - 8163 CalBP (89.7%)
* 8137 CalBP - 8116 CalBP (1.0%)
* 8102 CalBP - 8039 CalBP (3.9%)

----

IOSACal v0.6.0
```

Multiple determinations from the same event can be checked for consistency and combined:

```from iosacal import R, combine
from iosacal.text import single_text

r1 = R(4430, 100, 'Birm-637')
r2 = R(4430, 120, 'Birm-638')
r3 = R(4400, 100, 'Birm-639')
r4 = R(4350, 130, 'Birm-636')
r_combined = combine([r1, r2, r3, r4])
print(r_combined)
```
```RadiocarbonSample( Combined from Birm-637, Birm-638, Birm-639, Birm-636 with test statistic 0.287 : 4406 ± 55 )
```
```r_combined_cal = r_combined.calibrate('intcal13')
print(single_text(r_combined_cal))
```
```# Combined from Birm-637, Birm-638, Birm-639, Birm-636 with test statistic 0.287

Calibration of Combined from Birm-637, Birm-638, Birm-639, Birm-636 with test statistic 0.287: 4406.465763017056 ± 55.163983474505095 BP

## Calibrated age

Atmospheric data from Reimer et al (2013);

### 68.2% probability

* 5210 CalBP - 5203 CalBP (2.2%)
* 5047 CalBP - 4870 CalBP (65.8%)

### 95.4% probability

* 5280 CalBP - 5164 CalBP (19.3%)
* 5135 CalBP - 5105 CalBP (3.6%)
* 5077 CalBP - 4855 CalBP (72.5%)

----

IOSACal v0.6.0
```

Radiocarbon determinations can be simulated for known calendar dates and expected measurement error to test hypotheses and models:

```from iosacal import R, combine, simulate
from iosacal.text import single_text
r1 = simulate(710, 28, 'Heid.inv. Arab. 2 (target 1)', 'intcal20')
r2 = simulate(710, 28, 'Heid.inv. Arab. 2 (target 2)', 'intcal20')
r3 = simulate(710, 28, 'Heid.inv. Arab. 2 (target 3)', 'intcal20')
r_combined = combine([r1, r2, r3])
print(r_combined)
```
```RadiocarbonSample( Combined from Heid.inv. Arab. 2 (target 1), Heid.inv. Arab. 2 (target 2), Heid.inv. Arab. 2 (target 3) with test statistic 1.108 : 758 ± 16 )
```
```r_combined_cal = r_combined.calibrate('intcal20')
print(single_text(r_combined_cal, BP='ce'))
```
```# Combined from Heid.inv. Arab. 2 (target 1), Heid.inv. Arab. 2 (target 2), Heid.inv. Arab. 2 (target 3) with test statistic 1.108

Calibration of Combined from Heid.inv. Arab. 2 (target 1), Heid.inv. Arab. 2 (target 2), Heid.inv. Arab. 2 (target 3) with test statistic 1.108: 758.3333333333334 ± 16.165807537309522 BP

## Calibrated age

Atmospheric data from Reimer et al (2020)

### 68.2% probability

* CE 1266 - CE 1277 (66.9%)

### 95.4% probability

* CE 1230 - CE 1244 (10.9%)
* CE 1257 - CE 1281 (83.2%)

----

IOSACal v0.6.0
```

IOSACal can be used interactively with Jupyter Notebook (formerly known as IPython Notebook). This page is generated by a Jupyter notebook! This page is generated from a Jupyter Notebook1.

## Why another 14C calibration software ?#

Most available programs for radiocarbon calibration, like OxCal, CALIB and others, are freeware. You don’t have to pay for them, but on the other side you’re not free to modify them as you need, nor to access and study the source code.

This is the main motivation behind IOSACal: creating a free-as-in-freedom radiocarbon calibration software, with a clean programming library, that enables experiments and integration in existing archaeological information systems.

Furthermore, writing this software from scratch is an alternative way of learning how 14C calibration works, not only in strict mathematical terms, but also from a practical point of view.

# Can I use IOSACal for my research?#

Yes, IOSACal has been used in research projects with large numbers of radiocarbon dates like Antarctica Marine Radiocarbon and the IPHES PALEODEOM project.

Using IOSACal with Jupyter Notebooks is ideal for reproducible research that can be easily shared.

Furthermore, it takes little effort to customize and adapt the existing code to your specific needs.

IOSACal is reasonably fast, especially for batch processing.

If you make use of IOSACal in your work, please cite it with the IOSACal Zenodo record.

This helps us get some recognition for creating and maintaining this software free for everyone.

1

This notebook can be downloaded as `index.ipynb`.