2 First steps: age analysis of one sample
Measurement data can be imported using two different options as detailed in the following:
- Option 1: Using the conventional ‘BayLum’ folder structure (old)
- Option 2: Using a single-setting config file (new)
2.1 Option 1: Import information from a BIN/BINX-file.
Let us consider the sample named samp1, which is the example
dataset coming with the package. All information related to this sample
is stored in a subfolder called also samp1. To test the package
example, first, we add the path of the example dataset to the object
path.
Please note that for your own dataset (i.e. not included in the package) you have to replace this call by something like:
In our example the folder contains the following subfolders and files:
| 1 | example.yml |
| 2 | FER1/bin.bin |
| 3 | FER1/Disc.csv |
| 4 | FER1/DoseEnv.csv |
| 5 | FER1/DoseSource.csv |
| 6 | FER1/rule.csv |
| 7 | samp1/bin.bin |
| 8 | samp1/DiscPos.csv |
| 9 | samp1/DoseEnv.csv |
| 10 | samp1/DoseSource.csv |
| 11 | samp1/rule.csv |
| 12 | samp2/bin.bin |
| 13 | samp2/DiscPos.csv |
| 14 | samp2/DoseEnv.csv |
| 15 | samp2/DoseSource.csv |
| 16 | samp2/rule.csv |
| 17 | yaml_config_reference.yml |
See “What are the required files in each subfolder?” in the
manual of Generate_DataFile() function for the meaning of
these files.
To import your data, simply call the function
Generate_DataFile():
Warning in Generate_DataFile(Path = path, FolderNames = "samp1", Nb_sample = 1, : 'Generate_DataFile' is deprecated.
Use 'create_DataFile()' instead.
See help("Deprecated")2.1.1 Remarks
2.1.1.1 Data import/export
The import may take a while, in particular for large BIN/BINX-files. This can become annoying if you want to play with the data. In such situations, it makes sense to save your imported data somewhere else before continuing.
To save the obove imported data on your hardrive use
To load the data use
2.1.1.2 Data structure
To see the overall structure of the data generated from the BIN/BINX-file and the associated CSV-files, the following call can be used:
List of 9
$ LT :List of 1
..$ : num [1, 1:7] 2.042 0.842 1.678 3.826 4.258 ...
$ sLT :List of 1
..$ : num [1, 1:7] 0.344 0.162 0.328 0.803 0.941 ...
$ ITimes :List of 1
..$ : num [1, 1:6] 15 30 60 100 0 15
$ dLab : num [1:2, 1] 1.53e-01 5.89e-05
$ ddot_env : num [1:2, 1] 2.512 0.0563
$ regDose :List of 1
..$ : num [1, 1:6] 2.3 4.6 9.21 15.35 0 ...
$ J : num 1
$ K : num 6
$ Nb_measurement: num 16It reveals that DATA1 is basically a list with 9
elements:
| Element | Content |
|---|---|
DATA1$LT |
\(L_x\)/\(T_x\) values from each sample |
DATA1$sLT |
\(L_x\)/\(T_x\) error values from each sample |
DATA1$ITimes |
Irradiation times |
DATA1$dLab |
The lab dose rate |
DATA1$ddot_env |
The environmental dose rate and its variance |
DATA1$regDose |
The regenerated dose points |
DATA1$J |
The number of aliquots selected for each BIN-file |
DATA1$K |
The number of regenerated dose points |
DATA1$Nb_measurement |
The number of measurements per BIN-file |
2.1.1.3 Visualise Lx/Tx values and dose points
To get an impression on how your data look like, you can visualise
them by using the function LT_RegenDose():
LT_RegenDose(
DATA = DATA1,
Path = path,
FolderNames = "samp1",
SampleNames = "samp1",
Nb_sample = 1,
nrow = NULL
)Warning in LT_RegenDose(DATA = DATA1, Path = path, FolderNames = "samp1", : 'LT_RegenDose' is deprecated.
Use 'plot_RegDosePoints()' instead.
See help("Deprecated")
Note that here we consider only one sample, and the name of the
folder is the name of the sample. For that reason the argumetns were set
to FolderNames = samp1 and
SampleNames = samp1.
2.1.2 Generate data file from BIN/BINX-files of multi-grain OSL measurements
For a multi-grain OSL measurements, instead of
Generate_DataFile(), the function
Generate_DataFile_MG() should be used with similar
parameters. The functions differ by their expectations:
Disc.csv instead of DiscPos.csv file for Single-grain
OSL Measurements. Please check type ?Generate_DataFile_MG
for further information.
2.2 Option 2: Import data
using create_DataFile()
With 'BayLum' >= v0.3.2 we introduced a new function
called create_DataFile(), which will at some point in time
replace the function Generate_DataFile() and
Generate_DataFile_MG(). create_DataFile()
works conceptionally very different from the approach detailed above.
Key differences are:
- The function uses a single configuration file for all samples and all measurement files
- The very error prone subfolder structure is no longer needed
- Measurement data can be imported with
create_DataFile(), but also outside of the function and then passed on the functions. This enables the possibility of extensive pre-processing and selection of measurement data.
The configuration follows the so-called YAML format specification. For single sample the file looks as follows:
- sample: "samp1"
files: null
settings:
dose_source: { value: 0.1535, error: 0.00005891 }
dose_env: { value: 2.512, error: 0.05626 }
rules:
beginSignal: 6
endSignal: 8
beginBackground: 50
endBackground: 55
beginTest: 6
endTest: 8
beginTestBackground: 50
endTestBackground: 55
inflatePercent: 0.027
nbOfLastCycleToRemove: 1In the case above, the configuration file assumes that data for
samp1 are already imported and treated and a R object
called samp1 is available in the global environment. The
following example code reproduces this case:
## get example file path from package
yaml_file <- system.file("extdata/example.yml", package = "BayLum")
samp1_file <- system.file("extdata/samp1/bin.bin", package = "BayLum")
## read YAML manually and select only the first record
config_file <- yaml::read_yaml(yaml_file)[[1]]
## import BIN/BINX files and select position 2 and grain 32 only
samp1 <- Luminescence::read_BIN2R(samp1_file, verbose = FALSE) |>
subset(POSITION == 2 & GRAIN == 32)
## create the data file
DATA1 <- create_DataFile(config_file, verbose = FALSE)2.3 Age computation
To compute the age of the sample samp1, you can run the following code:
Age <- Age_Computation(
DATA = DATA1,
SampleName = "samp1",
PriorAge = c(10, 100),
distribution = "cauchy",
LIN_fit = TRUE,
Origin_fit = FALSE,
Iter = 10000
)Compiling model graph
Resolving undeclared variables
Allocating nodes
Graph information:
Observed stochastic nodes: 6
Unobserved stochastic nodes: 9
Total graph size: 139
Initializing model
>> Sample name <<
----------------------------------------------
samp1
>> Results of the Gelman and Rubin criterion of convergence <<
----------------------------------------------
Point estimate Uppers confidence interval
A 1.05 1.093
D 1.051 1.095
sD 1.012 1.013
---------------------------------------------------------------------------------------------------
*** WARNING: The following information are only valid if the MCMC chains have converged ***
---------------------------------------------------------------------------------------------------
parameter Bayes estimate Credible interval
----------------------------------------------
A 21.625
lower bound upper bound
at level 95% 10 53.914
at level 68% 10 23.468
----------------------------------------------
D 53.734
lower bound upper bound
at level 95% 19.689 134.741
at level 68% 22.366 59.917
----------------------------------------------
sD 32.442
lower bound upper bound
at level 95% 0.341 112.15
at level 68% 1.388 29.543 This also works if DATA1 is the output of
Generate_DataFile_MG().
2.3.0.0.1 Remark 1: MCMC trajectories
If MCMC trajectories did not converge, you can add more iteration with the parameter
Iterin the functionAge_Computation(), for exampleIter = 20000orIter = 50000. If it is not desirable to re-run the model from scratch, read theTo increase the precision of prior distribution, if not specified before you can use the argument
PriorAge. For example:PriorAge= c(0.01,10)for a young sample andPriorAge = c(10,100)for an old sample.If the trajectories are still not convergering, you should whether the choice you made with the argument
distributionand dose-response curves are meaningful.
2.3.0.0.2 Remark 2:
LIN_fit and Origin_fit, dose-response curves
option
- By default, a saturating exponential plus linear dose response curve
is expected. However, you choose other formula by changing arguments
LIN_fitandOrigin_fitin the function.
2.3.0.0.3 Remark 3:
distribution, equivalent dose dispersion option
By default, a cauchy distribution is assumed, but you can
choose another distribution by replacing the word cauchy by
gaussian, lognormal_A or
lognormal_M for the argument distribution.
The difference between the models: lognormal_A and lognormal_M is that the equivalent dose dispersion are distributed according to:
- a log-normal distribution with mean or average equal to the palaeodose for the first model
- a log-normal distribution with median equal to the palaeodose for the second model.
2.3.0.0.4 Remark 4:
SavePdf and SaveEstimates option
These two arguments allow to save the results to files.
SavePdf = TRUEcreate a PDF-file with MCMC trajectories of parametersA(age),D(palaeodose),sD(equivalent doses dispersion). You have to specifyOutputFileNameandOutputFilePathto define name and path of the PDF-file.SaveEstimates = TRUEsaves a CSV-file containing the Bayes estimates, the credible interval at 68% and 95% and the Gelman and Rudin test of convergence of the parametersA,D,sD. For the export the argumentsOutputTableNameandOutputTablePathhave to be specified.
2.3.0.0.5 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, PriorAge should
be modified accordingly.
For example, if you know that the sample is an older, you can set
PriorAge=c(10,120). In contrast, if you know that the
sample is younger, you may want to set
PriorAge=c(0.001,10). Ages of \(<=0\) are not possible. The minimum
bound is 0.001.
Please note that the setting of PriorAge is not
trivial, wrongly set boundaries are likely biasing your
results.
2.4 Multiple BIN/BINX-files for one sample
In the previous example we considered only the simplest case: one
sample, and one BIN/BINX-file. However, ‘BayLum’ allows to process
multiple BIN/BINX-files for one sample. To work with multiple
BIN/BINX-files, the names of the subfolders need to beset in argument
Names and both files need to be located unter the same
Path.
For the case
the call Generate_DataFile() (or
Generate_DataFile_MG()) becomes as follows:
##argument setting
nbsample <- 1
nbbinfile <- length(Names)
Binpersample <- c(length(Names))
##call data file generator
DATA_BF <- Generate_DataFile(
Path = path,
FolderNames = Names,
Nb_sample = nbsample,
Nb_binfile = nbbinfile,
BinPerSample = Binpersample,
verbose = FALSE
)Warning in Generate_DataFile(Path = path, FolderNames = Names, Nb_sample = nbsample, : 'Generate_DataFile' is deprecated.
Use 'create_DataFile()' instead.
See help("Deprecated")##calculate the age
Age <- Age_Computation(
DATA = DATA_BF,
SampleName = Names,
BinPerSample = Binpersample
)Compiling model graph
Resolving undeclared variables
Allocating nodes
Graph information:
Observed stochastic nodes: 12
Unobserved stochastic nodes: 15
Total graph size: 221
Initializing model
>> Sample name <<
----------------------------------------------
samp1 samp2
>> Results of the Gelman and Rubin criterion of convergence <<
----------------------------------------------
Point estimate Uppers confidence interval
A 1.001 1.002
D 1.001 1.003
sD 1.008 1.013
---------------------------------------------------------------------------------------------------
*** WARNING: The following information are only valid if the MCMC chains have converged ***
---------------------------------------------------------------------------------------------------
parameter Bayes estimate Credible interval
----------------------------------------------
A 2.299
lower bound upper bound
at level 95% 1.3 3.476
at level 68% 1.72 2.706
----------------------------------------------
D 5.723
lower bound upper bound
at level 95% 3.406 8.252
at level 68% 4.659 6.823
----------------------------------------------
sD 0.746
lower bound upper bound
at level 95% 0 2.418
at level 68% 0 0.735 
