Safe Haskell	Safe-Inferred
Language	Haskell2010

Currycarbon

Contents

Calibration
Year data types
Calibration curves
Derived output
Sum (and product) calibration
Drawing random samples from CalPDFs

Description

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.

Synopsis

calibrateDates :: CalibrateDatesConf -> CalCurveBP -> [UncalC14] -> [Either CurrycarbonException CalPDF]
data CalibrateDatesConf = CalibrateDatesConf {
- _calConfMethod :: CalibrationMethod
- _calConfAllowOutside :: Bool
- _calConfInterpolateCalCurve :: Bool
}
defaultCalConf :: CalibrateDatesConf
data CalibrationMethod
- = MatrixMultiplication
- | Bchron {
  - distribution :: CalibrationDistribution
  }
data UncalC14 = UncalC14 {
- _uncalC14Id :: String
- _uncalC14UnCal :: YearBP
- _uncalC14Sigma :: YearRange
}
readUncalC14FromFile :: FilePath -> IO [UncalC14]
data CalPDF = CalPDF {
- _calPDFid :: String
- _calPDFCals :: Vector YearBCAD
- _calPDFDens :: Vector Float
}
writeCalPDFs :: FilePath -> [CalPDF] -> IO ()
type YearBP = Word
type YearBCAD = Int
type YearRange = Word
data CalCurveBP = CalCurveBP {
- _calCurveBPCals :: Vector YearBP
- _calCurveBPUnCals :: Vector YearBP
- _calCurveBPSigmas :: Vector YearRange
}
data CalCurveBCAD = CalCurveBCAD {
- _calCurveBCADCals :: Vector YearBCAD
- _calCurveBCADUnCals :: Vector YearBCAD
- _calCurveBCADSigmas :: Vector YearRange
}
intcal20 :: CalCurveBP
readCalCurveFromFile :: FilePath -> IO CalCurveBP
refineCalDates :: [CalPDF] -> [Either CurrycarbonException CalC14]
data CalC14 = CalC14 {
- _calC14id :: String
- _calC14RangeSummary :: CalRangeSummary
- _calC14HDROneSigma :: [HDR]
- _calC14HDRTwoSigma :: [HDR]
}
writeCalC14s :: FilePath -> [CalC14] -> IO ()
renderCalDatePretty :: Bool -> (NamedCalExpr, CalPDF, CalC14) -> String
evalCalExpr :: CalibrateDatesConf -> CalCurveBP -> CalExpr -> Either CurrycarbonException CalPDF
data CalExpr
- = UnCalDate UncalC14
- | WindowBP TimeWindowBP
- | WindowBCAD TimeWindowBCAD
- | CalDate CalPDF
- | SumCal CalExpr CalExpr
- | ProductCal CalExpr CalExpr
addPDFs :: CalPDF -> CalPDF -> CalPDF
multiplyPDFs :: CalPDF -> CalPDF -> CalPDF
normalizeCalPDF :: CalPDF -> CalPDF
data AgeSamplingConf = AgeSamplingConf {
- _assRNG :: StdGen
- _assNumberOfSamples :: Word
}
sampleAgesFromCalPDF :: AgeSamplingConf -> CalPDF -> Either CurrycarbonException RandomAgeSample
data RandomAgeSample = RandomAgeSample {
- _rasId :: String
- _rasSamples :: Vector YearBCAD
}

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 Source #

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 Source #

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

Instances details

Show CalibrateDatesConf Source #
Instance details Defined in Currycarbon.Calibration.Calibration Methods showsPrec :: Int -> CalibrateDatesConf -> ShowS # show :: CalibrateDatesConf -> String # showList :: [CalibrateDatesConf] -> ShowS #
Eq CalibrateDatesConf Source #
Instance details Defined in Currycarbon.Calibration.Calibration Methods (==) :: CalibrateDatesConf -> CalibrateDatesConf -> Bool # (/=) :: CalibrateDatesConf -> CalibrateDatesConf -> Bool #

defaultCalConf :: CalibrateDatesConf Source #

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

data CalibrationMethod Source #

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

Instances details

Show CalibrationMethod Source #
Instance details Defined in Currycarbon.Types Methods showsPrec :: Int -> CalibrationMethod -> ShowS # show :: CalibrationMethod -> String # showList :: [CalibrationMethod] -> ShowS #
Eq CalibrationMethod Source #
Instance details Defined in Currycarbon.Types Methods (==) :: CalibrationMethod -> CalibrationMethod -> Bool # (/=) :: CalibrationMethod -> CalibrationMethod -> Bool #

Input

data UncalC14 Source #

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

Instances details

Show UncalC14 Source #
Instance details Defined in Currycarbon.Types Methods showsPrec :: Int -> UncalC14 -> ShowS # show :: UncalC14 -> String # showList :: [UncalC14] -> ShowS #
Eq UncalC14 Source #
Instance details Defined in Currycarbon.Types Methods (==) :: UncalC14 -> UncalC14 -> Bool # (/=) :: UncalC14 -> UncalC14 -> Bool #

readUncalC14FromFile :: FilePath -> IO [UncalC14] Source #

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 Source #

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

Instances details

Show CalPDF Source #
Instance details Defined in Currycarbon.Types Methods showsPrec :: Int -> CalPDF -> ShowS # show :: CalPDF -> String # showList :: [CalPDF] -> ShowS #
Eq CalPDF Source #
Instance details Defined in Currycarbon.Types Methods (==) :: CalPDF -> CalPDF -> Bool # (/=) :: CalPDF -> CalPDF -> Bool #

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

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 Source #

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

type YearBCAD = Int Source #

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 Source #

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 Source #

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

Instances details

Show CalCurveBP Source #
Instance details Defined in Currycarbon.Types Methods showsPrec :: Int -> CalCurveBP -> ShowS # show :: CalCurveBP -> String # showList :: [CalCurveBP] -> ShowS #

data CalCurveBCAD Source #

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

Instances details

Show CalCurveBCAD Source #
Instance details Defined in Currycarbon.Types Methods showsPrec :: Int -> CalCurveBCAD -> ShowS # show :: CalCurveBCAD -> String # showList :: [CalCurveBCAD] -> ShowS #

intcal20 :: CalCurveBP Source #

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

readCalCurveFromFile :: FilePath -> IO CalCurveBP Source #

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] Source #

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

data CalC14 Source #

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

Instances details

Show CalC14 Source #
Instance details Defined in Currycarbon.Types Methods showsPrec :: Int -> CalC14 -> ShowS # show :: CalC14 -> String # showList :: [CalC14] -> ShowS #

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

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 Source #

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 Source #

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

data CalExpr Source #

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

Instances details

Show CalExpr Source #
Instance details Defined in Currycarbon.Types Methods showsPrec :: Int -> CalExpr -> ShowS # show :: CalExpr -> String # showList :: [CalExpr] -> ShowS #
Eq CalExpr Source #
Instance details Defined in Currycarbon.Types Methods (==) :: CalExpr -> CalExpr -> Bool # (/=) :: CalExpr -> CalExpr -> Bool #

addPDFs :: CalPDF -> CalPDF -> CalPDF Source #

Add two probability densities

multiplyPDFs :: CalPDF -> CalPDF -> CalPDF Source #

Multiply two probability densities

normalizeCalPDF :: CalPDF -> CalPDF Source #

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 Source #

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

Instances details

Show AgeSamplingConf Source #
Instance details Defined in Currycarbon.Calibration.Calibration Methods showsPrec :: Int -> AgeSamplingConf -> ShowS # show :: AgeSamplingConf -> String # showList :: [AgeSamplingConf] -> ShowS #
Eq AgeSamplingConf Source #
Instance details Defined in Currycarbon.Calibration.Calibration Methods (==) :: AgeSamplingConf -> AgeSamplingConf -> Bool # (/=) :: AgeSamplingConf -> AgeSamplingConf -> Bool #

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

Draw random samples from a probability density table

data RandomAgeSample Source #

A data type to store random samples drawn from a calPDF

Constructors

RandomAgeSample
Fields _rasId :: String Identifier _rasSamples :: Vector YearBCAD Random samples

Instances

Instances details

Show RandomAgeSample Source #
Instance details Defined in Currycarbon.Types Methods showsPrec :: Int -> RandomAgeSample -> ShowS # show :: RandomAgeSample -> String # showList :: [RandomAgeSample] -> ShowS #