Help for package RCarb

Type:

Package

Title:

Dose Rate Modelling of Carbonate-Rich Samples

Version:

0.1.6

Date:

2022-07-22

Author:

Sebastian Kreutzer

[aut, trl, cre, dtc], Roger P. Nathan [aut, cph], Barbara Mauz

[aut, cph]

Maintainer:

Sebastian Kreutzer <sebastian.kreutzer@uni-heidelberg.de>

Description:

Translation of the 'MATLAB' program 'Carb' (Nathan and Mauz 2008 <doi:10.1016/j.radmeas.2007.12.012>; Mauz and Hoffmann 2014) for dose rate modelling for carbonate-rich samples in the context of trapped charged dating (e.g., luminescence dating) applications.

Depends:

R (≥ 4.1), utils

Imports:

interp (≥ 1.1), matrixStats (≥ 0.62.0)

Suggests:

testthat (≥ 3.1.4), R.rsp (≥ 0.45.0)

URL:

https://r-lum.github.io/RCarb/

BugReports:

https://github.com/R-Lum/RCarb/issues

License:

GPL-3

Encoding:

UTF-8

Language:

en-GB

LazyData:

true

VignetteBuilder:

R.rsp

RoxygenNote:

7.2.1

NeedsCompilation:

Packaged:

2022-07-22 08:47:37 UTC; kreutzer

Repository:

CRAN

Date/Publication:

2022-08-08 18:30:14 UTC

RCarb - Dose Rate Modelling of Carbonate-Rich Samples

Description

The package provides a dose rate modelling for carbonate-rich samples in the context of trapped charged dating (e.g., luminescence dating) applications.

Details

Funding

Between 2018-2019, the work of Sebastian Kreutzer as maintainer of the package was supported by LabEx LaScArBxSK (ANR - n. ANR-10-LABX-52).
From 01/2020-04/2022, Sebastian Kreutzer received funding from the European Union’s Horizon 2020 research and innovation programme under the Marie Skłodowska-Curie grant agreement No 844457 (project: CREDit).

References

Kreutzer, S., Mauz, B., Martin, L., Mercier, N., 2019. “RCarb”: Dose Rate Modelling of Carbonate-Rich Samples - an Implementation of Carb in R -. Ancient TL 37, 1–8.

This package bases on a 'MATLAB' programme with name 'Carb', details can be found the following references:

Mauz, B., Hoffmann, D., 2014. What to do when carbonate replaced water: Carb, the model for estimating the dose rate of carbonate-rich samples. Ancient TL 32, 24-32. http://ancienttl.org/ATL_32-2_2014/ATL_32-2_Mauz_p24-32.pdf

Nathan, R.P., Mauz, B., 2008. On the dose-rate estimate of carbonate-rich sediments for trapped charge dating. Radiation Measurements 43, 14-25. doi:10.1016/j.radmeas.2007.12.012

Further reading

Nathan, R.P., 2010. Numerical modelling of environmental dose rate and its application to trapped-charge dating. DPhil thesis, St Hugh's College, Oxford. https://ora.ox.ac.uk/objects/ora:6421

Example data

Description

Example data as shipped with Carb by Mauz & Hoffmann (2014). In contrast to the original data, NA values have been replaced by 0 and columns and rows have been transposed. Samples are now organised in rows and parameters in columns.

The data can be used to test 'RCarb' and play with the secondary carbonatisation process. Sample HD107 was renamed to LV107 for the sake of consistency with Fig. 4 in Mauz & Hoffmann (2014).

Format

Example_Data: data.frame (28 x 29)

Each column has two attributes:

UNIT: the unit, so far applicable, e.g. "ppm"
DESCRIPTION: the column description

Version

0.1.0

Author(s)

Mauz & Hoffmann (2014), with minor modifications by Sebastian Kreutzer,Geography & Earth Sciences, Aberystwyth University (United Kingdom)

References

Mauz, B., Hoffmann, D., 2014. What to do when carbonate replaced water: Carb, the model for estimating the dose rate of carbonate-rich samples. Ancient TL 32, 24-32.

Examples


## show first elements of the example data
data(Example_Data, envir = environment())
head(Example_Data)

##show only column U230
Example_Data$U238

Reference data

Description

Reference data and correction factors for beta and gamma radiation used for internal calculations. These values are used instead of the correction factors given in Aitken (1985) for the carbonate model.

Format

Reference_Data: list

NAME	TYPE	DIM	DESCRIPTION
`DATAek`	`matrix`	4 x 4	correction factors for electrons for water and carbonate to sediment mass ratio for K
`DATAet`	`matrix`	4 x 4	correction factors for electrons for water and carbonate to sediment mass ratio for Th
`DATAet230`	`matrix`	4 x 4	correction factors for electrons for water and carbonate to sediment mass ratio for Th-230
`DATAeu`	`matrix`	4 x 4	correction factors for electrons for water and carbonate to sediment mass ratio for U
`DATAeu234`	`matrix`	4 x 4	correction factors for electrons for water and carbonate to sediment mass ratio for U-234
`DATAeu238`	`matrix`	4 x 4	correction factors for electrons for water and carbonate to sediment mass ratio for U-238
`DATApk`	`matrix`	4 x 4	correction factors for photons for water and carbonate to sediment mass ratio for K
`DATApt`	`matrix`	4 x 4	correction factors for photons for water and carbonate to sediment mass ratio for T
`DATApt230`	`matrix`	4 x 4	correction factors for photons for water and carbonate to sediment mass ratio for Th-230
`DATApu`	`matrix`	4 x 4	correction factors for photons for water and carbonate to sediment mass ratio for U
`DATApu234`	`matrix`	4 x 4	correction factors for photons for water and carbonate to sediment mass ratio for U-234
`DATApu238`	`matrix`	4 x 4	correction factors for photons for water and carbonate to sediment mass ratio for U-238
`mejdahl`	`data.frame`	36 x 4	beta-dose attenuation values for quartz grains according to Mejdahl (1979)
`DR_conv_factors`	`data.frame`	4 x 13	beta and gamma dose rate conversion factors used internally (see details)

Details

The reference values are used internally to account for: (1) grain size depend beta-attenuation factors (Mejdahl, 1979) and (2) to correct nuclide dependent beta and gamma radiation for water/carbonate proportions. The latter values are given as matrix and precise values are interpolated during the modelling process.

Additionally 'RCarb' provides and own set of dose rate conversion factors to convert concentrations of U, Th, and K to dose rate values. Historically Carb (and thus 'RCarb') as its own dose rate conversion factors, which differ slightly from other published values. To provide a consistent calculation approach by default the 'old' Carb values are used, but the user can further switch (see model_DoseRate) to values provided by Adamiec & Aitken (1998), Guérin et al. (2011) or Liritzis et al (2013).

Different values quoted for U-238 and U-234 accounts for different activity ratios. For further details on the origin of these data we refer to Nathan & Mauz (2008) and Nathan (2010).

Nuclear data origin according to Nathan & Mauz (2008)

The gamma primary energy spectra of uranium, thorium and potassium are drawn from Evaluated Nuclear Structure Data File (ENSDF) database at http://www.nndc.bnl.gov (2002-01-16) and the beta primary energy spectra was derived from ENSDF end-point energies using a Fermi beta decay model (Evans, 1955) modified by Behrens & Szybisz (1976). For the simulations of the collisional mass stopping powers for quartz the software ESTAR (Berger et al., 2000) was used. The mass energy-absorption coefficients for quartz were tabulated by Hubbell & Seltzer (2004).

For further details and references please read Nathan & Mauz (2008)

Version

0.2.0

References

Adamiec, G., Aitken, M.J., 1998. Dose-rate conversion factors: update. Ancient TL 16, 37–50. http://ancienttl.org/ATL_16-2_1998/ATL_16-2_Adamiec_p37-50.pdf

Guérin, G., Mercier, N., Adamiec, G., 2011. Dose-rate conversion factors: update. Ancient TL 29, 5–9. http://ancienttl.org/ATL_29-1_2011/ATL_29-1_Guerin_p5-8.pdf

Liritzis, I., Stamoulis, K., Papachristodoulou, C., Ioannides, K., 2013. A Re-Evaluation of Radiation Dose-Rate Conversion Factors. Mediterranean Archaeology and Archaeometry 12, 1–15. http://maajournal.com/Issues/2012/pdf/FullTextLiritzis.pdf

Mejdahl, V., 1979. Thermoluminescence dating: beta-dose attenuation in quartz grains. Archaeometry 21, 61-72. http://ancienttl.org/ATL_32-2_2014/ATL_32-2_Mauz_p24-32.pdf

Nathan, R.P., Mauz, B., 2008. On the dose-rate estimate of carbonate-rich sediments for trapped charge dating. Radiation Measurements 43, 14-25. doi:10.1016/j.radmeas.2007.12.012

Nathan, R.P., 2010. Numerical modelling of environmental dose rate and its application to trapped-charge dating. DPhil thesis, St Hugh's College, Oxford. https://ora.ox.ac.uk/objects/ora:6421

Further reading

Aitken, M.J., 1985. Thermoluminescence dating. Academic Press.

Berger, M.J., Coursey, J.S., Zucker, M.A., 2000. ESTAR, PSTAR, and ASTAR: Computer Programs for Calculating Stopping-Power and Range Tables for Electrons, Protons, and Helium Ions (version 1.2.2). http://physics.nist.gov/Star (2005-08-09). National Institute of Standards and Technology, Gaithersburg, MD.

Behrens, H., Szybisz, L., 1976. Shapes of beta spectra. Physics Data 6-1, Zentralstelle fuer Atomkernenergie-Dokumentation (ZAED), Germany.

Evans, R.D., 1955. The Atomic Nucleus. McGraw-Hill, NY.

Hubbell, J.H., Seltzer, S.M., 2004. Tables of X-Ray Mass Attenuation Coefficients and Mass Energy-Absorption Coefficients (version 1.4). http://physics.nist.gov/xaamdi (2005-08-09). National Institute of Standards and Technology, Gaithersburg, MD.

Examples


data(Reference_Data, envir = environment())
str(Reference_Data)
Reference_Data$DATAek

Model dose rate evolution in carbonate-rich samples

Description

This function models the dose rate evolution in carbonate enrich environments. For the calculation internal functions are called.

Usage

model_DoseRate(
  data,
  DR_conv_factors = NULL,
  length_step = 1L,
  max_time = 500L,
  n.MC = 100,
  method_control = list(),
  txtProgressBar = TRUE,
  verbose = TRUE,
  plot = TRUE,
  par_local = TRUE,
  ...
)

Arguments

data

data.frame (required): input data following the structure given in the example data set data(Example_Data). The input data.frame should have at least one row (i.e. values for one sample). For multiple rows the function is automatically re-called.

DR_conv_factors

character (optional): applied dose rate conversion factors, allowed input values are "Carb2007", "Adamiec_Aitken_1998", "Guerin_et_al_2011", "Liritzis_et_al_2013". NULL triggers the default, which is "Carb2007"

length_step

numeric (with default): step length used for the calculation

max_time

numeric (with default): maximum temporal search range

n.MC

numeric (with default): number of Monte Carlo runs used for the error calculation

method_control

(optional): additional arguments that can be provided to the control the the modelling. See details for further information.

txtProgressBar

logical (with default): enables/disables the txtProgressBar for the MC runs

verbose

logical (with default): enables/disables verbose mode

plot

logical (with default): enables/disables plot output

par_local

logical (with default): enables/disable local par settings, If set to FALSE all global par settings are accepted.

...

further arguments passed to the underlying plot functions, see also details for further information. Supported standard arguments are mfrow, xlim, xlab.

Details

This function is the starting point for the dose rate modelling for carbonate enrich environments. It provides basically the same functionality as the original version of 'Carb', i.e. you should be also aware of the limitations of this modelling approach. In particular: The model assumes a linear carbonate mass increase due to post-depositional processes. Please read the references cited blow.

Uncertainty estimation

For estimating the uncertainties, Monte-Carlo (MC) simulation runs are used. For very small values (close to 0) this can, however, lead to edge effects (similar in 'Carb') since values below 0 are set to 0.

Value

The function returns numerical and graphical output

———————————–
⁠[ NUMERICAL OUTPUT ]⁠
———————————–

A data.frame which is the combination of the input and values calculated by this function.

———————————–
⁠[ GRAPHICAL OUTPUT ]⁠
———————————–

Upper plot: Dose rate evolution over time backwards. The solid black line is the calculation output, the grey shaded area indicates the 2-sigma error margins. The dashed blue line is an indicator of the quality of the error estimations based on Monte Carlo (MC) runs.The closer it follows the black line, the more reliable are the given error margins.

Lower plot: Totally absorbed dose over time. The plot is an representation of the 'new' age based on the carbonate modelling.

Function version

0.2.1

How to cite

Kreutzer, S., 2022. model_DoseRate(): Model dose rate evolution in carbonate-rich samples. Function version 0.2.1. In: Kreutzer, S., Nathan, R.P., Mauz, B., 2022. RCarb: Dose Rate Modelling of Carbonate-Rich Samples . R package version 0.1.6. https://r-lum.github.io/RCarb/

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany); based on 'MATLAB' code given in file Carb_2007a.m of Carb

References

Nathan, R.P., Mauz, B., 2008. On the dose-rate estimate of carbonate-rich sediments for trapped charge dating. Radiation Measurements 43, 14-25. doi:10.1016/j.radmeas.2007.12.012

Further reading

Nathan, R.P., 2010. Numerical modelling of environmental dose rate and its application to trapped-charge dating. DPhil thesis, St Hugh's College, Oxford. https://ora.ox.ac.uk/objects/ora:6421

Zimmerman, D.W., 1971. Thermoluminescent dating using fine grains from pottery. Archaeometry 13, 29–52.doi:10.1111/j.1475-4754.1971.tb00028.x

Examples

##load example data
data("Example_Data", envir = environment())

##run the function for one sample from
##the dataset
model_DoseRate(
data = Example_Data[14,],
n.MC = 2,
txtProgressBar = FALSE
)

Write table input template

Description

This function creates a template table that can be used as input for the function model_DoseRate

Usage

write_InputTemplate(file = NULL, ...)

Arguments

file

character (optional): output path, if NULL nothing is written, but a template data.frame is returned.

...

additional arguments that can be passed to function write.table if file != NULL. Supported arguments are: sep, dec, fileEncoding

Function version

0.1.0

How to cite

Kreutzer, S., 2022. write_InputTemplate(): Write table input template. Function version 0.1.0. In: Kreutzer, S., Nathan, R.P., Mauz, B., 2022. RCarb: Dose Rate Modelling of Carbonate-Rich Samples . R package version 0.1.6. https://r-lum.github.io/RCarb/

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany)

Examples


##create template without file creation
write_InputTemplate()

## Not run: 
##Example with file output

## set temporary filename
## (replace by own path if needed)
temp_file <- tempfile(pattern = "template", fileext = ".csv")
write_InputTemplate(file = temp_file)


## End(Not run)

RCarb - Dose Rate Modelling of Carbonate-Rich Samples

Description

Details

References

Example data

Description

Format

Version

Author(s)

References

Examples

Reference data

Description

Format

Details

Version

References

Examples

Model dose rate evolution in carbonate-rich samples

Description

Usage

Arguments

Details

Value

Function version

How to cite

Author(s)

References

Examples

Write table input template

Description

Usage

Arguments

Function version

How to cite

Author(s)

See Also

Examples