View source: R/AgeC14_Computation.R
AgeC14_Computation  R Documentation 
This function calibrates the C14 age of samples to get an age (in ka). The user can choose one of the following radiocarbon calibration curve: Northern or Sourthen Hemisphere or marine atmospheric. It must be the same curve for all samples.
AgeC14_Computation( Data_C14Cal, Data_SigmaC14Cal, SampleNames, Nb_sample, PriorAge = rep(c(10, 50), Nb_sample), SavePdf = FALSE, OutputFileName = c("MCMCplot", "HPD_CalC14Curve", "summary"), OutputFilePath = c(""), SaveEstimates = FALSE, OutputTableName = c("DATA"), OutputTablePath = c(""), StratiConstraints = c(), sepSC = c(","), Model = c("full"), CalibrationCurve = c("IntCal20"), Iter = 50000, t = 5, n.chains = 3, quiet = FALSE, roundingOfValue = 3 )
Data_C14Cal 
numeric (required): corresponding to C14 age estimate. 
Data_SigmaC14Cal 
numeric (required): correponding to the error of C14 age estimates. 
SampleNames 
character (required): names of sample. The length of this vector is equal to 
Nb_sample 
integer: number of samples. 
PriorAge 
numeric (with default): lower and upper bounds for age parameter of each sample in years (not in ka).
Note that, 
SavePdf 
logical (with default): if TRUE save graphs in pdf file named 
OutputFileName 
character (with default): name of the pdf file that will be generated by the function if 
OutputFilePath 
character (with default): path to the pdf file that will be generated by the function if 
SaveEstimates 
logical (with default): if TRUE save Bayes estimates, credible interval at level 68% and 95% and
the result of the gelman en Rubin test of convergency, in a csv table named 
OutputTableName 
logical (with default): name of the table that will be generated by the function if 
OutputTablePath 
character (with default): path to the table that will be generated by the function if 
StratiConstraints 
numeric matrix or character(with default): input object for the statigraphic relation between samples.
If there is stratigraphic relation between samples see the details section for instructions regarding how to correctly fill 
sepSC 
character (with default): if 
Model 
character (with default): if "full", error on estimate calibration curve is taken account. If "naive" this error is not taken account in the age estimate. 
CalibrationCurve 
character (with default): calibration curve choosen. Allowed inputs are

Iter 
integer (with default): number of iterations for the MCMC computation (for more information see rjags::jags.model). 
t 
integer (with default): 1 every 
n.chains 
integer (with default): number of independent chains for the model (for more information see rjags::jags.model. 
quiet 
logical (with default): enables/disables rjags messages 
roundingOfValue 
integer (with default): Integer indicating the number of decimal places to be used, default = 3. 
** How to fill StratiConstraints? **
If there is stratigraphic relations between samples, C14 age in Data_C14Cal
must be ordered by order of increasing ages.
The user can fill the StratiConstraints
matrix as follow.
Size of the matrix: row number of StratiConstraints
matrix is equal to Nb_sample+1
,
and column number is equal to Nb_sample
.
First line of the matrix:
for all i in {1,...,Nb_Sample}
, StratiConstraints[1,i]=1
that means the lower bound
of the sample age (given in PriorAge[2i1]
)
for the sample whose number ID is equal to i
, is taken into account.
Sample relations: for all j in {2,...,Nb_Sample+1}
and all i in {j,...,Nb_Sample}
,
StratiConstraints[j,i]=1
if sample age whose number ID is equal to j1
is lower than
sample age whose number ID is equal to i
. Otherwise, StratiConstraints[j,i]=0
.
Note that StratiConstraints_{2:Nb_sample+1,1:Nb_sample}
is a upper triangular matrix.
The user can also use SCMatrix
or SC_Ordered (if all samples are ordered) functions
to construct the StratiConstraints
matrix.
The user can also refer to a .csv file that containts the relation between samples as defined above.
The user must take care about the separator used in the csv file using the argument sepSC
.
** More precision on Model
**
We propose two models "full" or "naive". If Model = 'full'
that means
measurement error and error on calibration curve are taken account in
the Bayesian model; if Model = "naive"
that means only error on measurement
are taken account in the mode.
More precisely, the model considered here, as the one developped by Christen, JA (1994), assume multiplicative effect of errors to address the problem of outliers. In addition, to not penalyse variables that are not outliers and damage theirs estimation, we introduce a structure of mixture, that means only variable that are considered as outlier have in addition a multiplicative error.
NUMERICAL OUTPUT
A list containing the following objects:
Sampling: that corresponds to a sample of the posterior distributions of the age parameters;
Outlier: stating the names of samples that are considered as outliers;
Model: stating which model was chosen ("full"
or "naive"
);
CalibrationCurve: stating which radiocarbon calibration curve was chosen;
PriorAge: stating the priors used for the age parameter;
StratiConstraints: stating the stratigraphic relations between samples considered in the model.
The Gelman and Rubin test of convergency: print the result of the Gelman and Rubin test of convergency for the age estimate for each sample.
A result close to one is expected.
In addition, the user must visually assess the convergency of the trajectories by looking at the graph
generated by the function (see PLOT OUTPUT for more informations).
If both convergencies (Gelman and Rubin test and plot checking) are satisfactory,
the user can consider the estimates as valid.
Otherwise, the user may try increasing the number of MCMC interations (Iter
)
or being more precise if it is possible on the PriorAge
parameter to reach convergency.
Credible intervals and Bayes estimates: prints the Bayes estimates, the credible intervals at 95% and 68% for the age parameters for each sample.
PLOT OUTPUT
MCMC trajectories: A graph with the MCMC trajectories and posterior distributions of the age parameter is displayed.
On each line, the plot on the left represents the MCMC trajectories, and the one on the right the posterior distribution of the parameter.
Summary of sample age estimates: plot credible intervals and Bayes estimate of each sample age on one graph.
To give the results in a publication, we recommend to give the Bayes estimate of the parameters as well as the credible interval at 95% or 68%.
Christophe, C., Philippe, A., Kreutzer, S., 2022. AgeC14_Computation(): Bayesian analysis for C14 age estimations of various samples. In: Christophe, C., Philippe, A., Kreutzer, S., Guerin, G., 2022. BayLum: Chronological Bayesian Models Integrating Optically Stimulated. R package version 0.2.1. https://CRAN.rproject.org/package=BayLum
Please note that the initial values for all MCMC are currently all the same for all chains since we rely on the automatic initial value generation of JAGS. This is not optimal and will be changed in future. However, it does not affect the quality of the age estimates if the chains have converged.
Claire Christophe, Anne Philippe, Guillaume GuĂ©rin, Sebastian Kreutzer
Christen, JA (1994). Summarizing a set of radiocarbon determinations: a robust approach. Applied Statistics, 489503.
Reimer PJ, Bard E, Bayliss A, Beck JW, Blackwell PC, Bronl Ramsey C, Buck CE, Cheng H, Edwards RL, Friedrich M, Grootes PM, Guilderson TP, Haflidason H, Hajdas I, Hatte C, Heaton TJ, Hoffmann DL, Hogg AG, Hughen KA, Kaiser KF, Kromer B, Manning SW, Niu M, Reimer RW, Richards DA, Scott EM, Southon JR, Staff RA, Turney CSM, van der Plicht J. 2013. IntCal13 ans Marine13 radiocarbon age calibration curves 050000 years cal BP. Radiocarbon 55(4)=18691887.
Hogg AG, Hua Q, Blackwell PG, Niu M, Buck CE, Guilderson TP, Heaton TJ, Palmer JG, Reimer PJ, Reimer RW, Turney CSM, Zimmerman SRH. 2013. SHCal13 Southern Hemisphere calibration, 050000 years cal BP. Radiocarbon 55(4):18891903
rjags, plot_MCMC, SCMatrix, plot_Ages
## Load data data(DATA_C14,envir = environment()) C14Cal < DATA_C14$C14[,1] SigmaC14Cal < DATA_C14$C14[,2] Names < DATA_C14$Names nb_sample < length(Names) ## Age computation of samples without stratigraphic relations Age < AgeC14_Computation( Data_C14Cal = C14Cal, Data_SigmaC14Cal = SigmaC14Cal, SampleNames = Names, Nb_sample = nb_sample, PriorAge = rep(c(20,60),nb_sample), Iter = 500, quiet = TRUE, roundingOfValue=3)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.