Currycarbon

This module implements an algorithm for the calibration of radiocarbon dates. This is a standard procedure in Archaeology and other fields working with radiocarbon dating.

Calibration

The main function in this module calibrateDates calibrates radiocarbon dates, given the uncalibrated input dates, a calibration curve and some configuration options.

• For the input dates there is a dedicated data type UncalC14. These can be read from a .csv file with readUncalC14FromFile.
• Calibration curves are covered with the data type Calcurve. Only one curve is embedded in the package (incal20), others can be read at runtime with readCalCurveFromFile.
• The configuration options are managed in CalibrateDatesConf, within which CalibrationMethod is most important. For a solid default I suggest to use defaultCalConf.

calibrateDates returns a list of calibrated dates in the rough CalPDF format, which can be written to a file with writeCalPDFs. See the Derived output section below for more pretty output formats.

calibrateDates

Arguments

:: CalibrateDatesConf

Configuration options to consider

-> CalCurveBP

A calibration curve

-> [UncalC14]

A list of uncalibrated radiocarbon dates

-> [Either CurrycarbonException CalPDF]

The function returns a list for each input date, with either an exception if the calibration failed for some reason, or a CalPDF

Calibrates a list of dates with the provided calibration curve

Configuration

data CalibrateDatesConf

A data type to cover the configuration options of the calibrateDates function

Constructors

CalibrateDatesConf

Fields

• _calConfMethod :: CalibrationMethod

  The calibration algorithm that should be used

• _calConfAllowOutside :: Bool

  Allow calibration to run outside of the range of the calibration curve

• _calConfInterpolateCalCurve :: Bool

  Interpolate the calibration curve before calibration. This is a simple linear interpolation only to increase the output resolution for earlier time periods, where the typical calibration curves are less dense by default. With the interpolation, the output will be a per-year density. The mechanism is inspired by the implementation in the Bchron R package

Instances

Eq CalibrateDatesConf

Defined in Currycarbon.Calibration.Calibration

Methods

(==) :: CalibrateDatesConf -> CalibrateDatesConf -> Bool

(/=) :: CalibrateDatesConf -> CalibrateDatesConf -> Bool

Show CalibrateDatesConf

Defined in Currycarbon.Calibration.Calibration

Methods

showsPrec :: Int -> CalibrateDatesConf -> ShowS

show :: CalibrateDatesConf -> String

showList :: [CalibrateDatesConf] -> ShowS

defaultCalConf :: CalibrateDatesConf

A default configuration that should yield almost identical calibration results to the Bchron R package

>>> defaultCalConf
CalibrateDatesConf {_calConfMethod = Bchron {distribution = StudentTDist {ndf = 100.0}}, _calConfAllowOutside = False, _calConfInterpolateCalCurve = True}

data CalibrationMethod

Different calibration algorithms implemented in currycarbon. Currently two distinct implementations are available, although both of them are similar Intercept calibration algorithms. Maybe more algorithms will be added in the future

Constructors

MatrixMultiplication

A matrix multiplication method generally following this blog post by Martin Hinz. This method is slower and the underlying code more verbose than Bchron, but it has some advantages regarding didactics and the inspection of intermediate data products for debugging. Using this method is thus generally not advisable, except for specific applications, where a more technical insight into C14 calibration is needed

Bchron

A fast and reliable calibration algorithm very similar to the implementation in the R package Bchron by Andrew Parnell. This algorithm can be run with a simple normal distribution (NormalDist) or Student's t-distribution (StudentTDist), which is recommended

Fields

• distribution :: CalibrationDistribution

Instances

Eq CalibrationMethod

Defined in Currycarbon.Types

Methods

(==) :: CalibrationMethod -> CalibrationMethod -> Bool

(/=) :: CalibrationMethod -> CalibrationMethod -> Bool

Show CalibrationMethod

Defined in Currycarbon.Types

Methods

showsPrec :: Int -> CalibrationMethod -> ShowS

show :: CalibrationMethod -> String

showList :: [CalibrationMethod] -> ShowS

Input

data UncalC14

A data type to represent an uncalibrated radiocarbon date

Constructors

UncalC14

Fields

• _uncalC14Id :: String

  Sample identifier, e.g. a lab number

• _uncalC14UnCal :: YearBP

  C14 age in years BP

• _uncalC14Sigma :: YearRange

  C14 standard deviation (one sigma in years)

Instances

Eq UncalC14

Defined in Currycarbon.Types

Methods

(==) :: UncalC14 -> UncalC14 -> Bool

(/=) :: UncalC14 -> UncalC14 -> Bool

Show UncalC14

Defined in Currycarbon.Types

Methods

showsPrec :: Int -> UncalC14 -> ShowS

show :: UncalC14 -> String

showList :: [UncalC14] -> ShowS

readUncalC14FromFile :: FilePath -> IO [UncalC14]

Read uncalibrated radiocarbon dates from a file. The file should feature one radiocarbon date per line in the form "<sample name>,<mean age BP>,<one sigma standard deviation>", where <sample name> is optional. A valid file could look like this:

Sample1,5000,30
6000,50
Sample3,4000,25

Output

data CalPDF

A data type to represent a year-wise probability density for calibrated dates. Although technically not correct, we still call this a probability density function (PDF)

Constructors

CalPDF

Fields

• _calPDFid :: String

  Sample identifier, e.g. a lab number

• _calPDFCals :: Vector YearBCAD

  Years calBCAD

• _calPDFDens :: Vector Float

  Probability densities for each year in _calPDFCals

Instances

Show CalPDF

Defined in Currycarbon.Types

Methods

showsPrec :: Int -> CalPDF -> ShowS

show :: CalPDF -> String

showList :: [CalPDF] -> ShowS

writeCalPDFs :: FilePath -> [CalPDF] -> IO ()

Write CalPDFs to the file system. The output file is a long .csv file with the following structure:

sample,calBCAD,density
...
Sample1,-1391,2.8917924e-4
Sample1,-1390,3.3285577e-4
Sample1,-1389,3.5674628e-4
Sample1,-1388,3.750703e-4
...
Sample2,-3678,1.8128564e-3
Sample2,-3677,1.9512239e-3
Sample2,-3676,2.0227064e-3
Sample2,-3675,2.095691e-3
...

Year data types

A number of types were introcuded to distinguish clearly between ages in years BP, years BC/AD and year ranges (e.g. for standard deviations). Generally currycarbon handles input (UncalC14, UncalPDF) with YearBP, and output (CalPDF, CalC14) with YearBCAD. The switch happens as part of the the calibration process, so that calibration curves have to be adjusted as well. That is why the two types CalCurveBP and CalCurveBCAD are distinguished.

type YearBP = Word

A type to represent years BP. All numbers are positive and describe the distance in years to 1950AD: 3000 = 3000BP = 1050BC

type YearBCAD = Int

A type to represent years BC or AD. Negative values describe years BC, positive values years AD: -5000 = 5000BC and 1300 = 1300AD

type YearRange = Word

A type to represent a range of years

Calibration curves

Currycarbon features two separate data types for calibration curves: CalCurveBP and CalCurveBCAD to distinguish between versions with YearBP and YearBCAD.

The library only comes with one curve: intcal20. At runtime curves can be read and used with readCalCurveFromFile.

data CalCurveBP

A data type to represent a calibration curve with YearBP

Constructors

CalCurveBP

Fields

• _calCurveBPCals :: Vector YearBP

  Years calBP

• _calCurveBPUnCals :: Vector YearBP

  Years BP

• _calCurveBPSigmas :: Vector YearRange

  Standard deviation (one sigma in years)

Instances

Show CalCurveBP

Defined in Currycarbon.Types

Methods

showsPrec :: Int -> CalCurveBP -> ShowS

show :: CalCurveBP -> String

showList :: [CalCurveBP] -> ShowS

data CalCurveBCAD

A second data type to represent a calibration curve, here now with YearBCAD

Constructors

CalCurveBCAD

Fields

• _calCurveBCADCals :: Vector YearBCAD

  Years calBCAD

• _calCurveBCADUnCals :: Vector YearBCAD

  Years BCAD

• _calCurveBCADSigmas :: Vector YearRange

  Standard deviation (one sigma in years)

Instances

Show CalCurveBCAD

Defined in Currycarbon.Types

Methods

showsPrec :: Int -> CalCurveBCAD -> ShowS

show :: CalCurveBCAD -> String

showList :: [CalCurveBCAD] -> ShowS

intcal20 :: CalCurveBP

The intcal20 calibration curve (Reimer et al. 2020, doi: 10.1017/RDC.2020.41)

readCalCurveFromFile :: FilePath -> IO CalCurveBP

Read a calibration curve file. The file must adhere to the current version of the .c14 file format (e.g. here). Look here for other calibration curves

Derived output

The main calibration function calibrateDates returns a list of CalPDFs. This is very useful output for further computational analysis, but it is not optimised for human reading and understanding. refineCalDates therefore takes these probability distributions and turns them into the derived data type CalC14, which features high density regions (HDRs). HDRs are the age ranges a sample most likely dates to according to the post calibration probability distribution.

These can also be written to a file with writeCalC14s.

renderCalDatesPretty finally combines UncalC14, CalPDF and CalC14 to produce nice command line output summarising the calibration result for a given sample.

refineCalDates :: [CalPDF] -> [CalC14]

Transforms the raw, calibrated probability density table to a meaningful representation of a calibrated radiocarbon date

>>> :{
  let years = VU.fromList [-3000,-2900,-2800,-2700,-2600]
      densities = VU.fromList [0.1,0.2,0.3,0.2,0.1]
  in refineCalDates [CalPDF {_calPDFid = "", _calPDFCals = years, _calPDFDens = densities}]
:}
[CalC14 {_calC14id = "", _calC14HDROneSigma = [HDR {_hdrstart = -2800, _hdrstop = -2900}], _calC14HDRTwoSigma = [HDR {_hdrstart = -2600, _hdrstop = -3000}]}]

data CalC14

A data type to represent a human readable summary of a calibrated radiocarbon date

Constructors

CalC14

Fields

• _calC14id :: String

  Identifier, e.g. a lab number

• _calC14HDROneSigma :: [HDR]

  One-sigma high density regions

• _calC14HDRTwoSigma :: [HDR]

  Two-sigma high density regions

Instances

Show CalC14

Defined in Currycarbon.Types

Methods

showsPrec :: Int -> CalC14 -> ShowS

show :: CalC14 -> String

showList :: [CalC14] -> ShowS

writeCalC14s :: FilePath -> [CalC14] -> IO ()

Write CalC14s to the file system. The output file is a long .csv file with the following structure:

sample,hdrSigma,hdrStartBCAD,hdrStopBCAD
Sample1,1,-3797,-3709
Sample1,1,-3894,-3880
Sample1,2,-3680,-3655
Sample1,2,-3810,-3700
Sample1,2,-3941,-3864
Sample2,1,-1142,-1130
Sample2,1,-1173,-1161
Sample2,1,-1293,-1194
Sample2,1,-1368,-1356
Sample2,2,-1061,-1059
Sample2,2,-1323,-1112
Sample2,2,-1393,-1334

renderCalDatesPretty :: [(UncalC14, CalPDF, CalC14)] -> String

Combine UncalC14, CalPDF and CalC14 to render pretty command line output like this:

Sample: 1 ~> [5000±30BP]
1-sigma: 3894-3880BC, 3797-3709BC
2-sigma: 3941-3864BC, 3810-3700BC, 3680-3655BC
                                    ***                      
                                   *'''**   *****            
                  ***             *''''''***'''''*           
            ******'''*            ''''''''''''''''      **   
           *''''''''''**        **''''''''''''''''*   **''*  
        ***'''''''''''''********'''''''''''''''''''***'''''**
 -3960 <~~~~~~~~~|~~~~~~~~~~~~~~~~|~~~~~~~~~~~~~~~|~~~~~~~~~~> -3640