currycarbon
A package for simple, fast radiocarbon calibration
https://github.com/nevrome/currycarbon
Version on this page: | 0.2.1.2 |
LTS Haskell 22.33: | 0.3.0.1 |
Stackage Nightly 2024-09-07: | 0.3.0.1 |
Latest on Hackage: | 0.3.0.1 |
currycarbon-0.2.1.2@sha256:43362c12d201cb0e9ef9ee4e2d0c3de201191bd76d300061ef6ffa3ab8b631a6,1760
Module documentation for 0.2.1.2
- Currycarbon
- Currycarbon.CLI
- Currycarbon.CalCurves
- Currycarbon.Calibration
- Currycarbon.Parsers
- Currycarbon.SumCalibration
- Currycarbon.Types
- Currycarbon.Utils
currycarbon
Radiocarbon calibration module written in and for Haskell. Comes with a small CLI app to run calibration on the command line.
Library
The Haskell library is available on Hackage here and on Stackage here.
CLI app
For stable release versions we automatically prepare statically built binaries that can be downloaded and run directly.
You can download them here: [ Linux π₯ | macOS π₯ ]. Older release versions (some with Windows builds) are available here.
So in Linux you can run the following commands to get started:
# download the current stable release binary
wget https://github.com/nevrome/currycarbon/releases/latest/download/currycarbon-Linux
# make it executable
chmod +x currycarbon-Linux
# test it
./currycarbon-Linux "Sample1,4990,30"
currycarbon v0.2.1.0 (UTF-8)
Method: Bchron {distribution = StudentTDist {ndf = 100.0}}
Curve: IntCal20
Calibrating...
DATE: Sample1:4990Β±30BP
Calibrated: 3936BC >> 3794BC > 3757BC < 3662BC << 3654BC
1-sigma: 3794-3707BC, 3666-3662BC
2-sigma: 3936-3874BC, 3804-3697BC, 3684-3654BC
βββ ββββ
ββββββββββββββ
ββββββββββββββ β
ββ ββββββββββββββββ ββ
βββββ ββββββββββββββββ ββββ
βββββββββββ βββββββββββββββββββββββββββ
ββββββββββββββββββββββββββββββββββββββββββββββββββββ
-3950 βββββββββββ¬ββββββββββββββββ¬βββββββββββββββββ¬ββββββββββ -3640
> > ^ < <
ββββββββββββββββ β
βββββββββββ ββββββββββββββββββ ββββββ
Done.
Usage: currycarbon [--version] [DATE] [-i|--inputFile ARG]
[--calibrationCurveFile ARG] [--method ARG] [--allowOutside]
[--noInterpolation] [-q|--quiet] [--densityFile ARG]
[--hdrFile ARG] [--calCurveSegmentFile ARG]
[--calCurveMatrixFile ARG]
Intercept calibration of radiocarbon dates
Available options:
-h,--help Show this help text
--version Show version
DATE A string with one or multiple uncalibrated dates of
the form "<sample name>,<mean age BP>,<one sigma
standard deviation>" where <sample name> is optional
(e.g. "S1,4000,50"). Multiple dates can be listed
separated by ";" (e.g. "S1,4000,50; 3000,25;
S3,1000,20"). To sum or multiply the post calibration
probability distributions, dates can be combined with
"+" or "*" (e.g. "4000,50 + 4100,100"). These
expressions can be combined arbitrarily. Parentheses
can be added to specify the order of operations (e.g.
"(4000,50 + 4100,100) * 3800,50")
-i,--inputFile ARG A file with a list of calibration expressions.
Formated just as DATE, but with a new line for each
input date. DATE and --inputFile can be combined and
you can provide multiple instances of --inputFile
--calibrationCurveFile ARG
Path to an calibration curve file in .14c format. The
calibration curve will be read and used for
calibration. If no file is provided, currycarbon will
use the intcal20 curve.
--method ARG The calibration algorithm that should be used:
"<Method>,<Distribution>,<NumberOfDegreesOfFreedom>".
The default setting is equivalent to
"Bchron,StudentT,100" which copies the algorithm
implemented in the Bchron R package. Alternatively we
implemented "MatrixMult", which comes without further
arguments. For the Bchron algorithm with a normal
distribution ("Bchron,Normal") the degrees of freedom
argument is not relevant
--allowOutside Allow calibrations to run outside the range of the
calibration curve
--noInterpolation Don't interpolate the calibration curve
-q,--quiet Suppress the printing of calibration results to the
command line
--densityFile ARG Path to an output file which stores output densities
per sample and calender year
--hdrFile ARG Path to an output file which stores the high
probability density regions for each sample
--calCurveSegmentFile ARG
Path to an output file which stores the relevant,
interpolated calibration curve segment for the first
(!) input date in a long format. This option as well
as --calCurveMatrixFile are mostly meant for
debugging
--calCurveMatrixFile ARG Path to an output file which stores the relevant,
interpolated calibration curve segment for the first
(!) input date in a wide matrix format
For developers who want to edit the code
To install the latest development version you can follow these steps:
- Install the Haskell build tool Stack
- Clone the repository
- Execute
stack install
inside the repository to build the tool and automatically copy the executables to~/.local/bin
(which you may want to add to your path). This will install the compiler and all dependencies into folders that wonβt interfere with any installation you might already have.
Preparing a new stable release
The Github Actions script in .github/workflows/release.yml
registers a new draft release and automatically builds and uploads currycarbon binaries when a new Git tag with the prefix v*
is pushed.
# locally register a new tag (e.g. 0.3.1)
git tag -a v0.3.1 -m "see CHANGELOG.md"
# push tag
git push origin v0.3.1
In case of a failing build delete the tag and the release draft on Github and then delete the tag locally with
git tag -d v0.3.1
before rerunning the procedure above.
Profiling
stack build --profile
stack exec --profile -- currycarbon "1000,200;2000,200;3000,200;4000,200;5000,200;6000,200;7000,200;8000,200" -q --densityFile /dev/null +RTS -p
stack exec -- currycarbon "1000,200;2000,200;3000,200;4000,200;5000,200;6000,200;7000,200;8000,200" -q --densityFile /dev/null +RTS -s
Changes
- V 0.2.1.2: Maintenance: Switched to a newer compiler/resolver version, lifted some dependency restrictions, ran stylish-haskell on the entire codebase, updated the github actions, deprecated the haddock documentation for the dev version on GitHub
- V 0.2.1.1: Lifted some restrictions regarding the upper version bounds of dependencies
- V 0.2.1.0: Added a mechanism to detect terminal encoding and fall back on a simpler CLI plot if it is not UTF-8
- V 0.2.0.1: Brought sample names back to default CLI output
- V 0.2.0.0: Added sum (and product) calibration and made the necessary changes to various interfaces (including CLI) to make this functionality accessible
- V 0.1.2.0: Added simple summary data (CalRangeSummary with calibrated median age + begin and end of 1- and 2-sigma ranges) to CalC14 and the cli output and plot. The latter got refactored and enhanced in the process. HDRs are now βorderedβ, so _hdrstart actually stores the older and _hdrstop the younger date
- V 0.1.1.0: Complete rewrite of the cli output handling to avoid a memory leak
- V 0.1.0.0: Switch to PVP versioning (https://pvp.haskell.org/)
- V 0.24.4: Removed big dependencies bytestring and statistics
- V 0.24.3: Multiple changes in .cabal to make cabal check happy
- V 0.24.2: Found and fixed another severe bug in renderCalCurve
- V 0.24.1: Fixed a serious bug in renderCalCurveMatrix
- V 0.24.0: Introduced more precise data types to distinguish years BP and years BC/AD
- V 0.23.1: Small changes to the instances of some general types
- V 0.23.0: Renamed multiple functions to make the naming of operations for parsing, reading, from-file reading, rendering and writing consistent across data types
- V 0.22.0: Changed the interface of the important calibrateDates function with a new config data type CalibrateDatesConf
- V 0.21.3: Refactored the calibration curve interpolation
- V 0.21.2: Introduced doctest and added some tiny examples/tests to try it out
- V 0.21.1: Split up the calibration module for better readability
- V 0.21.0: Added a neat CLI density plot for calibrated dates
- V 0.20.2: Some performance improvements for the calibration of large numbers of dates
- V 0.20.1: Better (parsing) error handling
- V 0.20.0: Added an option βallowOutside to allow for calibrations to run outside the range of the calibration curve
- V 0.19.0: Added functionality to filter out dates outside of the range of the calibration curve and report an error in this case
- V 0.18.0: Implemented calibration with a StudentT distribution to mimic Bchron and established that as the new default. Reimplemented the βmethod option of the CLI tool to reflect that change
- V 0.17.0: Changed argument order in CalCurve data type to adjust to the order in .14C files
- V 0.16.0: Refactoring in the library to simplify and clarify the interface
- V 0.15.0: Added another calibration algorithm (following the implementation by Andrew Parnell in Bchron) and a method switch for the CLI
- V 0.14.0: Introduced strictness, which brought a significant increase in performance. See the discussion here: https://old.reddit.com/r/haskell/comments/picjy6/how_could_i_improve_the_performance_of_my/
- V 0.13.0: Major rewrite with the vector library - includes multiple bugfixes, but is surprisingly slow
- V 0.12.0: Renamed some core functions
- V 0.11.0: Made calibration curve interpolation optional and turned it off by default
- V 0.10.0: Simplified CLI interface by dropping the βcalibrateβ subcommand (currycarbon is sufficient now) and by repurposing -q from βquickOut to βquiet
- V 0.9.0: Made βhdrFile output a lot more machine-readable
- V 0.8.0: Added option βcalibrationCurveFile to calibrate with different calibration curves
- V 0.7.2: More documentation, small changes in code layout and renamed CLI module that provides runCalibrate
- V 0.7.1: Added type documentation with haddock and replaced the existing types with record types
- V 0.7.0: Changed the date input interface once more
- V 0.6.0: Changed the date input interface, because parenthesis can be part of valid lab numbers
- V 0.5.2: Fixed parallel evalutation (deepseq forced memory-intensive, non-lazy behaviour)
- V 0.5.1: Added github release action (copied from poseidon-hs)
- V 0.5.0: Added file input for dates to calibrate
- V 0.4.0: Made output calibrated dates negative numbers for BC and positive for AD - and adjusted HDR printing accordingly
- V 0.3.2: Some optimisation
- V 0.3.1: Added automatic filling of unknown sample names
- V 0.3.0: Simplified interface
- V 0.2.1: Removed ascii plot functionality
- V 0.2.0: Added parallel processing for the main calibration operation
- V 0.1.0: First basically working version