Title: | Bayesian Analyses of Radiocarbon Dates with NIMBLE |
---|---|
Description: | Provides utility functions and custom probability distribution for Bayesian analyses of radiocarbon dates within the 'nimble' modelling framework. It includes various population growth models, nimbleFunction objects, as well as a suite of functions for prior and posterior predictive checks for demographic inference (Crema and Shoda (2021) <doi:10.1371/journal.pone.0251695>) and other analyses. |
Authors: | Enrico Crema [aut, cre] |
Maintainer: | Enrico Crema <[email protected]> |
License: | GPL (>= 2) |
Version: | 0.2.5 |
Built: | 2025-03-09 06:32:25 UTC |
Source: | https://github.com/ercrema/nimblecarbon |
Computes OxCal-style (Bronk-Ramsey 1995) individual and overall agreement index for evaluating model consistency.
agreementIndex(CRA, CRAError, calCurve = "intcal20", theta, verbose = TRUE)
agreementIndex(CRA, CRAError, calCurve = "intcal20", theta, verbose = TRUE)
CRA |
vector of C14 ages. |
CRAError |
vector of C14 errors associated with |
calCurve |
character string naming a calibration curve, one between 'intcal20','intcal13','shcal20','shcal13','marine13' and 'marine20'. |
theta |
a Matrix containing the posterior samples of each date. |
verbose |
a logical variable indicating whether extra information on progress should be reported. Default is TRUE. |
a list containing the individual and overall agreement indices.
Bronk-Ramsey, C. (1995). Radiocarbon Calibration and Analysis of Stratigraphy: The OxCal Program. Radiocarbon, 37(2), 425–430.
Compute delta WAIC and WAIC weights for model comparison.
compare.models(...)
compare.models(...)
... |
MCMC output from either |
A table containing WAIC, delta WAIC, and WAIC weights.
Density, distribution function, quantile function, and random generation for a Asymmetric Laplace Distribution.
dAsymLaplace(x, mu, sigma, tau, log) rAsymLaplace(n, mu, sigma, tau) pAsymLaplace(q, mu, sigma, tau, lower.tail = 1, log.p = 0) qAsymLaplace(p, mu, sigma, tau, lower.tail = 1, log.p = 0)
dAsymLaplace(x, mu, sigma, tau, log) rAsymLaplace(n, mu, sigma, tau) pAsymLaplace(q, mu, sigma, tau, lower.tail = 1, log.p = 0) qAsymLaplace(p, mu, sigma, tau, lower.tail = 1, log.p = 0)
x |
value to be computed. |
mu |
location parameter. |
sigma |
scale parameter. |
tau |
asymmetry parameter. |
log , log.p
|
TRUE or 1 to return log probability. FALSE or 0 to return probability. |
n |
number of random draws. Currently only n = 1 is supported, but the argument exists for standardization of "r" functions. |
q |
quantile to be computed. |
lower.tail |
logical; if TRUE (default), probabilities are P[X <= x] otherwise, P[X > x]. |
p |
probability to be computed. |
Enrico Crema
Density and random generation of an exponential growth model distribution.
dDoubleExponentialGrowth(x, a, b, r1, r2, mu, log) rDoubleExponentialGrowth(n, a, b, r1, r2, mu)
dDoubleExponentialGrowth(x, a, b, r1, r2, mu, log) rDoubleExponentialGrowth(n, a, b, r1, r2, mu)
x |
vector of calendar years (in BP). |
a |
lower (earliest) limit of the distribution (in BP). |
b |
upper (latest) limit of the distribution (in BP). |
r1 |
growth rate before change point mu. |
r2 |
growth rate after change point mu. |
mu |
change point (in BP). |
log |
TRUE or 1 to return log probability. FALSE or 0 to return probability. |
n |
number of random draws. Currently only n = 1 is supported, but the argument exists for standardization of "r" functions. |
For dDoubleExponentialGrowth
: the probability (or likelihood) or log probability of an observed date x (in Cal BP). For rDoubleExponentialGrowth
a simulated date in Cal BP.
Enrico Crema
p = list(r1=0.003,r2=-0.001,mu=5200) modelPlot(model = dDoubleExponentialGrowth,a=6000,b=4000,params=p,alpha = 1)
p = list(r1=0.003,r2=-0.001,mu=5200) modelPlot(model = dDoubleExponentialGrowth,a=6000,b=4000,params=p,alpha = 1)
Density and random generation of an exponential growth model distribution.
dExponentialGrowth(x, a, b, r, log) rExponentialGrowth(n, a, b, r)
dExponentialGrowth(x, a, b, r, log) rExponentialGrowth(n, a, b, r)
x |
vector of calendar years (in BP). |
a |
lower (earliest) limit of the distribution (in BP). |
b |
upper (latest) limit of the distribution (in BP). |
r |
intrinsic growth rate. |
log |
TRUE or 1 to return log probability. FALSE or 0 to return probability. |
n |
number of random draws. Currently only n = 1 is supported, but the argument exists for standardization of "r" functions. |
For dExponentialGrowth
: the probability (or likelihood) or log probability of an observed date x (in Cal BP). For rExponentialGrowth
a simulated date in Cal BP.
Enrico Crema
p = list(r=0.002) modelPlot(model = dExponentialGrowth,a=6000,b=4000,params=p,alpha = 1)
p = list(r=0.002) modelPlot(model = dExponentialGrowth,a=6000,b=4000,params=p,alpha = 1)
Density and random generation of a exponential-logistic growth model distribution.
dExponentialLogisticGrowth(x, a, b, k, r1, r2, mu, log) rExponentialLogisticGrowth(n, a, b, k, r1, r2, mu)
dExponentialLogisticGrowth(x, a, b, k, r1, r2, mu, log) rExponentialLogisticGrowth(n, a, b, k, r1, r2, mu)
x |
vector of calendar years (in BP). |
a |
lower (earliest) limit of the distribution (in BP). |
b |
upper (latest) limit of the distribution (in BP). |
k |
initial proportion of the carrying capacity (must be between 0 and 1). |
r1 |
growth rate of the exponential phase. |
r2 |
growth rate of logistic phase. |
mu |
change point (in BP). |
log |
TRUE or 1 to return log probability. FALSE or 0 to return probability. |
n |
number of random draws. Currently only n = 1 is supported, but the argument exists for standardization of "r" functions. |
For dExponentialLogisticGrowth
: the probability (or likelihood) or log probability of an observed date x (in Cal BP). For rExponentialLogisticGrowth
a simulated date in Cal BP.
Enrico Crema
p = list(r1=-0.001,r2=0.01,mu=5200,k=0.2) modelPlot(model = dExponentialLogisticGrowth,a=6000,b=4000,params=p,alpha = 1)
p = list(r1=-0.001,r2=0.01,mu=5200,k=0.2) modelPlot(model = dExponentialLogisticGrowth,a=6000,b=4000,params=p,alpha = 1)
Density and random generation of a logistic-exponential growth model distribution.
dLogisticExponentialGrowth(x, a, b, r1, r2, k, mu, log) rLogisticExponentialGrowth(n, a, b, r1, r2, k, mu)
dLogisticExponentialGrowth(x, a, b, r1, r2, k, mu, log) rLogisticExponentialGrowth(n, a, b, r1, r2, k, mu)
x |
vector of calendar years (in BP). |
a |
lower (earliest) limit of the distribution (in BP). |
b |
upper (latest) limit of the distribution (in BP). |
r1 |
growth rate of the logistic phase. |
r2 |
growth rate of exponential phase. |
k |
initial proportion of the carrying capacity (must be between 0 and 1). |
mu |
change point (in BP). |
log |
TRUE or 1 to return log probability. FALSE or 0 to return probability. |
n |
number of random draws. Currently only n = 1 is supported, but the argument exists for standardization of "r" functions. |
For dLogisticExponentialGrowth
: the probability (or likelihood) or log probability of an observed date x (in Cal BP). For rLogisticExponentialGrowth
a simulated date in Cal BP.
Robert DiNapoli & Enrico Crema
p = list(r1=0.01,r2=-0.001,k=0.001,mu=4500) modelPlot(model = dLogisticExponentialGrowth,a=6000,b=4000,params=p,alpha = 1)
p = list(r1=0.01,r2=-0.001,k=0.001,mu=4500) modelPlot(model = dLogisticExponentialGrowth,a=6000,b=4000,params=p,alpha = 1)
Density and random generation of a logistic growth model distribution.
dLogisticGrowth(x, a, b, k, r, log) rLogisticGrowth(n, a, b, k, r)
dLogisticGrowth(x, a, b, k, r, log) rLogisticGrowth(n, a, b, k, r)
x |
vector of calendar years (in BP). |
a |
lower (earliest) limit of the distribution (in BP). |
b |
upper (latest) limit of the distribution (in BP). |
k |
initial proportion of the carrying capacity (must be between 0 and 1). |
r |
intrinsic growth rate. |
log |
TRUE or 1 to return log probability. FALSE or 0 to return probability. |
n |
number of random draws. Currently only n = 1 is supported, but the argument exists for standardization of "r" functions. |
For dLogisticGrowth
: the probability (or likelihood) or log probability of an observed date x (in Cal BP). For rLogisticGrowth
a simulated date in Cal BP.
Enrico Crema
dLogisticGrowth2
for an alternative parametrisation.
p = list(k=0.01,r=0.007) modelPlot(model = dLogisticGrowth,a=6000,b=4000,params=p,alpha = 1)
p = list(k=0.01,r=0.007) modelPlot(model = dLogisticGrowth,a=6000,b=4000,params=p,alpha = 1)
Density and random generation of a logistic growth model distribution with alternative parametrisation.
dLogisticGrowth2(x, a, b, m, r, log) rLogisticGrowth2(n, a, b, m, r)
dLogisticGrowth2(x, a, b, m, r, log) rLogisticGrowth2(n, a, b, m, r)
x |
vector of calendar years (in BP). |
a |
lower (earliest) limit of the distribution (in BP). |
b |
upper (latest) limit of the distribution (in BP). |
m |
inflection point in BP (i.e. point with the highest growth rate). |
r |
intrinsic growth rate. |
log |
TRUE or 1 to return log probability. FALSE or 0 to return probability. |
n |
number of random draws. Currently only n = 1 is supported, but the argument exists for standardization of "r" functions. |
This is an alternative parametrisation of dLogisiticGrowth
, where m
is equal to log(-(k-1)/k)/r
.
For dLogisticGrowth2
: the probability (or likelihood) or log probability of an observed date x (in Cal BP). For rLogisticGrowth2
a simulated date in Cal BP.
Enrico Crema
p = list(m=4500,r=0.007) modelPlot(model = dLogisticGrowth2,a=6000,b=4000,params=p,alpha = 1)
p = list(m=4500,r=0.007) modelPlot(model = dLogisticGrowth2,a=6000,b=4000,params=p,alpha = 1)
Density and random generation of an Trapezoidal distribution.
dTrapezoidal(x, a, m1, m2, b, log) rTrapezoidal(n, a, m1, m2, b)
dTrapezoidal(x, a, m1, m2, b, log) rTrapezoidal(n, a, m1, m2, b)
x |
A calendar year (in BP). |
a |
lower (earliest) limit of the distribution (in BP). |
m1 |
lower mode (in BP) |
m2 |
upper mode (in BP). |
b |
upper (latest) limit of the distribution (in BP). |
log |
TRUE or 1 to return log probability. FALSE or 0 to return probability. |
n |
number of random draws. Currently only n = 1 is supported, but the argument exists for standardization of "r" functions. |
Enrico Crema
a=7000 b=6700 c=4000 d=3000 x=5400 modelPlot(dTrapezoidal,a=7000,b=5000,params=c(m1=6000,m2=5300),alpha=1,col=1)
a=7000 b=6700 c=4000 d=3000 x=5400 modelPlot(dTrapezoidal,a=7000,b=5000,params=c(m1=6000,m2=5300),alpha=1,col=1)
IntCal20 radiocarbon age calibration curve for the Northern hemisphere.
intcal20
intcal20
A data.frame with the following fields:
CalBP
ID of each radiocarbon date
C14Age
Radiocarbon age in 14C years BP
C14Age.sigma
Radiocarbon age error
Delta14C
Labcode of the radiocarbon date
Delta14C.sigma
Material of the dated sample
https://intcal.org/curves/intcal20.14c
Reimer, P. J., Austin, W. E. N., Bard, E., Bayliss, A., Blackwell, P. G., Ramsey, C. B., et al. (2020). The IntCal20 Northern Hemisphere Radiocarbon Age Calibration Curve (0–55 cal kBP). Radiocarbon, 62(4), 725–757. https://doi.org/10.1017/RDC.2020.41
A nimbleFunction
emulating BUGS/JAGS's interp.lin.
interpLin(z, x, y)
interpLin(z, x, y)
z |
value where the interpolation take place |
x |
numeric vector giving the coordinates of the points to be interpolated. |
y |
numeric vector giving the coordinates of the points to be interpolated. |
interpolated value
data(intcal20) interpLin(4500,intcal20$CalBP,intcal20$C14Age) # equivalent to: approx(x=intcal20$CalBP,y=intcal20$C14Age,xout=4500)$y
data(intcal20) interpLin(4500,intcal20$CalBP,intcal20$C14Age) # equivalent to: approx(x=intcal20$CalBP,y=intcal20$C14Age,xout=4500)$y
Marine20 radiocarbon age calibration curve.
marine20
marine20
A data.frame with the following fields:
CalBP
ID of each radiocarbon date
C14Age
Radiocarbon age in 14C years BP
C14Age.sigma
Radiocarbon age error
Delta14C
Labcode of the radiocarbon date
Delta14C.sigma
Material of the dated sample
https://intcal.org/curves/marine20.14c
Heaton, T. J., Köhler, P., Butzin, M., Bard, E., Reimer, R. W., Austin, W. E. N., et al. (2020). Marine20—The Marine Radiocarbon Age Calibration Curve (0–55,000 cal BP). Radiocarbon, 62(4), 779–820. https://doi.org/10.1017/RDC.2020.68
Plots growth models based on user provided parameters for prior and posterior predictive checks.
modelPlot( model, a, b, params, type = c("spaghetti"), nsample = NULL, interval = 0.9, calendar = "BP", col = "lightgrey", alpha = 0.1, ylim = NULL, xlim = NULL, xlab = NULL, ylab = NULL, add = FALSE, lwd = 1, ... )
modelPlot( model, a, b, params, type = c("spaghetti"), nsample = NULL, interval = 0.9, calendar = "BP", col = "lightgrey", alpha = 0.1, ylim = NULL, xlim = NULL, xlab = NULL, ylab = NULL, add = FALSE, lwd = 1, ... )
model |
growth model. |
a |
lower (earliest) limit of the distribution (in BP). |
b |
upper (latest) limit of the distribution (in BP). |
params |
a list of vectors containing model parameters. The names attribute of each vector should match growth model parameters. |
type |
either a 'spaghetti' plot or a quantile based 'envelope' plot. Default is 'spaghetti'. |
nsample |
number of samples to be used. Default is the length of the parameter vectors supplied in the argument |
interval |
quantile interval used for the envelope plot. Ignored when type is set to 'spaghetti'. |
calendar |
either |
col |
fill color for the quantile envelope (when |
alpha |
transparency value for each line in the spaghetti plot or the fill color in the 'envelope' plot. Default is 1. |
ylim |
the y limits of the plot. |
xlim |
the x limits of the plot (in Cal BP). |
xlab |
a label for the x axis. Default is 'Years cal BP','Years BC/AD','Years BC', or 'Years AD' depending on data range and settings of |
ylab |
a label for the y axis. Default is 'Probability'. |
add |
whether or not the new graphic should be added to an existing plot. |
lwd |
line width. Default is 1. |
... |
additional arguments affecting the plot |
None.
params = list(k=runif(100,0.01,0.02),r=runif(100,0.003,0.004)) modelPlot(model=dLogisticGrowth,a=5000,b=2000,params=params,type=c('spaghetti'),alpha=0.5)
params = list(k=runif(100,0.01,0.02),r=runif(100,0.003,0.004)) modelPlot(model=dLogisticGrowth,a=5000,b=2000,params=params,type=c('spaghetti'),alpha=0.5)
Plots spdppc
class object for SPD-based Posterior Predictive Check.
## S3 method for class 'spdppc' plot( x, type = "envelope", nsample = NULL, interval = 0.9, obs.lwd = 1.5, obs.col = "black", sim.col = "lightgrey", alpha = 1, envelope.col = "lightgrey", positive.col = "red", negative.col = "blue", calendar = "BP", xlab = NULL, ylab = NULL, ... )
## S3 method for class 'spdppc' plot( x, type = "envelope", nsample = NULL, interval = 0.9, obs.lwd = 1.5, obs.col = "black", sim.col = "lightgrey", alpha = 1, envelope.col = "lightgrey", positive.col = "red", negative.col = "blue", calendar = "BP", xlab = NULL, ylab = NULL, ... )
x |
An |
type |
Either a 'spaghetti' plot or a quantile based envelope plot. Default is 'envelope'. |
nsample |
Number of samples to be displayed in the 'spaghetti' plot. Default is the total number of simulations supplied in the 'spdppc' class object, ignored when |
interval |
Quantile interval used for the envelope plot. Ignored when |
obs.lwd |
Line width of the observed SPD. Default is 1.5. |
obs.col |
Line colour of the observed SPD. Default is 'black'. |
sim.col |
Line colour of simulated SPDs. Default is 'lightgrey', ignored when |
alpha |
Transparency value for each line in the spaghetti plot. Default is 1, ignored when |
envelope.col |
Fill colour of the simulation envelope. Default is 'lightgrey', ignored when |
positive.col |
Fill colour for the area with positive deviation from the simulation envelope. Default is 'red', ignored when |
negative.col |
Fill colour for the area with positive deviation from the simulation envelope. Default is 'blue', ignored when |
calendar |
Either |
xlab |
a label for the x axis. Default is 'Years cal BP','Years BC/AD','Years BC', or 'Years AD' depending on data range and settings of |
ylab |
a label for the y axis. Default is 'Probability'. |
... |
Additional arguments affecting the plot |
None.
Plot marginal posterior distribution highlighting user-defined higher posterior density interval.
postHPDplot( x, prob = 0.9, bw = "SJ", hpd.col = "lightblue", line.col = "darkgrey", rnd = 3, HPD = TRUE, show.hpd.val = TRUE, ... )
postHPDplot( x, prob = 0.9, bw = "SJ", hpd.col = "lightblue", line.col = "darkgrey", rnd = 3, HPD = TRUE, show.hpd.val = TRUE, ... )
x |
Posterior samples |
prob |
Highest posterior density interval. Default is 0.9. |
bw |
The smoothing bandwidth to be used. See |
hpd.col |
Fill colour for the highest density interval. Default is 'lightblue'. Ignored when |
line.col |
Line color for the density plot. Default is 'darkgrey'. |
rnd |
Integer indicating the number of decimal places to be used in the reporting of the highest posterior density interval. |
HPD |
Whether the highest posterior density interval is highlighted or not. Default is TRUE. |
show.hpd.val |
Whether the highest posterior density interval is displayed as subtitle. Default is TRUE. |
... |
other graphical parameters. |
None.
Computes the correlation between observed SPDs and posterior generated SPD from the output of postPredSPD()
function as an heuristic of the goodness-of-fit of the model.
postPredCor(x, method = "pearson")
postPredCor(x, method = "pearson")
x |
An object of class |
method |
a character string indicating which correlation coefficient is to be computed. One of "pearson" (default), "kendall", or "spearman": can be abbreviated. |
A vector of correlation values.
Generates SPDs from posterior samples.
postPredSPD( x, errors, calCurve, model, a, b, params, nsim, method = NULL, spdnormalised = TRUE, datenormalised = TRUE, ncores = 1, verbose = TRUE )
postPredSPD( x, errors, calCurve, model, a, b, params, nsim, method = NULL, spdnormalised = TRUE, datenormalised = TRUE, ncores = 1, verbose = TRUE )
x |
a vector of observed uncalibrated radiocarbon ages. |
errors |
a vector of standard deviations corresponding to each estimated radiocarbon age. |
calCurve |
character string naming a calibration curve already provided with the rcarbon package (currently 'intcal20','intcal13','intcal13nhpine16','shcal20','shcal13','shcal13shkauri16',”marine13','marine20'). |
model |
growth model |
a |
lower (earliest) limit of the distribution (in BP). |
b |
upper (latest) limit of the distribution (in BP). |
params |
list of vectors containing model parameters. The names attribute of each vector should match growth model parameters. |
nsim |
number of SPDs to be generated. Default is the length of the parameter vectors supplied in the argument |
method |
method for the creation of random dates from the fitted model. Either 'uncalsample' or 'calsample'. |
spdnormalised |
a logical variable indicating whether the total probability mass of the SPD is normalised to sum to unity for both observed and simulated data. Default is TRUE. |
datenormalised |
a logical variable indicating whether dates should be normalised to sum to unity or not. Default is TRUE. |
ncores |
number of cores used for for parallel execution. Default is 1. |
verbose |
a logical variable indicating whether extra information on progress should be reported. Default is TRUE. |
An object of class spdppc
with the following elements
obs
A data.frame containing the years (in Cal BP) and the corresponding summed probability in the observed data.
spdmat
A matrix containing the summed probability distribution of the simulated data.
IntCal20 radiocarbon age calibration curve for the Southern hemisphere.
shcal20
shcal20
A data.frame with the following fields:
CalBP
ID of each radiocarbon date
C14Age
Radiocarbon age in 14C years BP
C14Age.sigma
Radiocarbon age error
Delta14C
Labcode of the radiocarbon date
Delta14C.sigma
Material of the dated sample
https://intcal.org/curves/shcal20.14c
Reimer, P. J., Austin, W. E. N., Bard, E., Bayliss, A., Blackwell, P. G., Ramsey, C. B., et al. (2020). The IntCal20 Northern Hemisphere Radiocarbon Age Calibration Curve (0–55 cal kBP). Radiocarbon, 62(4), 725–757. https://doi.org/10.1017/RDC.2020.41