create_ThetaMatrix: Create Theta Matrix

In R-Lum/BayLum: Chronological Bayesian Models Integrating Optically Stimulated Luminescence and Radiocarbon Age Dating

Create Theta Matrix

Description

Create the \Theta matrix with the shared uncertainties that can used as input in, e.g., AgeS_Computation and Age_OSLC14 which is used for the covariance matrix \Sigma (Combès & Philippe, 2017)

Usage

create_ThetaMatrix(input, output_file = NULL, sigma_s, ...)

Arguments

input	character or data.frame (optional): input data frame or file connection to import a CSV-file with the needed information. If nothing is provided the function returns an input template. The argument output_file can be used to write this input template to the file system
output_file	character (optional): file path for the output CSV-file, the field separator is hard set to ",". Please use utils::write.table for more flexibility.
sigma_s	numeric (required): named character with values for systematic uncertainties. Those values are lab-specific. Can be set to NULL to remove systematic uncertainties. The order of the named vector is not important, but the naming! Note: some of the uncertainties have a unit, please check details.
...	further arguments that can be passed to utils::read.table (for the CSV-file import)

Details

The function intends to ease the creation of the Theta matrix, which cannot be created straight forward, e.g., base R functions such as stats::cov. The relationship between the covariance matrix Sigma and Theta is given with

\Sigma_ij = A_i * A_j * \Theta_ij

For details see Combès & Philippe, 2017 and Guérin et al. (2021).

Input modes

The function supports two different operation modes:

1. input is left empty: the function returns a data.frame template that can be used as input (the option output_file works as well)

2. input is fed with a data.frame or a character (file path), the \Theta matrix is returned

Input format

The function expects either a CSV-file or a data.frame as input. To create template you can run the function leaving the argument input empty (see example). Please note the format of the input table (data.frame) needs to kept as specified in the template.

The following table lists the meaning of the columns:

COLUMN	DESCRIPTION	UNIT
SAMPLE_ID	sample name	-
DR_BETA_K	standard error beta-dose rate K	Gy/ka
DR_BETA_U	standard error beta-dose rate U	Gy/ka
DR_BETA_Th	standard error beta-dose rate Th	Gy/ka
DR_GAMMA_K	standard error gamma-dose rate K	Gy/ka
DR_GAMMA_U	standard error gamma-dose rate U	Gy/ka
DR_GAMMA_Th	standard error gamma-dose rate Th	Gy/ka
DR_GAMMA_TOTAL	standard error total gamma-dose rate	Gy/ka
DR_TOTAL	total dose rate	Gy/ka
DR_TOTAL_X	standard error total dose rate	Gy/ka

Note: All columns can be set to 0 or NA but no column must be left empty! If a value > 0 is provided for DR_GAMMA_TOTAL this value is taken and values in, e.g., DR_GAMMA_K are discarded (set to 0)!

Systematic uncertainties

The following table provides information on the named argument that can be provided via the argument sigma_s. Missing values are not allowed, all values must be set.

ARGUMENT	DESCRIPTION	UNIT
s_betaK	relative uncertainty K concentration	-
s_betaU	relative uncertainty U concentration	-
s_betaTh	relative uncertainty Th concentration	-
s_gammaK	relative uncertainty K concentration	-
s_gammaU	relative uncertainty U concentration	-
s_gammaTh	relative uncertainty Th concentration	-
s_gammaDR	relative uncertainty gamma-dose rate	-
s_CAL	relative uncertainty beta-source calibration	-
s_intDR	absolute uncertainty internal dose rate	Gy/ka

Value

A symmetric Theta matrix or if input is missing, a data.frame with an input template

Function version

0.1.0

How to cite

Kreutzer, S., Guérin, G., 2024. create_ThetaMatrix(): Create Theta Matrix. Function version 0.1.0. In: Christophe, C., Philippe, A., Kreutzer, S., Guérin, G., Baumgarten, F.H., Frerebeau, N., 2024. BayLum: Chronological Bayesian Models Integrating Optically Stimulated. R package version 0.3.2. https://CRAN.r-project.org/package=BayLum

Author(s)

Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS-Université Bordeaux Montaigne (France), based on an 'MS Excel' sheet by Guillaume Guérin, IRAMAT-CRP2A, UMR 5060, CNRS-Université Bordeaux Montaigne (France)

References

Combès, B., Philippe, A., 2017. Bayesian analysis of individual and systematic multiplicative errors for estimating ages with stratigraphic constraints in optically stimulated luminescence dating. Quaternary Geochronology 39, 24–34. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.quageo.2017.02.003")}

Guérin, G., Lahaye, C., Heydari, M., Autzen, M., Buylaert, J.-P., Guibert, P., Jain, M., Kreutzer, S., Lebrun, B., Murray, A.S., Thomsen, K.J., Urbanova, P., Philippe, A., 2021. Towards an improvement of optically stimulated luminescence (OSL) age uncertainties: modelling OSL ages with systematic errors, stratigraphic constraints and radiocarbon ages using the R package BayLum. Geochronology 3, 229—245. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.5194/gchron-3-229-2021")}

See Also

AgeS_Computation, Age_OSLC14, utils::read.table, utils::write.table

Examples

##(1) return template data.frame (no file output)
create_ThetaMatrix()

## Not run: 
##(2) return template as data.frame + file
file_path <- tempfile(fileext = ".csv")
create_ThetaMatrix(output_file = file_path )

##NOT RUNNING EXAMPLE for sigma_s
calc_ThetaMatrix(...,
sigma_s =  c(
 s_betaK = 0.010,
 s_betaU = 0.007,
 s_betaTh = 0.006,
 s_gammaK = 0.010,
 s_gammaU = 0.007,
 s_gammaTh = 0.006,
 s_gammaDR = 0.05,
 s_CAL = 0.020,
 s_intDR = 0.030))


## End(Not run)

R-Lum/BayLum documentation built on April 19, 2024, 9:33 a.m.