# BayLum: An Introduction

#### Claire Christophe, Anne Philippe, Sebastian Kreutzer, Guillaume Guerin

#### 2017-08-30

# Introduction

BayLum provides a collection of various R functions for Bayesian analysis of Luminescence data. This includes, amongst others, data import, export, application of age models and palaeodose model.

It is possible to process data for various samples simultaneously and to consider more than one BIN file per sample. Single-grain and Multi-grain OSL measurement can be analysed. Stratigraphic constrains and systematic errors can be added in the analyse.

For those who already know how to use R, BayLum won’t be difficult to use.

### Installing BayLum package

To install BayLum you first need to install R and Rstudio that has a nice desktop environment for using R. In addition, you need to install JAGS for the Bayesian analysis of the models. Once in R (or in RStudio) you can type:

    install.packages('BayLum')

at the R command prompt to install BayLum If you then type:

    library(BayLum)

it will load in all the BayLum functions.

# 1. Age analysis of one sample

## 1.1. Generate data file from BIN file of Single-grain OSL measurements

A first step is to read information from BIN file.

Let us consider the sample named GDB3. All informations concerning this sample (environmental dose, source dose, disc and position of grains,… see “What are the required files in each subfolder?” section in help of Generate_DataFile function) are containing in a subfolder named as the sample GDB3 located in path.

Then, you can use the function Generate_DataFile as follows:

    path="path" # Put path in quotes to go to the folder containing bin.BIN file and associated .csv files
                # Note that in parameter "Path", the character must be terminated by "/"
    folder=c("GDB3")# give the name of the data folder
    nbsample=1       # give the number of samples
    DATA1=Generate_DataFile(Path=path,FolderNames=folder,Nb_sample=nbsample)

##### Remark 1: save en load information

The user can use the function save to save output \(DATA1\) as follows:

    save(DATA1,file=c(paste(path,"DATA1.RData",sep="")))

The user can acced to this file with the function load:

    load(file=c(paste(path,"DATA1.RData",sep="")))

##### Remark 2: general structure of the data

To check if there is no problem, the user can read information on BIN file and associated .csv files as folows:

    str(DATA1)

    List of 9
     $ LT            :List of 1
      ..$ : num [1:101, 1:6] 5.66 6.9 4.05 3.43 4.97 ...
     $ sLT           :List of 1
      ..$ : num [1:101, 1:6] 0.373 0.315 0.245 0.181 0.246 ...
     $ ITimes        :List of 1
      ..$ : num [1:101, 1:5] 160 160 160 160 160 160 160 160 160 160 ...
     $ dLab          : num [1:2, 1] 1.53e-01 5.89e-05
     $ ddot_env      : num [1:2, 1] 2.26 0.0617
     $ regDose       :List of 1
      ..$ : num [1:101, 1:5] 24.6 24.6 24.6 24.6 24.6 ...
     $ J             : num 101
     $ K             : num 5
     $ Nb_measurement: num 14

In DATA1, there is information for the sample named GDB3. It is expected (for more information we refer to “Value” section in help of Generate_DataFile function):

- 1 list (1 list per sample), for DATA$LT, DATA$sLT, DATA1$ITimes and DATA1$regDose}
- 1 vector of size 2 (a 2 column matrix, with 1 line per sample), for DATA1$dLab, DATA1$ddot_env
- 1 integer (1 integer per BIN files), for DATA1$J, DATA1$K, DATA1$Nb_measurement.

##### Remark 3: Lx/Ts value as a function of Regenerative Dose

You can also see the Lx/Tx values as a function of regenerative dose using the function LT_RegenDose:

    LT_RegenDose(DATA=DATA1,Path=path,FolderNames=folder,
                 SampleNames=folder,Nb_sample=nbsample)

Note that, here we consider only one sample, and the name of the folder is the name of the sample, that is why \(FolderNames=\) folder and \(SampleNames=\) folder.

## 1.2. Generate data file from BIN file of Multi-grain OSL measurements

For a multi-grain OSL measurements, instead of Generate_DataFile function, the user use Generate_DataFile_MG whith similar parameter. The difference come from the associated Disc.csv file instead DiscPos.csv file for Single-grain OSL Measurements (we refer to help of Generate_DataFile_MG function).

The user can also plot Lx/Tx values as a function of Regenerative Dose, for every selected aliquot and for each sample, with the LT_RegenDose with the option \(SG=\)False.

## 1.3. Age analysis

To compute age of the sample GDB3, you can run the following code:

    priorage=c(10,100)    # GDB3 is an old sample
    Age=Age_Computation(DATA=DATA1,SampleName="GDB3",
                        PriorAge=priorage,
                        distribution="cauchy", # Option on equivalent dose distribution
                        LIN_fit=TRUE,Origin_fit=FALSE, # Option on growth curves
                        Taille=10000)

If \(DATA1\) is output of Generate_DataFile_MG, then the user can use Age_Computation exactly as in the previous example.

##### Remark 0: on MCMC trajectories

If MCMC trajectories did not converge, you can add more iteration at the parameter \(Taille\) in the function Age_Computation, for example \(Taille=20000\) or \(Taille=50000\).

Or you can precise the prior distribution if it was not spécified before (for example if it is a young sample \(PriorAge=\) c(0.01,10), if it is an old sample \(PriorAge=\)c(10,100)).

If trajectories are still not converged, you can check if the choice of \(distribution\) and growth cruves are good.

##### Remark 1: \(LIN\_fit\) and \(Origin\_fit\), dose response curves option

By default, a saturating exponential plus linear growth curve is considered, but the user can choose other growth curves by changing option \(LIN\_fit\) and \(Origin\_fit\) in the function. We refer to the user manual for more detail.

What we can recommend is to use … if you have…

##### Remark 2: \(distribution\), equivalent dose dispersion option

By default, a cauchy distribution is considered, but the user can choose other distribution replacing cauchy by gaussian or lognormal_A or lognormal_M in \(distribution\) option.

The difference between the models: lognormal_A and lognormal_M is that the equivalent dose dispersion are distributed according to:

- a lognormal distribution with mean or Average equal to the palaeodose for the first model
- a lognormal distribution with Median equal to the palaeodose for the second model.

If you are in this cases: ….. , you can consider …..

##### Remark 3: \(SavePdf\) and \(SaveEstimates\) option

These two options allow to save directly information.

\(SavePdf=TRUE\) saves a pdf file with MCMC trajectories of parameters \(A\) (age), \(D\) (palaeodose), \(sD\) (equivalent doses dispersion). The user must precise \(OutputFileName\) and \(OutputFilePath\) to define name and path of the pdf file.

\(SaveEstimates=TRUE\) saves a csv file containing Bayes estimates, credible interval at 68% and 95% and the Gelman and Rudin test of convergency of the parameters \(A\), \(D\), \(sD\). The user must precise \(OutputTableName\) and \(OutputTablePath\) to define name and path of the csv file.

##### Remark 4: \(PriorAge\) option

By default, an age between 0.01 Ka and 100 ka is expected. If the user has more informations on the sample age it can change \(PriorAge\).

For example, if you know that the sample is an old sample, you can choose \(PriorAge=c(10,120)\). In contrast, if you know that is a young sample, you can choose \(PriorAge=c(0.001,10)\). Note that, it is not possible to consider as lower bound 0, you can consider 0.001.

You must take care with this option, because \(PriorAge\) are the lower bound and the upper bound of the estimated age. If you give a \(PriorAge\) too precise it can bias the result.

## 1.4. Various BIN files for one sample

In the previous example we consider the samplest case: one sample, and one BIN file for this sample. But we can consider various BIN files for one sample. To do this, you write in \(Names\) the names of subfolder coresponding to a specific BIN file, both located in \(path\). For example \(Names=c("name\_binfile1","name\_binfile2")\). Then, you can complete Generate_DataFile (or Generate_DataFile_MF) as follows:

    nbsample=1
    nbbinfile = length(Names)
    Binpersample = c(length(Names))
    DATA_BF=Generate_DataFile(Path=path,
                              FolderNames=Names,
                              Nb_sample=nbsample,
                              Nb_binfile=nbbinfile,
                              BinPerSample=Binpersample)
    # Computation of age
    Age=Age_Computation(DATA=DATA_BF,
                        SampleName="Names",
                        BinPerSample=Binpersample)

# 2. Age analysis of various samples

## 2.1. Generate data file from BIN files

More precisely, the function Generate_DataFile (or Generate_DataFile_MF) can consider various samples simultaneously, and can consider more than one BIN file per sample.

Assume that we are interested in two samples named: sample1 and sample2. In addition, we have two BIN files for the first sample named: sample1-1 and sample1-2, and one Bin file for the sample2, named sample2-1. Then we must have 3 subfolders named sample1-1, sample1-2 and sample2-1; which each subfolder contains one BIN file named bin.BIN, and its associated files DiscPos.csv, DoseEnv.csv, DoseSourve.csv and rule.csv. These 3 subfolders are located in path.

To fill corectly \(BinPerSample\): \[binpersample=c(\underbrace{2}_{\text{sample 1: 2 bin files}},\underbrace{1}_{\text{sample 2: 1 bin file}})\]

    Names=c("sample1-1","sample1-2","sample2-1") # give the name of the folder datat
    nbsample=2    # give the number of samples
    nbbinfile=3   # give the number of bin files
    DATA=Generate_DataFile(Path=path,FolderNames=Names,
                           Nb_sample=nbsample,
                           Nb_binfile=nbbinfile,
                           BinPerSample=binpersample)

#### Concat_DataFile function

If the user has already saved informations obtained with Generate_DataFile function (or Generate_DataFile_MG function) about samples in RData file. The user can concatenate data with the Concat_DataFile.

For example if DATA1 is output of sample named “GDB3”, and DATA2 is output of “GDB5”,

    data("DATA1",envir = environment())
    data("DATA2",envir = environment())
    DATA3=Concat_DataFile(L1=DATA2,L2=DATA1)
    str(DATA3)

    List of 9
     $ LT            :List of 2
      ..$ : num [1:188, 1:6] 4.54 2.73 2.54 2.27 1.48 ...
      ..$ : num [1:101, 1:6] 5.66 6.9 4.05 3.43 4.97 ...
     $ sLT           :List of 2
      ..$ : num [1:188, 1:6] 0.333 0.386 0.128 0.171 0.145 ...
      ..$ : num [1:101, 1:6] 0.373 0.315 0.245 0.181 0.246 ...
     $ ITimes        :List of 2
      ..$ : num [1:188, 1:5] 40 40 40 40 40 40 40 40 40 40 ...
      ..$ : num [1:101, 1:5] 160 160 160 160 160 160 160 160 160 160 ...
     $ dLab          : num [1:2, 1:2] 1.53e-01 5.89e-05 1.53e-01 5.89e-05
     $ ddot_env      : num [1:2, 1:2] 2.512 0.0563 2.26 0.0617
     $ regDose       :List of 2
      ..$ : num [1:188, 1:5] 6.14 6.14 6.14 6.14 6.14 6.14 6.14 6.14 6.14 6.14 ...
      ..$ : num [1:101, 1:5] 24.6 24.6 24.6 24.6 24.6 ...
     $ J             : num [1:2] 188 101
     $ K             : num [1:2] 5 5
     $ Nb_measurement: num [1:2] 14 14

In DATA, there is information for samples named GDB3 and GDB5, then it is expected

- 2 lists (1 list per sample) for DATA$LT, DATA$sLT, DATA1$ITimes and DATA1$regDose
- a matrix with 2 columns (1 line per sample) for DATA1$dLab, DATA1$ddot_env
- 2 integers (1 integer per BIN files here we have 1 BIN file per sample) for DATA1$J, DATA1$K, DATA1$Nb_measurement.

It is possible to concat data from Single-grain OSL measurement and from Multi-grain OSL measurement.

You can also see the L/T in function of the regenerative doses for each sample as follows:

    LT_RegenDose(DATA=DATA3,Path=path,FolderNames=Names,
                 Nb_sample=nbsample,SG=rep(TRUE,nbsample))

As in DATA3 there are informations concerning sample GDB3 and GDB5 which are Single-grain OSL measurements, \(SG[1]=SG[2]=TRUE\). If one sample (whose number ID is equal to \(i\)) is Multi-grain OSL measurements, the user changes \(SG\) option by \(SG[i]=\)FALSE.

## 2.2. Age analysis without constraint

If there is no stratigraphic constraint, you can compute the following code to analyse simultaneously the age of the sample GDB5 and GDB3.

    priorage=c(1,10,10,100) # see remark to have more information on this parameter
    Age=AgeS_Computation(DATA=DATA3,Nb_sample=2,SampleNames=c("GDB5","GDB3"),
                  PriorAge=priorage,
                  distribution="cauchy", # Option on equivalent dose distribution
                  LIN_fit=TRUE,Origin_fit=FALSE, # Option on growth curves
                  Iter=10000)

##### Remark: MCMC trajectories and convergencies

If MCMC trajectories did not converge, we refer to remark 0 in Section 1.3.

##### Remark

Options detailled in remark 1, 2, 3, of the section1.3, are still available for this function.

As for the function Age_computation, age for each sample is by default between 0.01 Ka and 100 ka. If you have more informations on your samples it is possible to change \(PriorAge\) parameters. \(PriorAge\) is a vector of size = 2*\(Nb\_sample\), the two first values of \(PriorAge\) concern the first sample and so on.

For example, if you know that sample named GDB5 is a young sample whose its age is between 0.01 ka and 10 ka, and GDB3 is an old sample whose age is between 10 ka and 100 ka, \[PriorAge=c(\underbrace{0.01,10}_{GDB5\ prior\ age},\underbrace{10,100}_{GDB3\ prior\ age})\]

## 2.3. Stratigraphic constraints

With the function AgeS_Computation it is possible to take into account stratigraphic relations between samples.

For example, we know that GDB5 age is supposed lower than GDB3 age.

#### a) Ordering samples

To take into acount stratigraphic constraints, informations on samples must be ordered.

Either you inter sample Name (corresponding to subforlder names) in \(Names\) parameter of the function Generate_DataFile, ordered by order of increasing ages; or you enter saved .RData informations of each sample in Concat_DataFile, ordered by order of increasing ages.

    # using Generate_DataFile function
    Names=c("GDB5","GDB3")
    nbsample=2
    Generate_DataFile(Path=path,FolderNames=Names,Nb_sample=nbsample)

    # using Concat_DataFile function
    data(DATA1,envir = environment()) # .RData on sample GDB3
    data(DATA2,envir = environment()) # .RData on sample GDB5
    DATA3=Concat_DataFile(L1=DATA1,L2=DATA2)

#### b) Construct stratigraphic constraint matrix

Let SC be the matrix containing all informations on stratigraphic relations for this two samples. This matrix is defined as follows:

- the size of the matrix: row number of \(StratiConstraints\) matrix is equal to \(Nb\_sample+1\), and column number is equal to \(Nb\_sample\).

- the 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[2i-1]\) for the sample whose number ID is equal to \(i\), is taken into account.

- the 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 j-1 is lower than sample age whose number ID is equal to i. Otherwise, \(StratiConstraints[j,i]=0\).

The user can use the function SCMatrix to define this matrix:

    SC=SCMatrix(Nb_sample=2,SampleNames=c("GDB5","GDB3"))

    GDB5 is younger than sample GDB3? 1 for TRUE or 0 for FALSE -->

    1

    [1] 1

In our case: 2 samples, SC is a matrix with 3 lines and 2 columns. The first line containts \(c(1,1)\) (because we take into acount prior ages), the second line containts \(c(0,1)\) (because the sample 2, named GDB3 is supposed older than the sample 1, named GDB5) and the third line contains \(c(0,0)\) (because the sample 2, named GDB3 is not younger than the sample 1, named GDB5). Then, we can also fill the matrix of stratigraphic relations as follow:

    (SC=matrix(data=c(1,1,0,1,0,0),ncol=2,nrow = (2+1),byrow = T))

         [,1] [,2]
    [1,]    1    1
    [2,]    0    1
    [3,]    0    0

#### c) Age computation

    Age=AgeS_Computation(DATA=DATA3,Nb_sample=2,SampleNames=c("GDB5","GDB3"),
                       PriorAge=priorage,
                       distribution="cauchy", # Option on equivalent dose distribution
                       LIN_fit=TRUE,Origin_fit=FALSE, # Option on growth curves
                       StratiConstraints=SC,  # Stratigraphic relations
                       Taille=10000)

# References

Models used in this package are detailled in the following publication:

- Combes, B., Philippe, A., Lanos, P., Mercier, N., Tribolo, C., Guerin, G., Guibert, P., Lahaye, C., (2015). A Bayesian central equivalent dose model for optically stimulated luminescence dating. Quaternary Geochronology 28, 62-70.
- Combes, B. and Philippe, A. (2017). Bayesian analysis of multiplicative Gaussian error for multiple ages estimation in optically stimulated luminescence dating. Quaternary Geochronology (in press)

For more details on the diagnostic of Markov chain :

- Robert and Casella (2009). Introducing Monte Carlo Methods with R. Springer Science & Business Media.

For more detail on data used in examples, we refer to the following publication:

- Tribolo, C., Asrat, A., Bahain, J. J., Chapon, C., Douville, E., Fragnol, C., Hernandez, M., Hovers, E., Leplongeon, A., Martin, L, Pleurdeau, D, Pearson, O , Puaud, S, Assefa, Z. (2017). Across the Gap: Geochronological and Sedimentological Analyses from the Late Pleistocene-Holocene Sequence of Goda Buticha, Southeastern Ethiopia. PloS one, 12(1), e0169418.