.. IOSACal documentation master file, created by
   sphinx-quickstart on Mon Apr 20 12:42:29 2009.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

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::

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

.. image:: /images/P-769_7505_93.png

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('intcal13')
  >>> 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%)


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 can be `used interactively with Jupyter Notebook
<http://nbviewer.jupyter.org/urls/gitlab.com/iosa/iosacal/snippets/18122/raw>`_
(formerly known as IPython Notebook).

Install
-------

If you have Python 3 just::

  pip3 install iosacal

or get the source at https://codeberg.org/steko/iosacal

If none of the above makes sense, follow the :doc:`install` instructions.

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.

Features
--------

IOSACal takes a radiocarbon determination and outputs a calibrated age as a set
of probability intervals. A radiocarbon date is represented by a date in years
BP (before present, that is before 1950 AD) and a standard deviation, like
2430±170. The combination of these two values is a numerical representation of
a laboratory measure performed on the original organic material.

The main task of the calibration process is to convert this measure into a set
of calendar dates by means of a calibration curve. Users can choose whether
they want results as a plot, a short textual summary or both (the plot includes
the summary).

IOSACal reads calibration curves in the common ``.14c`` format used also by
other programs. Should you have calibration data in another format, it would be
easy to either convert them to that format or modify the source code of IOSACal
to adapt it to your needs.

IOSACal is based on current calibration methods, like those described in
[RAM2008]_.

.. [RAM2008] C. Bronk Ramsey, Radiocarbon dating: revolutions in
   understanding, Archaeometry 50,2 (2008) pp. 249–275
   http://dx.doi.org/10.1111/j.1475-4754.2008.00394.x

Can I use IOSACal for my research?
----------------------------------

Yes, IOSACal has been used in research projects with large numbers of radiocarbon
dates. 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.

The `web application`_ is ideal for quick checks on single radiocarbon
dates, and requires no registration.  Please note that the web
application may not be updated to the latest version of IOSACal.

.. _`web application`: http://iosacal.herokuapp.com/

If you make use of IOSACal in your work, please cite it with the appropriate
reference [IOSACAL_Zenodo]_. This helps us get some recognition for creating
and maintaining this software free for everyone.

.. [IOSACAL_Zenodo] https://doi.org/10.5281/zenodo.630455

Site contents
-------------

.. toctree::
   :glob:
   :maxdepth: 1

   install
   how
   contributing
   resources
   whatsnew
   license
