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

Show CalibrateDatesConf

Defined in Currycarbon.Calibration.Calibration

Methods

showsPrec :: Int -> CalibrateDatesConf -> ShowS

show :: CalibrateDatesConf -> String

showList :: [CalibrateDatesConf] -> ShowS

Eq CalibrateDatesConf

Defined in Currycarbon.Calibration.Calibration

Methods

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

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

defaultCalConf :: CalibrateDatesConf

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

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

Show CalibrationMethod

Defined in Currycarbon.Types

Methods

showsPrec :: Int -> CalibrationMethod -> ShowS

show :: CalibrationMethod -> String

showList :: [CalibrationMethod] -> ShowS

Eq CalibrationMethod

Defined in Currycarbon.Types

Methods

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

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

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

Show UncalC14

Defined in Currycarbon.Types

Methods

showsPrec :: Int -> UncalC14 -> ShowS

show :: UncalC14 -> String

showList :: [UncalC14] -> ShowS

Eq UncalC14

Defined in Currycarbon.Types

Methods

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

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

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

Eq CalPDF

Defined in Currycarbon.Types

Methods

(==) :: CalPDF -> CalPDF -> Bool

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

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

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

id  yearBCAD  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] -> [Either CurrycarbonException CalC14]

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

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

• _calC14RangeSummary :: CalRangeSummary

  Summary of the range of the calibrated date

• _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 .tsv file with the following structure:

id  hdrSigmaLevel  hdrStartYearBCAD  hdrStopYearBCAD
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

renderCalDatePretty

Arguments

:: Bool

Should the CLI plot be restricted to (boring) ASCII symbols?

-> (NamedCalExpr, CalPDF, CalC14)

-> String

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

CalEXPR: [Ex2] (S1:5000±30BP + S2:5100±100BP)
Calibrated: 4150BC >> 3941BC > 3814BC < 3660BC << 3651BC
1-sigma: 3941-3864BC, 3810-3707BC, 3667-3660BC
2-sigma: 4150-4148BC, 4048-3651BC
                                          ▁
                                          ▒▁ ▁▁
                                  ▁▁▁    ▁▒▒▁▒▒
                                ▁▁▒▒▒    ▒▒▒▒▒▒
                              ▁▁▒▒▒▒▒▁▁▁▁▒▒▒▒▒▒▁ ▁
                          ▁▁▁▁▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▁▒▁
        ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▁▁▁▁▁▁▁▁
 -4330 ┄──┬─────┬─────┬─────┬──────┬─────┬─────┬─────┬─────┄ -3530
                   >            >       ^         <
                                ──────  ──────── ──
                   ─     ──────────────────────────

Sum (and product) calibration

Calculating the sum or product of two calibration curves is a common application, which currycarbon supports with a custom algebraic data type CalExpr. It encodes a language to describe (very simple) chronological models, to be evaluated to a single CalPDF with evalCalExpr.

A more basic interface is available with addPDFs and multiplyPDFs, which allow to combine two CalPDFs with the respective operation. Depending on the application, normalizeCalPDF will come in handy here, to normalize the output density distributions.

evalCalExpr :: CalibrateDatesConf -> CalCurveBP -> CalExpr -> Either CurrycarbonException CalPDF

Evaluate a dating expression by calibrating the individual dates and forming the respective sums and products of post-calibration density distributions

data CalExpr

A data type to represent an expression for sum- or product calibration

Constructors

UnCalDate UncalC14

WindowBP TimeWindowBP

WindowBCAD TimeWindowBCAD

CalDate CalPDF

SumCal CalExpr CalExpr

ProductCal CalExpr CalExpr

Instances

Show CalExpr

Defined in Currycarbon.Types

Methods

showsPrec :: Int -> CalExpr -> ShowS

show :: CalExpr -> String

showList :: [CalExpr] -> ShowS

Eq CalExpr

Defined in Currycarbon.Types

Methods

(==) :: CalExpr -> CalExpr -> Bool

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

addPDFs :: CalPDF -> CalPDF -> CalPDF

Add two probability densities

multiplyPDFs :: CalPDF -> CalPDF -> CalPDF

Multiply two probability densities

normalizeCalPDF :: CalPDF -> CalPDF

Rescale a CalPDF so that the sum of the densities is approx. 1.0

Drawing random samples from CalPDFs

Another common requirement for archaeological data analysis is temporal resampling, where random age samples are drawn from CalPDFs according to the probability density distribution.

currycarbon supports this with sampleAgesFromCalPDF, which takes a configuration data type AgeSamplingConf including a random number generator and the number of requested age samples, and an arbitrary CalPDF. It returns an object of type RandomAgeSample with a vector of sampled YearBCADs.

data AgeSamplingConf

A data type to define the settings for age sampling

Constructors

AgeSamplingConf

Fields

• _assRNG :: StdGen

  Random number generator

• _assNumberOfSamples :: Word

  Number of samples that should be drawn per sample

Instances

Show AgeSamplingConf

Defined in Currycarbon.Calibration.Calibration

Methods

showsPrec :: Int -> AgeSamplingConf -> ShowS

show :: AgeSamplingConf -> String

showList :: [AgeSamplingConf] -> ShowS

Eq AgeSamplingConf

Defined in Currycarbon.Calibration.Calibration

Methods

(==) :: AgeSamplingConf -> AgeSamplingConf -> Bool

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

sampleAgesFromCalPDF :: AgeSamplingConf -> CalPDF -> Either CurrycarbonException RandomAgeSample

Draw random samples from a probability density table

data RandomAgeSample

A data type to store random samples drawn from a calPDF

Constructors

RandomAgeSample

Fields

• _rasId :: String

  Identifier

• _rasSamples :: Vector YearBCAD

  Random samples

Instances

Show RandomAgeSample

Defined in Currycarbon.Types

Methods

showsPrec :: Int -> RandomAgeSample -> ShowS

show :: RandomAgeSample -> String

showList :: [RandomAgeSample] -> ShowS