resages 0.22
Methods and codes for reservoir atmosphere 14C age offset calculations
Requires Python: >=3.10

﻿# resages——calculation of 14C reservoir age offsets

<p align="right">
  <img src="https://github.com/cccchou/radcal/blob/master/logo.png" alt="Logo" width="130"/>
</p>

[![PyPI version](https://badge.fury.io/py/resages.svg)](https://badge.fury.io/py/resages)
[![DOI](https://img.shields.io/badge/DOI-10.1016%2Fj.quageo.2015.05.023-blue)](https://www.sciencedirect.com/science/article/pii/S1871101415300273)

## Description
resages is a package dedicated to the proper calculation of reservoir age offsets, particularly when dealing with pairs of radiocarbon (14C) and calendar ages. This package includes a set of radiocarbon calibration curves (IntCal13,  SHCal13，and IntCal20), a template folder, various examples, a manual, and three scripts written in python. They are adapted from the folder **(/ResAge_12_2015.zip)** 

## Installation

```sh
pip install resages
```

**Note:** **Python** needs to be **> 3.10** because of the use of the `match` statement. If you don't want to upgrade Python, download the source code and change the `match` statement to an `if` statement.

## Usage

resages consists of three programs: `radical`, `rad2`, `colyear`. The corresponding function application scenarios can be found in the manual.This manual is the author's source code manual for the R language

### Quick Use

```python
from resages.radical import Radical
a = Radical("example_radcal_Southon2012", export_resage_pdf=True, threshold=1e-6)
a.radcal()

from resages.rad2 import Rad2
a = Rad2(name="example_rad2")
a.rad2()

from resages.colyear import Colyear
a = Colyear(name="example_colyear")
a.colyear()
```

## test
```sh
python setup.py test
```
there are three tests.py in tests folder, if run successfully, the output will be 

```sh
Reservoir age offsets are calculated using the IntCal20.14C calibration curve.

Work has been done successfully, check output in your folder.


Calculating reservoir age offsets...

Calibrating atmospheric 14C ages using the IntCal20.14C calibration curve...

processing: 100%|███████████████████████████████████████████████████████████████████████| 4/4 [00:00<00:00, 142.85it/s]
Calibrating atmospheric 14C ages using the IntCal20.14C calibration curve has done

Work has been done successfully, check outputs in your folder.


running
processing: 100%|██████████████████████████████████████████████████████████████████████| 80/80 [00:06<00:00, 11.88it/s]
the total spending time is 0.0min6.7s

Exporting your reservoir ages
Export reservoir age completed successfully.
```


## Options
Each script has additional options:

`rad2`:

**calibrate**: Calibrates atmospheric 14C ages (default: FALSE).

**cc**: Selects the calibration curve (1 for IntCal20, 2 for Cal13, 3 for SHIntCal13).

**prob**: Confidence interval for calibrated ranges (default: 0.95).

**export_cal_pdf**: Exports the calibrated probability density functions (default: FALSE).

`colyear`:

**cc**: Selects the calibration curve (1 for IntCal20, 2 for Cal13, 3 for SHIntCal13).

`radcal`:

**mixture_pdf**: Computes the reservoir age offset probability density function mixture (default: FALSE).

**export_uncal_pdf**: Exports the uncalibrated probability density functions (default: FALSE).

**export_resage_pdf**:Exports the uncalibrated probability density functions (default: True, must set True because it export resage output.).

**cc**: Selects the calibration curve (1 for IntCal20, 2 for Cal13, 3 for SHIntCal13).

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Citation
This python program was adapted from the **folder(/ResAge_12_2015.zip)** 
Please cite the following publications when using the **resages**:

- Soulet G, 2015. Methods and codes for reservoir-atmosphere 14C age offset calculations. Quaternary Geochronology 29:97-103, doi: 10.1016/j.quageo.2015.05.023

If using the F14R or δ14R metrics, cite: 
- Soulet G, Skinner LC, Beaupré SR, Galy V, 2016. A note on reporting of reservoir 14C disequilibria and age offsets. Radiocarbon, in press doi: 10.1017/RDC.2015.22

## References
- Beck, J.W., et al., 2001. Extremely large variations of atmospheric 14C concentration during the last glacial period. Science 292(5526): 2453-2458.
- Blaauw, M., 2010. Methods and code for ‘classical’ age-modelling of radiocarbon sequences. Quaternary Geochronology 5(5): 512-518.
- Bondevik, S., et al., 1999. Late Weichselian Marine 14C Reservoir Ages at the Western Coast of Norway. Quaternary Research 52(1): 104-114.
- Hall, B.L., et al., 2010. Constant Holocene Southern-Ocean 14C reservoir ages and ice-shelf flow rates. Earth and Planetary Science Letters 296(1): 115-123.
- Hoffmann, D.L., et al., 2010. Towards radiocarbon calibration beyond 28ka using speleothems from the Bahamas. Earth and Planetary Science Letters 289(1): 1-10.
- Hogg, A.G., et al., 2013. SHCal13 Southern Hemisphere calibration, 0–50,000 cal yr BP. Radiocarbon 55(4): 1889-1903.
Reimer, P.J., et al., 2009. IntCal09 and Marine09 Radiocarbon Age Calibration Curves, 0–50,000 years cal BP. Radiocarbon 51(4): 1111–1150.
- Reimer, P.J., et al., 2013. IntCal13 and Marine13 Radiocarbon Age Calibration Curves 0–50,000 Years cal BP. Radiocarbon 55(4): 1869-1887.
- Siani, G., et al., 2000. Radiocarbon reservoir ages in the Mediterranean Sea and Black Sea. Radiocarbon 42(2): 271-280.
Soulet, G., 2015. Methods and codes for reservoir-atmosphere 14C age offset calculations. Quaternary Geochronology 29: 97-103 doi: 10.1016/j.quageo.2015.05.023
- Southon, J., et al., 2012. A high-resolution record of atmospheric 14C based on Hulu Cave speleothem H82. Quaternary Science Reviews 33: 32-41.