Package 'Luminescence'

Description

A collection of various R functions for the purpose of luminescence dating data analysis. This includes, amongst others, data import, export, application of age models, curve deconvolution, sequence analysis and plotting of equivalent dose distributions.

Details

Supervisor of the initial version in 2012

Markus Fuchs, Justus-Liebig-University Giessen, Germany

Support contact

• [email protected]

• https://github.com/R-Lum/Luminescence/discussions

Bug reporting

• [email protected] or

• https://github.com/R-Lum/Luminescence/issues

Project website

• https://r-luminescence.org

Project source code repository

• https://github.com/R-Lum/Luminescence

Related package projects

• https://cran.r-project.org/package=RLumShiny

• https://cran.r-project.org/package=RLumModel

• https://cran.r-project.org/package=RLumCarlo

• https://cran.r-project.org/package=RCarb

Funding

• 2011-2013: The initial version of the package was developed, while Sebastian Kreutzer was funded through the DFG programme "Rekonstruktion der Umweltbedingungen des Spätpleistozäns in Mittelsachsen anhand von Löss-Paläobodensequenzen" (DFG id: 46526743)

• 2014-2018: Cooperation and personal exchange between the developers is gratefully funded by the DFG (SCHM 3051/3-1) in the framework of the program "Scientific Networks". Project title: "RLum.Network: Ein Wissenschaftsnetzwerk zur Analyse von Lumineszenzdaten mit R" (2014-2018)

• 05/2014-12/2019: The work of Sebastian Kreutzer as maintainer of the package was supported by LabEx LaScArBx (ANR - n. ANR-10-LABX-52).

• 01/2020-04/2022: Sebastian Kreutzer as maintainer of the package has received funding from the European Union’s Horizon 2020 research and innovation programme under the Marie Skłodowska-Curie grant agreement No 844457 (CREDit), and could continue maintaining the package.

• since 03/2023: Sebastian Kreutzer as maintainer of the package receives funding from the DFG Heisenberg programme No 505822867.

• All other authors gratefully received additional funding from various public funding bodies.

Author(s)

Maintainer: Sebastian Kreutzer [email protected] (ORCID) [translator, data contributor]

Authors:

• Christoph Burow (ORCID) [translator, data contributor]

• Michael Dietze (ORCID)

• Margret C. Fuchs (ORCID)

• Christoph Schmidt (ORCID)

• Manfred Fischer [translator]

• Johannes Friedrich (ORCID)

• Norbert Mercier (ORCID)

• Anne Philippe (ORCID)

• Svenja Riedesel (ORCID)

• Martin Autzen (ORCID)

• Dirk Mittelstrass (ORCID)

• Harrison J. Gray (ORCID)

• Jean-Michel Galharret (ORCID)

• Marco Colombo (ORCID)

Other contributors:

• Rachel K. Smedley (ORCID) [contributor]

• Claire Christophe [contributor]

• Antoine Zink (ORCID) [contributor]

• Julie Durcan (ORCID) [contributor]

• Georgina E. King (ORCID) [contributor, data contributor]

• Guillaume Guerin (ORCID) [contributor]

• Pierre Guibert (ORCID) [contributor]

• Markus Fuchs (ORCID) [thesis advisor]

References

Dietze, M., Kreutzer, S., Fuchs, M.C., Burow, C., Fischer, M., Schmidt, C., 2013. A practical guide to the R package Luminescence. Ancient TL, 31 (1), 11-18.

Dietze, M., Kreutzer, S., Burow, C., Fuchs, M.C., Fischer, M., Schmidt, C., 2016. The abanico plot: visualising chronometric data with individual standard errors. Quaternary Geochronology 31, 1-7. https://doi.org/10.1016/j.quageo.2015.09.003

Fuchs, M.C., Kreutzer, S., Burow, C., Dietze, M., Fischer, M., Schmidt, C., Fuchs, M., 2015. Data processing in luminescence dating analysis: An exemplary workflow using the R package 'Luminescence'. Quaternary International, 362,8-13. https://doi.org/10.1016/j.quaint.2014.06.034

Kreutzer, S., Schmidt, C., Fuchs, M.C., Dietze, M., Fischer, M., Fuchs, M., 2012. Introducing an R package for luminescence dating analysis. Ancient TL, 30 (1), 1-8.

Mercier, N., Kreutzer, S., Christophe, C., Guérin, G., Guibert, P., Lahaye, C., Lanos, P., Philippe, A., Tribolo, C., 2016. Bayesian statistics in luminescence dating: The 'baSAR'-model and its implementation in the R package ’Luminescence’. Ancient TL 34 (2), 14-21.

Mercier, N., Galharret, J.-M., Tribolo, C., Kreutzer, S., Philippe, A., 2022. Luminescence age calculation through Bayesian convolution of equivalent dose and dose-rate distributions: the De_Dr model. Geochronology 4, 297–310. https://doi.org/10.5194/gchron-4-297-2022

Smedley, R.K., 2015. A new R function for the Internal External Uncertainty (IEU) model. Ancient TL, 33 (1), 16-21.

King, E.G., Burow, C., Roberts, H., Pearce, N.J.G., 2018. Age determination using feldspar: evaluating fading-correction model performance. Radiation Measurements 119, 58-73. https://doi.org/10.1016/j.radmeas.2018.07.013

See Also

Useful links:

• https://r-lum.github.io/Luminescence/

• Report bugs at https://github.com/R-Lum/Luminescence/issues

Description

The function provides the analysis of cross-talk measurements on a FI lexsyg SMART reader using Al2O3:C chips

Usage

analyse_Al2O3C_CrossTalk(
  object,
  signal_integral = NULL,
  dose_points = c(0, 4),
  recordType = c("OSL (UVVIS)"),
  irradiation_time_correction = NULL,
  method_control = NULL,
  plot = TRUE,
  ...
)

Arguments

Value

Function returns results numerically and graphically:

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

RLum.Results-object

slot: ⁠@data⁠

slot: ⁠@info⁠

The original function call

————————
⁠[ PLOT OUTPUT ]⁠
————————

• An overview of the obtained apparent dose values

Function version

0.1.3

How to cite

Kreutzer, S., 2024. analyse_Al2O3C_CrossTalk(): Al2O3:C Reader Cross Talk Analysis. Function version 0.1.3. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team

References

Kreutzer, S., Martin, L., Guérin, G., Tribolo, C., Selva, P., Mercier, N., 2018. Environmental Dose Rate Determination Using a Passive Dosimeter: Techniques and Workflow for alpha-Al2O3:C Chips. Geochronometria 45, 56-67. doi: 10.1515/geochr-2015-0086

See Also

analyse_Al2O3C_ITC

Examples

##load data
data(ExampleData.Al2O3C, envir = environment())

##run analysis
analyse_Al2O3C_CrossTalk(data_CrossTalk)

Description

The function provides a very particular analysis to correct the irradiation time while irradiating Al2O3:C chips in a luminescence reader.

Usage

analyse_Al2O3C_ITC(
  object,
  signal_integral = NULL,
  dose_points = c(2, 4, 8, 12, 16),
  recordType = c("OSL (UVVIS)"),
  method_control = NULL,
  verbose = TRUE,
  plot = TRUE,
  ...
)

Arguments

Details

Background: Due to their high dose sensitivity Al2O3:C chips are usually irradiated for only a very short duration or under the closed beta-source within a luminescence reader. However, due to its high dose sensitivity, during the movement towards the beta-source, the pellet already receives and non-negligible dose. Based on measurements following a protocol suggested by Kreutzer et al., 2018, a dose response curve is constructed and the intersection (absolute value) with the time axis is taken as real irradiation time.

method_control

To keep the generic argument list as clear as possible, arguments to allow a deeper control of the method are all preset with meaningful default parameters and can be handled using the argument method_control only, e.g., method_control = list(fit.method = "LIN"). Supported arguments are:

Value

Function returns results numerically and graphically:

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

RLum.Results-object

slot: ⁠@data⁠

slot: ⁠@info⁠

The original function call

————————
⁠[ PLOT OUTPUT ]⁠
————————

• A dose response curve with the marked correction values

Function version

0.1.1

How to cite

Kreutzer, S., 2024. analyse_Al2O3C_ITC(): Al2O3 Irradiation Time Correction Analysis. Function version 0.1.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team

References

Kreutzer, S., Martin, L., Guérin, G., Tribolo, C., Selva, P., Mercier, N., 2018. Environmental Dose Rate Determination Using a Passive Dosimeter: Techniques and Workflow for alpha-Al2O3:C Chips. Geochronometria 45, 56-67. doi: 10.1515/geochr-2015-0086

See Also

fit_DoseResponseCurve

Examples

##load data
data(ExampleData.Al2O3C, envir = environment())

##run analysis
analyse_Al2O3C_ITC(data_ITC)

Description

The function provides the analysis routines for measurements on a FI lexsyg SMART reader using Al2O3:C chips according to Kreutzer et al., 2018

Usage

analyse_Al2O3C_Measurement(
  object,
  signal_integral = NULL,
  dose_points = c(0, 4),
  recordType = c("OSL (UVVIS)", "TL (UVVIS)"),
  calculate_TL_dose = FALSE,
  irradiation_time_correction = NULL,
  cross_talk_correction = NULL,
  travel_dosimeter = NULL,
  test_parameters = NULL,
  verbose = TRUE,
  plot = TRUE,
  ...
)

Arguments

Details

Working with a travel dosimeter

The function allows to define particular position numbers as travel dosimeters. For example: travel_dosimeter = c(1,3,5) sets positions 1, 3 and 5 as travel dosimeters. These dose values #' of this dosimeters are combined and automatically subtracted from the obtained dose values of the other dosimeters.

Calculate TL dose

The argument calculate_TL_dose provides the possibility to experimentally calculate a TL-dose, i.e. an apparent dose value derived from the TL curve ratio. However, it should be noted that this value is only a fall back in case something went wrong during the measurement of the optical stimulation. The TL derived dose value is corrected for cross-talk and for the irradiation time, but not considered if a travel dosimeter is defined.

Calculating the palaeodose is possible without any TL curve in the sequence!

Test parameters

TL_peak_shift numeric (default: 15):

Checks whether the TL peak shift is bigger > 15 K, indicating a problem with the thermal contact of the chip.

stimulation_power numeric (default: 0.05):

So far available, information on the delivered optical stimulation are compared. Compared are the information from the first curves with all others. If the ratio differs more from unity than the defined by the threshold, a warning is returned.

Value

Function returns results numerically and graphically:

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

RLum.Results-object

slot: ⁠@data⁠

Note: If correction the irradiation time and the cross-talk correction method is used, the De values in the table data table are already corrected, i.e. if you want to get an uncorrected value, you can use the column CT_CORRECTION remove the correction

slot: ⁠@info⁠

The original function call

————————
⁠[ PLOT OUTPUT ]⁠
————————

• OSL and TL curves, combined on two plots.

Function version

0.2.6

How to cite

Kreutzer, S., 2024. analyse_Al2O3C_Measurement(): Al2O3:C Passive Dosimeter Measurement Analysis. Function version 0.2.6. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team

References

Kreutzer, S., Martin, L., Guérin, G., Tribolo, C., Selva, P., Mercier, N., 2018. Environmental Dose Rate Determination Using a Passive Dosimeter: Techniques and Workflow for alpha-Al2O3:C Chips. Geochronometria 45, 56-67.

See Also

analyse_Al2O3C_ITC

Examples

##load data
data(ExampleData.Al2O3C, envir = environment())

##run analysis
analyse_Al2O3C_Measurement(data_CrossTalk)

Description

This function allows the application of Bayesian models on luminescence data, measured with the single-aliquot regenerative-dose (SAR, Murray and Wintle, 2000) protocol. In particular, it follows the idea proposed by Combès et al., 2015 of using an hierarchical model for estimating a central equivalent dose from a set of luminescence measurements. This function is (I) the adoption of this approach for the R environment and (II) an extension and a technical refinement of the published code.

Usage

analyse_baSAR(
  object,
  CSV_file = NULL,
  aliquot_range = NULL,
  source_doserate = NULL,
  signal.integral,
  signal.integral.Tx = NULL,
  background.integral,
  background.integral.Tx = NULL,
  irradiation_times = NULL,
  sigmab = 0,
  sig0 = 0.025,
  distribution = "cauchy",
  baSAR_model = NULL,
  n.MCMC = 1e+05,
  fit.method = "EXP",
  fit.force_through_origin = TRUE,
  fit.includingRepeatedRegPoints = TRUE,
  method_control = list(),
  digits = 3L,
  distribution_plot = "kde",
  plot = TRUE,
  plot_reduced = TRUE,
  plot_singlePanels = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Details

Internally the function consists of two parts: (I) The Bayesian core for the Bayesian calculations and applying the hierarchical model and (II) a data pre-processing part. The Bayesian core can be run independently, if the input data are sufficient (see below). The data pre-processing part was implemented to simplify the analysis for the user as all needed data pre-processing is done by the function, i.e. in theory it is enough to provide a BIN/BINX-file with the SAR measurement data. For the Bayesian analysis for each aliquot the following information are needed from the SAR analysis. LxTx, the LxTx error and the dose values for all regeneration points.

How is the systematic error contribution calculated?

Standard errors (so far) provided with the source dose rate are considered as systematic uncertainties and added to final central dose by:

$systematic.error = 1/n \sum SE(source.doserate)$

$SE(central.dose.final) = \sqrt{SE(central.dose)^2 + systematic.error^2}$

Please note that this approach is rather rough and can only be valid if the source dose rate errors, in case different readers had been used, are similar. In cases where more than one source dose rate is provided a warning is given.

Input / output scenarios

Various inputs are allowed for this function. Unfortunately this makes the function handling rather complex, but at the same time very powerful. Available scenarios:

(1) - object is BIN-file or link to a BIN-file

Finally it does not matter how the information of the BIN/BINX file are provided. The function supports (a) either a path to a file or directory or a list of file names or paths or (b) a Risoe.BINfileData object or a list of these objects. The latter one can be produced by using the function read_BIN2R, but this function is called automatically if only a file name and/or a path is provided. In both cases it will become the data that can be used for the analysis.

⁠[CSV_file = NULL]⁠

If no CSV file (or data frame with the same format) is provided, the function runs an automatic process that consists of the following steps:

1. Select all valid aliquots using the function verify_SingleGrainData

2. Calculate Lx/Tx values using the function calc_OSLLxTxRatio

3. Calculate De values using the function plot_GrowthCurve

These proceeded data are subsequently used in for the Bayesian analysis

⁠[CSV_file != NULL]⁠

If a CSV file is provided (or a data.frame containing similar information) the pre-processing phase consists of the following steps:

1. Calculate Lx/Tx values using the function calc_OSLLxTxRatio

2. Calculate De values using the function plot_GrowthCurve

The CSV file should contain a selection of the BIN-file names and the aliquots selected for the further analysis. This allows a manual selection of input data, as the automatic selection by verify_SingleGrainData might be not totally sufficient.

(2) - object ⁠RLum.Results object⁠

If an RLum.Results object is provided as input and(!) this object was previously created by the function analyse_baSAR() itself, the pre-processing part is skipped and the function starts directly with the Bayesian analysis. This option is very powerful as it allows to change parameters for the Bayesian analysis without the need to repeat the data pre-processing. If furthermore the argument aliquot_range is set, aliquots can be manually excluded based on previous runs.

method_control

These are arguments that can be passed directly to the Bayesian calculation core, supported arguments are:

User defined models

The function provides the option to modify and to define own models that can be used for the Bayesian calculation. In the case the user wants to modify a model, a new model can be piped into the function via the argument baSAR_model as character. The model has to be provided in the JAGS dialect of the BUGS language (cf. rjags::jags.model) and parameter names given with the pre-defined names have to be respected, otherwise the function will break.

FAQ

Q: How can I set the seed for the random number generator (RNG)?

A: Use the argument method_control, e.g., for three MCMC chains (as it is the default):

method_control = list(
inits = list(
 list(.RNG.name = "base::Wichmann-Hill", .RNG.seed = 1),
 list(.RNG.name = "base::Wichmann-Hill", .RNG.seed = 2),
 list(.RNG.name = "base::Wichmann-Hill", .RNG.seed = 3)
))

This sets a reproducible set for every chain separately.

Q: How can I modify the output plots?

A: You can't, but you can use the function output to create own, modified plots.

Q: Can I change the boundaries for the central_D?

A: Yes, we made it possible, but we DO NOT recommend it, except you know what you are doing!
Example: ⁠method_control = list(lower_centralD = 10))⁠

Q: The lines in the baSAR-model appear to be in a wrong logical order?

A: This is correct and allowed (cf. JAGS manual)

Additional arguments support via the ... argument

This list summarizes the additional arguments that can be passed to the internally used functions.

Value

Function returns results numerically and graphically:

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

RLum.Results-object

slot: ⁠@data⁠

slot: ⁠@info⁠

The original function call

————————
⁠[ PLOT OUTPUT ]⁠
————————

• (A) Ln/Tn curves with set integration limits,

• (B) trace plots are returned by the baSAR-model, showing the convergence of the parameters (trace) and the resulting kernel density plots. If plot_reduced = FALSE for every(!) dose a trace and a density plot is returned (this may take a long time),

• (C) dose plots showing the dose for every aliquot as boxplots and the marked HPD in within. If boxes are coloured 'orange' or 'red' the aliquot itself should be checked,

• (D) the dose response curve resulting from the monitoring of the Bayesian modelling are provided along with the Lx/Tx values and the HPD. Note: The amount for curves displayed is limited to 1000 (random choice) for performance reasons,

• (E) the final plot is the De distribution as calculated using the conventional (frequentist) approach and the central dose with the HPDs marked within. This figure is only provided for a comparison, no further statistical conclusion should be drawn from it.

Please note: If distribution was set to log_normal the central dose is given as geometric mean!

Function version

0.1.35

How to cite

Mercier, N., Kreutzer, S., 2024. analyse_baSAR(): Bayesian models (baSAR) applied on luminescence data. Function version 0.1.33. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Note

If you provide more than one BIN-file, it is strongly recommended to provide a list with the same number of elements for the following parameters:

source_doserate, signal.integral, signal.integral.Tx, background.integral, background.integral.Tx, sigmab, sig0.

Example for two BIN-files: source_doserate = list(c(0.04, 0.006), c(0.05, 0.006))

The function is currently limited to work with standard Risoe BIN-files only!

Author(s)

Norbert Mercier, Archaésciences Bordeaux, CNRS-Université Bordeaux Montaigne (France)
Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany)
The underlying Bayesian model based on a contribution by Combès et al., 2015. , RLum Developer Team

References

Combès, 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. doi:10.1016/j.quageo.2015.04.001

Mercier, N., Kreutzer, S., Christophe, C., Guerin, G., Guibert, P., Lahaye, C., Lanos, P., Philippe, A., Tribolo, C., 2016. Bayesian statistics in luminescence dating: The 'baSAR'-model and its implementation in the R package 'Luminescence'. Ancient TL 34, 14-21.

Further reading

Gelman, A., Carlin, J.B., Stern, H.S., Dunson, D.B., Vehtari, A., Rubin, D.B., 2013. Bayesian Data Analysis, Third Edition. CRC Press.

Murray, A.S., Wintle, A.G., 2000. Luminescence dating of quartz using an improved single-aliquot regenerative-dose protocol. Radiation Measurements 32, 57-73. doi:10.1016/S1350-4487(99)00253-X

Plummer, M., 2017. JAGS Version 4.3.0 user manual. ⁠https://sourceforge.net/projects/mcmc-jags/files/Manuals/4.x/jags_user_manual.pdf/download⁠

See Also

read_BIN2R, calc_OSLLxTxRatio, plot_GrowthCurve, data.table::fread, verify_SingleGrainData, rjags::jags.model, rjags::coda.samples, boxplot.default

Examples

##(1) load package test data set
data(ExampleData.BINfileData, envir = environment())

##(2) selecting relevant curves, and limit dataset
CWOSL.SAR.Data <- subset(
  CWOSL.SAR.Data,
  subset = POSITION%in%c(1:3) & LTYPE == "OSL")

## Not run: 
##(3) run analysis
##please not that the here selected parameters are
##choosen for performance, not for reliability
results <- analyse_baSAR(
  object = CWOSL.SAR.Data,
  source_doserate = c(0.04, 0.001),
  signal.integral = c(1:2),
  background.integral = c(80:100),
  fit.method = "LIN",
  plot = FALSE,
  n.MCMC = 200

)

print(results)


##CSV_file template
##copy and paste this the code below in the terminal
##you can further use the function write.csv() to export the example

CSV_file <-
structure(
list(
 BIN_FILE = NA_character_,
 DISC = NA_real_,
 GRAIN = NA_real_),
   .Names = c("BIN_FILE", "DISC", "GRAIN"),
   class = "data.frame",
   row.names = 1L
)


## End(Not run)

Description

The function analysis fading measurements and returns a fading rate including an error estimation. The function is not limited to standard fading measurements, as can be seen, e.g., Huntley and Lamothe (2001). Additionally, the density of recombination centres (rho') is estimated after Kars et al. (2008).

Usage

analyse_FadingMeasurement(
  object,
  structure = c("Lx", "Tx"),
  signal.integral,
  background.integral,
  t_star = "half",
  n.MC = 100,
  verbose = TRUE,
  plot = TRUE,
  plot_singlePanels = FALSE,
  ...
)

Arguments

Details

All provided output corresponds to the $tc$ value obtained by this analysis. Additionally in the output object the g-value normalised to 2-days is provided. The output of this function can be passed to the function calc_FadingCorr.

Fitting and error estimation

For the fitting the function stats::lm is used without applying weights. For the error estimation all input values, except tc, as the precision can be considered as sufficiently high enough with regard to the underlying problem, are sampled assuming a normal distribution for each value with the value as the mean and the provided uncertainty as standard deviation.

The options for t_star

• t_star = "half" (the default) The calculation follows the simplified version in Auclair et al. (2003), which reads

  $t_{star} := t_1 + (t_2 - t_1)/2$

• t_star = "half_complex" This option applies the complex function shown in Auclair et al. (2003), which is derived from Aitken (1985) appendix F, equations 9 and 11. It reads

  $t_{star} = t0 * 10^[(t_2 log(t_2/t_0) - t_1 log(t_1/t_0) - 0.43(t_2 - t_1))/(t_2 - t_1)]$

  where 0.43 = $1/ln(10)$. t0, which is an arbitrary constant, is set to 1. Please note that the equation in Auclair et al. (2003) is incorrect insofar that it reads $10exp(...)$, where the base should be 10 and not the Euler's number. Here we use the correct version (base 10).

• t_star = "end" This option uses the simplest possible form for t_star which is the time since irradiation without taking into account any addition parameter and it equals t1 in Auclair et al. (2003)

• ⁠t_star = <function>⁠ This last option allows you to provide an R function object that works on t1 and gives you all possible freedom. For instance, you may want to define the following function fun <- function(x) {x^2}, this would square all values of t1, because internally it calls fun(t1). The name of the function does not matter.

Density of recombination centres

The density of recombination centres, expressed by the dimensionless variable rho', is estimated by fitting equation 5 in Kars et al. (2008) to the data. For the fitting the function stats::nls is used without applying weights. For the error estimation the same procedure as for the g-value is applied (see above).

Multiple aliquots & Lx/Tx normalisation

Be aware that this function will always normalise all $\frac{L_x}{T_x}$ values by the $\frac{L_x}{T_x}$ value of the prompt measurement of the first aliquot. This implicitly assumes that there are no systematic inter-aliquot variations in the $\frac{L_x}{T_x}$ values. If deemed necessary to normalise the $\frac{L_x}{T_x}$ values of each aliquot by its individual prompt measurement please do so before running analyse_FadingMeasurement and provide the already normalised values for object instead.

Shine-down curve plots Please note that the shine-down curve plots are for information only. As such not all pause steps are plotted to avoid graphically overloaded plots. However, all pause times are taken into consideration for the analysis.

Value

An RLum.Results object is returned:

Slot: @data

Slot: @info

Function version

0.1.23

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany)
Christoph Burow, University of Cologne (Germany)

References

Aitken, M.J., 1985. Thermoluminescence dating, Studies in archaeological science. Academic Press, London, Orlando.

Auclair, M., Lamothe, M., Huot, S., 2003. Measurement of anomalous fading for feldspar IRSL using SAR. Radiation Measurements 37, 487-492. doi:10.1016/S1350-4487(03)00018-0

Huntley, D.J., Lamothe, M., 2001. Ubiquity of anomalous fading in K-feldspars and the measurement and correction for it in optical dating. Canadian Journal of Earth Sciences 38, 1093-1106. doi: 10.1139/cjes-38-7-1093

Kars, R.H., Wallinga, J., Cohen, K.M., 2008. A new approach towards anomalous fading correction for feldspar IRSL dating-tests on samples in field saturation. Radiation Measurements 43, 786-790. doi:10.1016/j.radmeas.2008.01.021

See Also

calc_OSLLxTxRatio, read_BIN2R, read_XSYG2R, extract_IrradiationTimes, calc_FadingCorr

Examples

## load example data (sample UNIL/NB123, see ?ExampleData.Fading)
data("ExampleData.Fading", envir = environment())

##(1) get fading measurement data (here a three column data.frame)
fading_data <- ExampleData.Fading$fading.data$IR50

##(2) run analysis
g_value <- analyse_FadingMeasurement(
fading_data,
plot = TRUE,
verbose = TRUE,
n.MC = 10)

##(3) this can be further used in the function
## to correct the age according to Huntley & Lamothe, 2001
results <- calc_FadingCorr(
age.faded = c(100,2),
g_value = g_value,
n.MC = 10)

Description

Function to analyse IRSAR RF measurements on K-feldspar samples, performed using the protocol according to Erfurt et al. (2003) and beyond.

Usage

analyse_IRSAR.RF(
  object,
  sequence_structure = c("NATURAL", "REGENERATED"),
  RF_nat.lim = NULL,
  RF_reg.lim = NULL,
  method = "FIT",
  method_control = NULL,
  test_parameters = NULL,
  n.MC = 10,
  txtProgressBar = TRUE,
  plot = TRUE,
  plot_reduced = FALSE,
  ...
)

Arguments

Details

The function performs an IRSAR analysis described for K-feldspar samples by Erfurt et al. (2003) assuming a negligible sensitivity change of the RF signal.

General Sequence Structure (according to Erfurt et al., 2003)

1. Measuring IR-RF intensity of the natural dose for a few seconds ($RF_{nat}$)

2. Bleach the samples under solar conditions for at least 30 min without changing the geometry

3. Waiting for at least one hour

4. Regeneration of the IR-RF signal to at least the natural level (measuring ($RF_{reg}$)

5. Fitting data with a stretched exponential function

6. Calculate the the palaeodose $D_{e}$ using the parameters from the fitting

Actually three methods are supported to obtain the $D_{e}$: method = "FIT", method = "SLIDE" and method = "VSLIDE":

method = "FIT"

The principle is described above and follows the original suggestions by Erfurt et al., 2003. For the fitting the mean count value of the RF_nat curve is used.

Function used for the fitting (according to Erfurt et al. (2003)):

$\phi(D) = \phi_{0}-\Delta\phi(1-exp(-\lambda*D))^\beta$

with $\phi(D)$ the dose dependent IR-RF flux, $\phi_{0}$ the initial IR-RF flux, $\Delta\phi$ the dose dependent change of the IR-RF flux, $\lambda$ the exponential parameter, $D$ the dose and $\beta$ the dispersive factor.

To obtain the palaeodose $D_{e}$ the function is changed to:

$D_{e} = ln(-(\phi(D) - \phi_{0})/(-\lambda*\phi)^{1/\beta}+1)/-\lambda$

The fitting is done using the port algorithm of the nls function.

method = "SLIDE"

For this method, the natural curve is slid along the x-axis until congruence with the regenerated curve is reached. As opposed to fitting, this allows working with the original data without the need for any physical model. This approach was introduced for RF curves by Buylaert et al., 2012 and Lapp et al., 2012.

Here the sliding is done by searching for the minimum of the sum of squared residuals. For the mathematical details of the implementation see Frouin et al., 2017

method = "VSLIDE"

Same as "SLIDE" but searching also vertically for the best match (i.e. in xy-direction.) See Kreutzer et al. (2017) and Murari et al. (2021). By default the vertical sliding range is set automatically, but can be set manually by changing the vslide_range parameter (see method_control).

method_control

To keep the generic argument list as clear as possible, parameters to control the methods for De estimation are preset with meaningful default values, which can however be modified using the method_control argument, e.g., method_control = list(trace = TRUE). Supported parameters are:

Error estimation

For method = "FIT" the asymmetric error range is obtained by using the 2.5 % (lower) and the 97.5 % (upper) quantiles of the $RF_{nat}$ curve for calculating the $D_{e}$ error range.

For method = "SLIDE" and method = "VSLIDE" the error is obtained by bootstrapping the residuals of the slid curve to construct new natural curves for a Monte Carlo simulation. The error is returned in two ways: (a) the standard deviation of the $D_{e}$ obtained from the MC runs and (b) the confidence interval using the 2.5 % (lower) and the 97.5 % (upper) quantiles. The results of the MC runs are returned with the function output.

Test parameters

The argument test_parameters allows to pass some thresholds for several test parameters, which will be evaluated during the function run. If a threshold is set and it is exceeded, the test parameter status will be set to "FAILED". Intentionally this parameter is not termed 'rejection criteria' as not all test parameters are evaluated for both methods and some parameters are calculated but not evaluated by default. Common for all parameters are the allowed argument options NA and NULL. If the parameter is set to NA the value is calculated but the result will not be evaluated, therefore it will have no effect on the status ("OK" or "FAILED") of the parameter. Setting the parameter to NULL disables the parameter entirely and the parameter will be also removed from the function output. This might be useful in cases where a particular parameter requires a long computation time. Currently supported parameters are:

curves_ratio numeric (default: 1.001):

The ratio of $RF_{nat}$ over $RF_{reg}$ in the range of$RF_{nat}$ of is calculated and should not exceed the threshold value.

intersection_ratio numeric (default: NA):

Calculated as absolute difference from 1 of the ratio of the integral of the normalised RF-curves, This value indicates intersection of the RF-curves and should be close to 0 if the curves have a similar shape. For this calculation first the corresponding time-count pair value on the RF_reg curve is obtained using the maximum count value of the RF_nat curve and only this segment (fitting to the RF_nat curve) on the RF_reg curve is taken for further calculating this ratio. If nothing is found at all, Inf is returned.

residuals_slope numeric (default: NA; only for method = "SLIDE"):

A linear function is fitted on the residuals after sliding. The corresponding slope can be used to discard values as a high (positive, negative) slope may indicate that both curves are fundamentally different and the method cannot be applied at all. Per default the value of this parameter is calculated but not evaluated.

curves_bounds numeric (default: $max(RF_{reg_counts})$:

This measure uses the maximum time (x) value of the regenerated curve. The maximum time (x) value of the natural curve cannot be larger than this value. However, although this is not recommended the value can be changed or disabled.

dynamic_ratio numeric (default: NA):

The dynamic ratio of the regenerated curve is calculated as ratio of the minimum and maximum count values.

lambda, beta and delta.phi numeric (default: NA; method = "SLIDE"):

The stretched exponential function suggested by Erfurt et al. (2003) describing the decay of the RF signal, comprises several parameters that might be useful to evaluate the shape of the curves. For method = "FIT" this parameter is obtained during the fitting, for method = "SLIDE" a rather rough estimation is made using the function minpack.lm::nlsLM and the equation given above. Note: As this procedure requests more computation time, setting of one of these three parameters to NULL also prevents a calculation of the remaining two.

Value

The function returns numerical output and an (optional) plot.

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

RLum.Results-object

slot: ⁠@data⁠

⁠[.. $data : data.frame]⁠

⁠[.. $De.MC : numeric]⁠

A numeric vector with all the De values obtained by the MC runs.

⁠[.. $test_parameters : data.frame]⁠

⁠[.. $fit : data.frame]⁠

An nls object produced by the fitting.

⁠[.. $slide : list]⁠

A list with data produced during the sliding. Some elements are previously reported with the summary object data. List elements are:

slot: ⁠@info⁠

The original function call (methods::language-object)

The output (data) should be accessed using the function get_RLum

————————
⁠[ PLOT OUTPUT ]⁠
————————

The slid IR-RF curves with the finally obtained De

Function version

0.7.10

How to cite

Kreutzer, S., 2024. analyse_IRSAR.RF(): Analyse IRSAR RF measurements. Function version 0.7.10. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Note

This function assumes that there is no sensitivity change during the measurements (natural vs. regenerated signal), which is in contrast to the findings by Buylaert et al. (2012).

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team

References

Buylaert, J.P., Jain, M., Murray, A.S., Thomsen, K.J., Lapp, T., 2012. IR-RF dating of sand-sized K-feldspar extracts: A test of accuracy. Radiation Measurements 44 (5-6), 560-565. doi: 10.1016/j.radmeas.2012.06.021

Erfurt, G., Krbetschek, M.R., 2003. IRSAR - A single-aliquot regenerative-dose dating protocol applied to the infrared radiofluorescence (IR-RF) of coarse- grain K-feldspar. Ancient TL 21, 35-42.

Erfurt, G., 2003. Infrared luminescence of Pb+ centres in potassium-rich feldspars. physica status solidi (a) 200, 429-438.

Erfurt, G., Krbetschek, M.R., 2003. Studies on the physics of the infrared radioluminescence of potassium feldspar and on the methodology of its application to sediment dating. Radiation Measurements 37, 505-510.

Erfurt, G., Krbetschek, M.R., Bortolot, V.J., Preusser, F., 2003. A fully automated multi-spectral radioluminescence reading system for geochronometry and dosimetry. Nuclear Instruments and Methods in Physics Research Section B: Beam Interactions with Materials and Atoms 207, 487-499.

Frouin, M., Huot, S., Kreutzer, S., Lahaye, C., Lamothe, M., Philippe, A., Mercier, N., 2017. An improved radiofluorescence single-aliquot regenerative dose protocol for K-feldspars. Quaternary Geochronology 38, 13-24. doi:10.1016/j.quageo.2016.11.004

Kreutzer, S., Murari, M.K., Frouin, M., Fuchs, M., Mercier, N., 2017. Always remain suspicious: a case study on tracking down a technical artefact while measuring IR-RF. Ancient TL 35, 20–30.

Murari, M.K., Kreutzer, S., Fuchs, M., 2018. Further investigations on IR-RF: Dose recovery and correction. Radiation Measurements 120, 110–119. doi: 10.1016/j.radmeas.2018.04.017

Lapp, T., Jain, M., Thomsen, K.J., Murray, A.S., Buylaert, J.P., 2012. New luminescence measurement facilities in retrospective dosimetry. Radiation Measurements 47, 803-808. doi:10.1016/j.radmeas.2012.02.006

Trautmann, T., 2000. A study of radioluminescence kinetics of natural feldspar dosimeters: experiments and simulations. Journal of Physics D: Applied Physics 33, 2304-2310.

Trautmann, T., Krbetschek, M.R., Dietrich, A., Stolz, W., 1998. Investigations of feldspar radioluminescence: potential for a new dating technique. Radiation Measurements 29, 421-425.

Trautmann, T., Krbetschek, M.R., Dietrich, A., Stolz, W., 1999. Feldspar radioluminescence: a new dating method and its physical background. Journal of Luminescence 85, 45-58.

Trautmann, T., Krbetschek, M.R., Stolz, W., 2000. A systematic study of the radioluminescence properties of single feldspar grains. Radiation Measurements 32, 685-690.

** Further reading**

Murari, M.K., Kreutzer, S., King, G.E., Frouin, M., Tsukamoto, S., Schmidt, C., Lauer, T., Klasen, N., Richter, D., Friedrich, J., Mercier, N., Fuchs, M., 2021. Infrared radiofluorescence (IR-RF) dating: A review. Quaternary Geochronology 64, 101155. doi: 10.1016/j.quageo.2021.101155

See Also

RLum.Analysis, RLum.Results, get_RLum, nls, minpack.lm::nlsLM, parallel::mclapply

Examples

##load data
data(ExampleData.RLum.Analysis, envir = environment())

##(1) perform analysis using the method 'FIT'
results <- analyse_IRSAR.RF(object = IRSAR.RF.Data)

##show De results and test paramter results
get_RLum(results, data.object = "data")
get_RLum(results, data.object = "test_parameters")

##(2) perform analysis using the method 'SLIDE'
results <- analyse_IRSAR.RF(object = IRSAR.RF.Data, method = "SLIDE", n.MC = 1)

## Not run: 
##(3) perform analysis using the method 'SLIDE' and method control option
## 'trace
results <- analyse_IRSAR.RF(
 object = IRSAR.RF.Data,
 method = "SLIDE",
 method_control = list(trace = TRUE))

## End(Not run)

Description

The function performs an analysis of post-IR IRSL sequences including curve fitting on RLum.Analysis objects.

Usage

analyse_pIRIRSequence(
  object,
  signal.integral.min,
  signal.integral.max,
  background.integral.min,
  background.integral.max,
  dose.points = NULL,
  sequence.structure = c("TL", "IR50", "pIRIR225"),
  plot = TRUE,
  plot_singlePanels = FALSE,
  ...
)

Arguments

Details

To allow post-IR IRSL protocol (Thomsen et al., 2008) measurement analyses this function has been written as extended wrapper function for the function analyse_SAR.CWOSL, facilitating an entire sequence analysis in one run. With this, its functionality is strictly limited by the functionality of the function analyse_SAR.CWOSL.

Defining the sequence structure

The argument sequence.structure expects a shortened pattern of your sequence structure and was mainly introduced to ease the use of the function. For example: If your measurement data contains the following curves: TL, IRSL, IRSL, TL, IRSL, IRSL, the sequence pattern in sequence.structure becomes c('TL', 'IRSL', 'IRSL'). The second part of your sequence for one cycle should be similar and can be discarded. If this is not the case (e.g., additional hotbleach) such curves have to be removed before using the function.

If the input is a list

If the input is a list of RLum.Analysis-objects, every argument can be provided as list to allow for different sets of parameters for every single input element. For further information see analyse_SAR.CWOSL.

Value

Plots (optional) and an RLum.Results object is returned containing the following elements:

The output should be accessed using the function get_RLum.

Function version

0.2.5

How to cite

Kreutzer, S., 2024. analyse_pIRIRSequence(): Analyse post-IR IRSL measurement sequences. Function version 0.2.4. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Note

Best graphical output can be achieved by using the function pdf with the following options:

pdf(file = "<YOUR FILENAME>", height = 15, width = 15)

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team

References

Murray, A.S., Wintle, A.G., 2000. Luminescence dating of quartz using an improved single-aliquot regenerative-dose protocol. Radiation Measurements 32, 57-73. doi:10.1016/S1350-4487(99)00253-X

Thomsen, K.J., Murray, A.S., Jain, M., Boetter-Jensen, L., 2008. Laboratory fading rates of various luminescence signals from feldspar-rich sediment extracts. Radiation Measurements 43, 1474-1486. doi:10.1016/j.radmeas.2008.06.002

See Also

analyse_SAR.CWOSL, calc_OSLLxTxRatio, plot_GrowthCurve, RLum.Analysis, RLum.Results get_RLum

Examples

### NOTE: For this example existing example data are used. These data are non pIRIR data.
###
##(1) Compile example data set based on existing example data (SAR quartz measurement)
##(a) Load example data
data(ExampleData.BINfileData, envir = environment())

##(b) Transform the values from the first position in a RLum.Analysis object
object <- Risoe.BINfileData2RLum.Analysis(CWOSL.SAR.Data, pos=1)

##(c) Grep curves and exclude the last two (one TL and one IRSL)
object <- get_RLum(object, record.id = c(-29,-30))

##(d) Define new sequence structure and set new RLum.Analysis object
sequence.structure  <- c(1,2,2,3,4,4)
sequence.structure <- as.vector(sapply(seq(0,length(object)-1,by = 4),
                                       function(x){sequence.structure + x}))

object <-  sapply(1:length(sequence.structure), function(x){

  object[[sequence.structure[x]]]

})

object <- set_RLum(class = "RLum.Analysis", records = object, protocol = "pIRIR")

##(2) Perform pIRIR analysis (for this example with quartz OSL data!)
## Note: output as single plots to avoid problems with this example
results <- analyse_pIRIRSequence(object,
     signal.integral.min = 1,
     signal.integral.max = 2,
     background.integral.min = 900,
     background.integral.max = 1000,
     fit.method = "EXP",
     sequence.structure = c("TL", "pseudoIRSL1", "pseudoIRSL2"),
     main = "Pseudo pIRIR data set based on quartz OSL",
     plot_singlePanels = TRUE)


##(3) Perform pIRIR analysis (for this example with quartz OSL data!)
## Alternative for PDF output, uncomment and complete for usage
## Not run: 
tempfile <- tempfile(fileext = ".pdf")
pdf(file = tempfile, height = 15, width = 15)
  results <- analyse_pIRIRSequence(object,
         signal.integral.min = 1,
         signal.integral.max = 2,
         background.integral.min = 900,
         background.integral.max = 1000,
         fit.method = "EXP",
         main = "Pseudo pIRIR data set based on quartz OSL")

  dev.off()

## End(Not run)

Description

The function analyses CW-OSL curve data produced by a SUERC portable OSL reader and produces a combined plot of OSL/IRSL signal intensities, OSL/IRSL depletion ratios and the IRSL/OSL ratio.

Usage

analyse_portableOSL(
  object,
  signal.integral = NULL,
  invert = FALSE,
  normalise = FALSE,
  mode = "profile",
  coord = NULL,
  plot = TRUE,
  ...
)

Arguments

Details

This function only works with RLum.Analysis objects produced by read_PSL2R. It further assumes (or rather requires) an equal amount of OSL and IRSL curves that are pairwise combined for calculating the IRSL/OSL ratio. For calculating the depletion ratios the cumulative signal of the last n channels (same number of channels as specified by signal.integral) is divided by cumulative signal of the first n channels (signal.integral).

Note: The function assumes the following sequence pattern: ⁠DARK COUNT⁠, IRSL, ⁠DARK COUNT⁠, BSL, ⁠DARK COUNT⁠. If you have written a different sequence, the analysis function will (likely) not work!.

Signal processing The function processes the signals as follows: BSL and IRSL signals are extracted using the chosen signal integral, dark counts are taken in full.

Working with coordinates Usually samples are taken from a profile with a certain stratigraphy. In the past the function calculated an index. With this newer version, you have two option of passing on xy-coordinates to the function:

• (1) Add coordinates to the sample name during measurement. The form is rather strict and has to follow the scheme ⁠_x:<number>|y:<number>⁠. Example: sample_x:0.2|y:0.4.

• (2) Alternatively, you can provide a list or matrix with the sample coordinates. Example: coord = list(c(0.2, 1), c(0.3,1.2))

Please note that the unit is meter (m) and the function expects always xy-coordinates. The latter one is useful for surface interpolations. If you have measured a profile where the x-coordinates to not measure, x-coordinates should be 0.

Value

Returns an S4 RLum.Results object with the following elements:

⁠$data⁠
.. $summary: data.frame with the results
.. $data: list with the RLum.Analysis objects
.. $args: list the input arguments

Function version

0.1.1

How to cite

Burow, C., Kreutzer, S., 2024. analyse_portableOSL(): Analyse portable CW-OSL measurements. Function version 0.1.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Author(s)

Christoph Burow, University of Cologne (Germany), Sebastian Kreutzer, Institute of Geography, Ruprecht-Karl University of Heidelberg, Germany , RLum Developer Team

See Also

RLum.Analysis, RLum.Data.Curve, read_PSL2R

Examples

## example profile plot
# (1) load example data set
data("ExampleData.portableOSL", envir = environment())

# (2) merge and plot all RLum.Analysis objects
merged <- merge_RLum(ExampleData.portableOSL)
plot_RLum(
 object = merged,
 combine = TRUE,
 records_max = 5,
 legend.pos = "outside")
merged

# (3) analyse and plot
results <- analyse_portableOSL(
  merged,
  signal.integral = 1:5,
  invert = FALSE,
  normalise = TRUE)
get_RLum(results)

Description

The function performs a SAR CW-OSL analysis on an RLum.Analysis object including growth curve fitting.

Usage

analyse_SAR.CWOSL(
  object,
  signal.integral.min = NA,
  signal.integral.max = NA,
  background.integral.min = NA,
  background.integral.max = NA,
  OSL.component = NULL,
  rejection.criteria = list(),
  dose.points = NULL,
  trim_channels = FALSE,
  mtext.outer = "",
  plot = TRUE,
  plot_onePage = FALSE,
  plot_singlePanels = FALSE,
  onlyLxTxTable = FALSE,
  ...
)

Arguments

Details

The function performs an analysis for a standard SAR protocol measurements introduced by Murray and Wintle (2000) with CW-OSL curves. For the calculation of the Lx/Tx value the function calc_OSLLxTxRatio is used. For changing the way the Lx/Tx error is calculated use the argument background.count.distribution and sigmab, which will be passed to the function calc_OSLLxTxRatio.

What is part of a SAR sequence?

The function is rather picky when it comes down to accepted curve input (OSL,IRSL,...) and structure. A SAR sequence is basically a set of $L_{x}/T_{x}$ curves. Hence, every 2nd curve is considered a shine-down curve related to the test dose. It also means that the number of curves for $L_{x}$ has to be equal to the number of $T_{x}$ curves, and that hot-bleach curves do not belong into a SAR sequence; at least not for the analysis. Other curves allowed and processed are preheat curves, or preheat curves measured as TL, and irradiation curves. The later one indicates the duration of the irradiation, the dose and test dose points, e.g., as part of XSYG files.

Argument object is of type list

If the argument object is of type list containing only RLum.Analysis objects, the function re-calls itself as often as elements are in the list. This is useful if an entire measurement wanted to be analysed without writing separate for-loops. To gain in full control of the parameters (e.g., dose.points) for every aliquot (corresponding to one RLum.Analysis object in the list), in this case the arguments can be provided as list. This list should be of similar length as the list provided with the argument object, otherwise the function will create an own list of the requested length. Function output will be just one single RLum.Results object.

Please be careful when using this option. It may allow a fast an efficient data analysis, but the function may also break with an unclear error message, due to wrong input data.

Working with IRSL data

The function was originally designed to work just for 'OSL' curves, following the principles of the SAR protocol. An IRSL measurement protocol may follow this procedure, e.g., post-IR IRSL protocol (Thomsen et al., 2008). Therefore this functions has been enhanced to work with IRSL data, however, the function is only capable of analysing curves that follow the SAR protocol structure, i.e., to analyse a post-IR IRSL protocol, curve data have to be pre-selected by the user to fit the standards of the SAR protocol, i.e., Lx,Tx,Lx,Tx and so on.

Example: Imagine the measurement contains pIRIR50 and pIRIR225 IRSL curves. Only one curve type can be analysed at the same time: The pIRIR50 curves or the pIRIR225 curves.

Supported rejection criteria

⁠[recycling.ratio]⁠: calculated for every repeated regeneration dose point.

⁠[recuperation.rate]⁠: recuperation rate calculated by comparing the Lx/Tx values of the zero regeneration point with the Ln/Tn value (the Lx/Tx ratio of the natural signal). For methodological background see Aitken and Smith (1988). As a variant with the argument recuperation_reference another dose point can be selected as reference instead of Ln/Tn.

⁠[testdose.error]⁠: set the allowed error for the test dose, which per default should not exceed 10%. The test dose error is calculated as Tx_net.error/Tx_net. The calculation of the $T_{n}$ error is detailed in calc_OSLLxTxRatio.

⁠[palaeodose.error]⁠: set the allowed error for the De value, which per default should not exceed 10%.

Irradiation times

The function makes two attempts to extra irradiation data (dose points) automatically from the input object, if the argument dose.points was not set (aka set to NULL).

1. It searches in every curve for an info object called IRR_TIME. If this was set, any value set here is taken as dose point.

2. If the object contains curves of type irradiation, the function tries to use this information to assign these values to the curves. However, the function does not overwrite values preset in IRR_TIME.

Value

A plot (optional) and an RLum.Results object is returned containing the following elements:

The output should be accessed using the function get_RLum.

Function version

0.10.3

How to cite

Kreutzer, S., 2024. analyse_SAR.CWOSL(): Analyse SAR CW-OSL measurements. Function version 0.10.3. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Note

This function must not be mixed up with the function Analyse_SAR.OSLdata, which works with Risoe.BINfileData objects.

The function currently does support only 'OSL', 'IRSL' and 'POSL' data!

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team

References

Aitken, M.J. and Smith, B.W., 1988. Optical dating: recuperation after bleaching. Quaternary Science Reviews 7, 387-393.

Duller, G., 2003. Distinguishing quartz and feldspar in single grain luminescence measurements. Radiation Measurements, 37 (2), 161-165.

Murray, A.S. and Wintle, A.G., 2000. Luminescence dating of quartz using an improved single-aliquot regenerative-dose protocol. Radiation Measurements 32, 57-73.

Thomsen, K.J., Murray, A.S., Jain, M., Boetter-Jensen, L., 2008. Laboratory fading rates of various luminescence signals from feldspar-rich sediment extracts. Radiation Measurements 43, 1474-1486. doi:10.1016/j.radmeas.2008.06.002

See Also

calc_OSLLxTxRatio, plot_GrowthCurve, RLum.Analysis, RLum.Results, get_RLum

Examples

##load data
##ExampleData.BINfileData contains two BINfileData objects
##CWOSL.SAR.Data and TL.SAR.Data
data(ExampleData.BINfileData, envir = environment())

##transform the values from the first position in a RLum.Analysis object
object <- Risoe.BINfileData2RLum.Analysis(CWOSL.SAR.Data, pos=1)

##perform SAR analysis and set rejection criteria
results <- analyse_SAR.CWOSL(
object = object,
signal.integral.min = 1,
signal.integral.max = 2,
background.integral.min = 900,
background.integral.max = 1000,
log = "x",
fit.method = "EXP",
rejection.criteria = list(
  recycling.ratio = 10,
  recuperation.rate = 10,
  testdose.error = 10,
  palaeodose.error = 10,
  recuperation_reference = "Natural",
  exceed.max.regpoint = TRUE)
)

##show De results
get_RLum(results)

##show LnTnLxTx table
get_RLum(results, data.object = "LnLxTnTx.table")

Description

The function analyses SAR CW-OSL curve data and provides a summary of the measured data for every position. The output of the function is optimised for SAR OSL measurements on quartz.

The function works only for standard SAR protocol measurements introduced by Murray and Wintle (2000) with CW-OSL curves. For the calculation of the Lx/Tx value the function calc_OSLLxTxRatio is used.

Provided rejection criteria

⁠[recyling ratio]⁠: calculated for every repeated regeneration dose point.

⁠[recuperation]⁠: recuperation rate calculated by comparing the Lx/Tx values of the zero regeneration point with the Ln/Tn value (the Lx/Tx ratio of the natural signal). For methodological background see Aitken and Smith (1988)

⁠[IRSL/BOSL]⁠: the integrated counts (signal.integral) of an IRSL curve are compared to the integrated counts of the first regenerated dose point. It is assumed that IRSL curves got the same dose as the first regenerated dose point. Note: This is not the IR depletion ratio described by Duller (2003).

Usage

Analyse_SAR.OSLdata(
  input.data,
  signal.integral,
  background.integral,
  position,
  run,
  set,
  dtype,
  keep.SEL = FALSE,
  info.measurement = "unknown measurement",
  output.plot = FALSE,
  plot_singlePanels = FALSE,
  cex.global = 1,
  ...
)

Arguments

Value

A plot (optional) and list is returned containing the following elements:

Function version

0.2.18

Note

Rejection criteria are calculated but not considered during the analysis to discard values.

The analysis of IRSL data is not directly supported. You may want to consider using the functions analyse_SAR.CWOSL or analyse_pIRIRSequence instead.

The development of this function will not be continued. We recommend to use the function analyse_SAR.CWOSL or instead.

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany)
Margret C. Fuchs, HZDR, Freiberg (Germany)

References

Aitken, M.J. and Smith, B.W., 1988. Optical dating: recuperation after bleaching. Quaternary Science Reviews 7, 387-393.

Duller, G., 2003. Distinguishing quartz and feldspar in single grain luminescence measurements. Radiation Measurements, 37 (2), 161-165.

Murray, A.S. and Wintle, A.G., 2000. Luminescence dating of quartz using an improved single-aliquot regenerative-dose protocol. Radiation Measurements 32, 57-73.

See Also

calc_OSLLxTxRatio, Risoe.BINfileData, read_BIN2R, fit_DoseResponseCurve

Examples

##load data
data(ExampleData.BINfileData, envir = environment())

##analyse data
suppressWarnings( # silence the deprecation warning
output <- Analyse_SAR.OSLdata(input.data = CWOSL.SAR.Data,
                              signal.integral = c(1:5),
                              background.integral = c(900:1000),
                              position = c(1:1),
                              output.plot = TRUE)
)

##combine results relevant for further analysis
output.SAR <- data.frame(Dose = output$LnLxTnTx[[1]]$Dose,
                         LxTx = output$LnLxTnTx[[1]]$LxTx,
                         LxTx.Error = output$LnLxTnTx[[1]]$LxTx.Error)
output.SAR

Description

The function performs a SAR TL analysis on a RLum.Analysis object including growth curve fitting.

Usage

analyse_SAR.TL(
  object,
  object.background,
  signal.integral.min,
  signal.integral.max,
  integral_input = "channel",
  sequence.structure = c("PREHEAT", "SIGNAL", "BACKGROUND"),
  rejection.criteria = list(recycling.ratio = 10, recuperation.rate = 10),
  dose.points,
  log = "",
  ...
)

Arguments

Details

This function performs a SAR TL analysis on a set of curves. The SAR procedure in general is given by Murray and Wintle (2000). For the calculation of the Lx/Tx value the function calc_TLLxTxRatio is used.

Provided rejection criteria

⁠[recycling.ratio]⁠: calculated for every repeated regeneration dose point.

⁠[recuperation.rate]⁠: recuperation rate calculated by comparing the Lx/Tx values of the zero regeneration point with the Ln/Tn value (the Lx/Tx ratio of the natural signal). For methodological background see Aitken and Smith (1988)

Value

A plot (optional) and an RLum.Results object is returned containing the following elements:

note: the output should be accessed using the function get_RLum

Function version

0.3.0

How to cite

Kreutzer, S., 2024. analyse_SAR.TL(): Analyse SAR TL measurements. Function version 0.3.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Note

THIS IS A BETA VERSION

None TL curves will be removed from the input object without further warning.

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team

References

Aitken, M.J. and Smith, B.W., 1988. Optical dating: recuperation after bleaching. Quaternary Science Reviews 7, 387-393.

Murray, A.S. and Wintle, A.G., 2000. Luminescence dating of quartz using an improved single-aliquot regenerative-dose protocol. Radiation Measurements 32, 57-73.

See Also

calc_TLLxTxRatio, fit_DoseResponseCurve, RLum.Analysis, RLum.Results, get_RLum

Examples

##load data
data(ExampleData.BINfileData, envir = environment())

##transform the values from the first position in a RLum.Analysis object
object <- Risoe.BINfileData2RLum.Analysis(TL.SAR.Data, pos=3)

##perform analysis
analyse_SAR.TL(
 object = object,
 signal.integral.min = 210,
 signal.integral.max = 220,
 fit.method = "EXP OR LIN",
 sequence.structure = c("SIGNAL", "BACKGROUND"))

Description

The function provides several methods for cosmic-ray removal and spectrum smoothing RLum.Data.Spectrum objects and such objects embedded in list or RLum.Analysis objects.

Usage

apply_CosmicRayRemoval(
  object,
  method = "smooth",
  method.Pych.smoothing = 2,
  method.Pych.threshold_factor = 3,
  MARGIN = 2,
  verbose = FALSE,
  plot = FALSE,
  ...
)

Arguments

Details

method = "Pych"

This method applies the cosmic-ray removal algorithm described by Pych (2003). Some aspects that are different to the publication:

• For interpolation between neighbouring values the median and not the mean is used.

• The number of breaks to construct the histogram is set to: length(number.of.input.values)/2

For further details see references below.

method = "smooth"

Method uses the function smooth to remove cosmic rays.

Arguments that can be passed are: kind, twiceit

method = "smooth.spline"

Method uses the function smooth.spline to remove cosmic rays.

Arguments that can be passed are: spar

How to combine methods?

Different methods can be combined by applying the method repeatedly to the dataset (see example).

Value

Returns same object as input.

Function version

0.3.0

How to cite

Kreutzer, S., 2024. apply_CosmicRayRemoval(): Function to remove cosmic rays from an RLum.Data.Spectrum S4 class object. Function version 0.3.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team

References

Pych, W., 2004. A Fast Algorithm for Cosmic-Ray Removal from Single Images. The Astronomical Society of the Pacific 116 (816), 148-153. doi:10.1086/381786

See Also

RLum.Data.Spectrum, RLum.Analysis, smooth, smooth.spline, apply_CosmicRayRemoval

Examples

##(1) - use with your own data and combine (uncomment for usage)
## run two times the default method and smooth with another method
## your.spectrum <- apply_CosmicRayRemoval(your.spectrum, method = "Pych")
## your.spectrum <- apply_CosmicRayRemoval(your.spectrum, method = "Pych")
## your.spectrum <- apply_CosmicRayRemoval(your.spectrum, method = "smooth")

Description

The function allows spectral efficiency corrections for RLum.Data.Spectrum S4 class objects

Usage

apply_EfficiencyCorrection(object, spectral.efficiency)

Arguments

Details

The efficiency correction is based on a spectral response dataset provided by the user. Usually the data set for the quantum efficiency is of lower resolution and values are interpolated for the required spectral resolution using the function stats::approx

If the energy calibration differs for both data set NA values are produces that will be removed from the matrix.

Value

Returns same object as provided as input

Function version

0.2.0

How to cite

Kreutzer, S., Friedrich, J., 2024. apply_EfficiencyCorrection(): Function to apply spectral efficiency correction to RLum.Data.Spectrum S4 class objects. Function version 0.2.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Note

Please note that the spectral efficiency data from the camera alone may not sufficiently correct for spectral efficiency of the entire optical system (e.g., spectrometer, camera ...).

Author(s)

Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS-Université Bordeaux Montaigne (France)
Johannes Friedrich, University of Bayreuth (Germany) , RLum Developer Team

See Also

RLum.Data.Spectrum, RLum.Analysis

Examples

##(1) - use with your own data (uncomment for usage)
## spectral.efficiency <- read.csv("your data")
##
## your.spectrum <- apply_EfficiencyCorrection(your.spectrum, )

Description

for ⁠[RLum.Analysis-class]⁠

for ⁠[RLum.Data.Curve-class]⁠

for ⁠[RLum.Data.Image-class]⁠

for ⁠[RLum.Data.Spectrum-class]⁠

for ⁠[RLum.Results-class]⁠

Arguments

Details

RLum.Analysis

Given that the list consists of RLum.Analysis objects.

RLum.Data.Curve

RLum.Data.Image

RLum.Data.Spectrum

RLum.Results

Given that the list consists of RLum.Results objects.

Note

Due to the complex structure of the RLum objects itself a coercing to standard R data structures will be always loosely!

See Also

methods::as

Description

Collection of published dose-rate conversion factors to convert concentrations of radioactive isotopes to dose rate values.

Format

A list with three elements with dose-rate conversion factors sorted by article and radiation type (alpha, beta, gamma):

Version

0.2.0

Source

All gamma conversion factors were carefully read from the tables given in the references above.

References

Adamiec, G., Aitken, M.J., 1998. Dose-rate conversion factors: update. Ancient TL 16, 37-46.

Cresswell., A.J., Carter, J., Sanderson, D.C.W., 2018. Dose rate conversion parameters: Assessment of nuclear data. Radiation Measurements 120, 195-201.

Guerin, G., Mercier, N., Adamiec, G., 2011. Dose-rate conversion factors: update. Ancient TL, 29, 5-8.

Liritzis, I., Stamoulis, K., Papachristodoulou, C., Ioannides, K., 2013. A re-evaluation of radiation dose-rate conversion factors. Mediterranean Archaeology and Archaeometry 13, 1-15.

Examples

## Load data
data("BaseDataSet.ConversionFactors", envir = environment())

Description

Collection of data from various sources needed for cosmic dose rate calculation

Format

$Dc = D0*(F+J*exp((altitude/1000)/H))$

Version

0.1

Source

The following data were carefully read from figures in mentioned sources and used for fitting procedures. The derived expressions are used in the function calc_CosmicDoseRate.

values.cosmic.Softcomp

For depths between 40-167 g cm^-2:

$y = 2*10^-6*x^2-0.0008*x+0.2535$

(For depths <40 g cm^-2)

$y = -6*10^-8*x^3+2*10^-5*x^2-0.0025*x+0.2969$

values.factor.Altitude

$y = -0.026*x^2 + 0.6628*x + 1.0435$

values.par.FJH

F (non-linear part, $\lambda$ < 36.5 deg.):

$y = -7*10^-7*x^3-8*10^-5*x^2-0.0009*x+0.3988$

F (linear part, $\lambda$ > 36.5 deg.):

$y = -0.0001*x + 0.2347$

J (non-linear part, $\lambda$ < 34 deg.):

$y = 5*10^-6*x^3-5*10^-5*x^2+0.0026*x+0.5177$

J (linear part, $\lambda$ > 34 deg.):

$y = 0.0005*x + 0.7388$

H (non-linear part, $\lambda$ < 36 deg.):

$y = -3*10^-6*x^3-5*10^-5*x^2-0.0031*x+4.398$

H (linear part, $\lambda$ > 36 deg.):

$y = 0.0002*x + 4.0914$

References

Gruen, R., 2009. The "AGE" program for the calculation of luminescence age estimates. Ancient TL, 27, pp. 45-46.

Prescott, J.R., Hutton, J.T., 1988. Cosmic ray and gamma ray dosimetry for TL and ESR. Nuclear Tracks and Radiation Measurements, 14, pp. 223-227.

Prescott, J.R., Hutton, J.T., 1994. Cosmic ray contributions to dose rates for luminescence and ESR dating: large depths and long-term time variations. Radiation Measurements, 23, pp. 497-500.

Examples

##load data
data(BaseDataSet.CosmicDoseRate)

Description

Collection of (un-)published fractional gamma dose-rate values to scale the gamma-dose rate considering layer-to-layer variations in soil radioactivity.

Format

A list with fractional gamma dose-rate values sorted by article:

Version

0.1

Source

Fractional gamma dose values were carefully read from the tables given in the references above.

References

Aitken, M.J., 1985. Thermoluminescence Dating. Academic Press, London.

Examples

## Load data
data("BaseDataSet.FractionalGammaDose", envir = environment())

Description

Grain size correction data for beta-dose rates published by Guérin et al. (2012).

#' @format

A data.frame seven columns and sixteen rows. Column headers are GrainSize, Q_K, FS_K, Q_Th, FS_Th, Q_U, FS_U. Grain sizes are quoted in µm (e.g., 20, 40, 60 etc.)

Version

0.1.0

Source

Guérin, G., Mercier, N., Nathan, R., Adamiec, G., Lefrais, Y., 2012. On the use of the infinite matrix assumption and associated concepts: A critical review. Radiation Measurements, 47, 778-785.

Examples

## load data
data("BaseDataSet.GrainSizeAttenuation", envir = environment())

Description

Function calls the object-specific bin functions for RLum.Data S4 class objects.

Usage

bin_RLum.Data(object, ...)

Arguments

Details

The function provides a generalised access point for specific RLum.Data objects.
Depending on the input object, the corresponding function will be selected. Allowed arguments can be found in the documentations of the corresponding RLum.Data class.

Value

An object of the same type as the input object is provided

Function version

0.2.0

How to cite

Kreutzer, S., 2024. bin_RLum.Data(): Channel binning - method dispatcher. Function version 0.2.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Note

Currently only RLum.Data objects of class RLum.Data.Curve and RLum.Data.Spectrum are supported!

Author(s)

Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team

See Also

RLum.Data.Curve, RLum.Data.Spectrum

Examples

##load example data
data(ExampleData.CW_OSL_Curve, envir = environment())

##create RLum.Data.Curve object from this example
curve <-
  set_RLum(
      class = "RLum.Data.Curve",
      recordType = "OSL",
      data = as.matrix(ExampleData.CW_OSL_Curve)
  )

##plot data without and with 2 and 4 channel binning
plot_RLum(curve)
plot_RLum(bin_RLum.Data(curve, bin_size = 2))
plot_RLum(bin_RLum.Data(curve, bin_size = 4))

Description

Estimate the number of grains on an aliquot. Alternatively, the packing density of an aliquot is computed.

Usage

calc_AliquotSize(
  grain.size,
  sample.diameter,
  packing.density = 0.65,
  MC = TRUE,
  grains.counted,
  plot = TRUE,
  ...
)

Arguments

Details

This function can be used to either estimate the number of grains on an aliquot or to compute the packing density depending on the the arguments provided.

The following function is used to estimate the number of grains n:

$n = (\pi*x^2)/(\pi*y^2)*d$

where x is the radius of the aliquot size (microns), y is the mean radius of the mineral grains (mm) and d is the packing density (value between 0 and 1).

Packing density

The default value for packing.density is 0.65, which is the mean of empirical values determined by Heer et al. (2012) and unpublished data from the Cologne luminescence laboratory. If packing.density = "Inf" a maximum density of $\pi/\sqrt12 = 0.9068\ldots$ is used. However, note that this value is not appropriate as the standard preparation procedure of aliquots resembles a PECC ("Packing Equal Circles in a Circle") problem where the maximum packing density is asymptotic to about 0.87.

Monte Carlo simulation

The number of grains on an aliquot can be estimated by Monte Carlo simulation when setting MC = TRUE. Each of the parameters necessary to calculate n (x, y, d) are assumed to be normally distributed with means $\mu_x, \mu_y, \mu_d$ and standard deviations $\sigma_x, \sigma_y, \sigma_d$.

For the mean grain size random samples are taken first from $N(\mu_y, \sigma_y)$, where $\mu_y = mean.grain.size$ and $\sigma_y = (max.grain.size-min.grain.size)/4$ so that 95\ grains are within the provided the grain size range. This effectively takes into account that after sieving the sample there is still a small chance of having grains smaller or larger than the used mesh sizes. For each random sample the mean grain size is calculated, from which random subsamples are drawn for the Monte Carlo simulation.

The packing density is assumed to be normally distributed with an empirically determined $\mu = 0.65$ (or provided value) and $\sigma = 0.18$. The normal distribution is truncated at d = 0.87 as this is approximately the maximum packing density that can be achieved in PECC problem.

The sample diameter has $\mu = sample.diameter$ and $\sigma = 0.2$ to take into account variations in sample disc preparation (i.e. applying silicon spray to the disc). A lower truncation point at x = 0.5 is used, which assumes that aliquots with smaller sample diameters of 0.5 mm are discarded. Likewise, the normal distribution is truncated at 9.8 mm, which is the diameter of the sample disc.

For each random sample drawn from the normal distributions the amount of grains on the aliquot is calculated. By default, 10^5 iterations are used, but can be reduced/increased with MC.iter (see ...). The results are visualised in a bar- and boxplot together with a statistical summary.

Value

Returns a terminal output. In addition an RLum.Results object is returned containing the following element:

The output should be accessed using the function get_RLum.

Function version

0.31

How to cite

Burow, C., 2024. calc_AliquotSize(): Estimate the amount of grains on an aliquot. Function version 0.31. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Author(s)

Christoph Burow, University of Cologne (Germany) , RLum Developer Team

References

Duller, G.A.T., 2008. Single-grain optical dating of Quaternary sediments: why aliquot size matters in luminescence dating. Boreas 37, 589-612.

Heer, A.J., Adamiec, G., Moska, P., 2012. How many grains are there on a single aliquot?. Ancient TL 30, 9-16.

Further reading

Chang, H.-C., Wang, L.-C., 2010. A simple proof of Thue's Theorem on Circle Packing. https://arxiv.org/pdf/1009.4322v1, 2013-09-13.

Graham, R.L., Lubachevsky, B.D., Nurmela, K.J., Oestergard, P.R.J., 1998. Dense packings of congruent circles in a circle. Discrete Mathematics 181, 139-154.

Huang, W., Ye, T., 2011. Global optimization method for finding dense packings of equal circles in a circle. European Journal of Operational Research 210, 474-481.

Examples

## Estimate the amount of grains on a small aliquot
calc_AliquotSize(grain.size = c(100,150), sample.diameter = 1, MC.iter = 100)

## Calculate the mean packing density of large aliquots
calc_AliquotSize(grain.size = c(100,200), sample.diameter = 8,
                 grains.counted = c(2525,2312,2880), MC.iter = 100)

Description

This functions calculates the Average Dose and their extrinsic dispersion and estimates the standard errors by bootstrapping based on the Average Dose Model by Guerin et al., 2017

Usage

calc_AverageDose(
  data,
  sigma_m,
  Nb_BE = 500,
  na.rm = TRUE,
  plot = TRUE,
  verbose = TRUE,
  ...
)

Arguments

Details

sigma_m

The program requires the input of a known value of sigma_m, which corresponds to the intrinsic overdispersion, as determined by a dose recovery experiment. Then the dispersion in doses (sigma_d) will be that over and above sigma_m (and individual uncertainties sigma_wi).

Value

The function returns numerical output and an (optional) plot.

———————————–
⁠[ NUMERICAL OUTPUT ]⁠
———————————–
RLum.Results-object

slot: ⁠@data⁠

⁠[.. $summary : data.frame]⁠

⁠[.. $dstar : matrix]⁠

Matrix with bootstrap values

⁠[.. $hist : list]⁠

Object as produced by the function histogram

————————
⁠[ PLOT OUTPUT ]⁠
————————

The function returns two different plot panels.

(1) An abanico plot with the dose values

(2) A histogram panel comprising 3 histograms with the equivalent dose and the bootstrapped average dose and the sigma values.

Function version

0.1.5

How to cite

Christophe, C., Philippe, A., Kreutzer, S., 2024. calc_AverageDose(): Calculate the Average Dose and the dose rate dispersion. Function version 0.1.5. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Note

This function has beta status!

Author(s)

Claire Christophe, IRAMAT-CRP2A, Université de Nantes (France), Anne Philippe, Université de Nantes, (France), Guillaume Guérin, IRAMAT-CRP2A, Université Bordeaux Montaigne, (France), Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team

References

Guerin, G., Christophe, C., Philippe, A., Murray, A.S., Thomsen, K.J., Tribolo, C., Urbanova, P., Jain, M., Guibert, P., Mercier, N., Kreutzer, S., Lahaye, C., 2017. Absorbed dose, equivalent dose, measured dose rates, and implications for OSL age estimates: Introducing the Average Dose Model. Quaternary Geochronology 1-32. doi:10.1016/j.quageo.2017.04.002

Further reading

Efron, B., Tibshirani, R., 1986. Bootstrap Methods for Standard Errors, Confidence Intervals, and Other Measures of Statistical Accuracy. Statistical Science 1, 54-75.

See Also

read.table, graphics::hist

Examples

##Example 01 using package example data
##load example data
data(ExampleData.DeValues, envir = environment())

##calculate Average dose
##(use only the first 56 values here)
AD <- calc_AverageDose(ExampleData.DeValues$CA1[1:56,], sigma_m = 0.1)

##plot De and set Average dose as central value
plot_AbanicoPlot(
 data = ExampleData.DeValues$CA1[1:56,],
 z.0 = AD$summary$AVERAGE_DOSE)

Description

This function calculates the central dose and dispersion of the De distribution, their standard errors and the profile log likelihood function for sigma.

Usage

calc_CentralDose(data, sigmab, log = TRUE, plot = TRUE, ...)

Arguments

Details

This function uses the equations of Galbraith & Roberts (2012). The parameters delta and sigma are estimated by numerically solving eq. 15 and 16. Their standard errors are approximated using eq. 17. In addition, the profile log-likelihood function for sigma is calculated using eq. 18 and presented as a plot. Numerical values of the maximum likelihood approach are only presented in the plot and not in the console. A detailed explanation on maximum likelihood estimation can be found in the appendix of Galbraith & Laslett (1993, 468-470) and Galbraith & Roberts (2012, 15)

Value

Returns a plot (optional) and terminal output. In addition an RLum.Results object is returned containing the following elements:

The output should be accessed using the function get_RLum

Function version

1.5

How to cite

Burow, C., 2024. calc_CentralDose(): Apply the central age model (CAM) after Galbraith et al. (1999) to a given De distribution. Function version 1.4.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Author(s)

Christoph Burow, University of Cologne (Germany)
Based on a rewritten S script of Rex Galbraith, 2010 , RLum Developer Team

References

Galbraith, R.F. & Laslett, G.M., 1993. Statistical models for mixed fission track ages. Nuclear Tracks Radiation Measurements 4, 459-470.

Galbraith, R.F., Roberts, R.G., Laslett, G.M., Yoshida, H. & Olley, J.M., 1999. Optical dating of single grains of quartz from Jinmium rock shelter, northern Australia. Part I: experimental design and statistical models. Archaeometry 41, 339-364.

Galbraith, R.F. & Roberts, R.G., 2012. Statistical aspects of equivalent dose and error calculation and display in OSL dating: An overview and some recommendations. Quaternary Geochronology 11, 1-27.

Further reading

Arnold, L.J. & Roberts, R.G., 2009. Stochastic modelling of multi-grain equivalent dose (De) distributions: Implications for OSL dating of sediment mixtures. Quaternary Geochronology 4, 204-230.

Bailey, R.M. & Arnold, L.J., 2006. Statistical modelling of single grain quartz De distributions and an assessment of procedures for estimating burial dose. Quaternary Science Reviews 25, 2475-2502.

Cunningham, A.C. & Wallinga, J., 2012. Realizing the potential of fluvial archives using robust OSL chronologies. Quaternary Geochronology 12, 98-106.

Rodnight, H., Duller, G.A.T., Wintle, A.G. & Tooth, S., 2006. Assessing the reproducibility and accuracy of optical dating of fluvial deposits. Quaternary Geochronology, 1 109-120.

Rodnight, H., 2008. How many equivalent dose values are needed to obtain a reproducible distribution?. Ancient TL 26, 3-10.

See Also

plot, calc_CommonDose, calc_FiniteMixture, calc_FuchsLang2001, calc_MinDose

Examples

##load example data
data(ExampleData.DeValues, envir = environment())

##apply the central dose model
calc_CentralDose(ExampleData.DeValues$CA1)

Description

Calculates the dose rate profile through the cobble based on Riedesel and Autzen (2020).

Corrects the beta dose rate in the cobble for the grain size following results of Guérin et al. (2012). Sediment beta and gamma dose rates are corrected for the water content of the sediment using the correction factors of Aitken (1985). Water content in the cobble is assumed to be 0.

Usage

calc_CobbleDoseRate(input, conversion = "Guerinetal2011")

Arguments

Details

The input table layout

Water content The water content provided by the user should be calculated according to:

$(Wet_weight - Dry_weight) / Dry_weight * 100$

Value

The function returns an RLum.Results object for which the first element is a matrix (DataIndividual) that gives the dose rate results for each slice for each decay chain individually, for both, the cobble dose rate and the sediment dose rate. The second element is also a matrix (DataComponent) that gives the total beta and gamma-dose rates for the cobble and the adjacent sediment for each slice of the cobble.

Function version

0.1.0

How to cite

Riedesel, S., Autzen, M., 2024. calc_CobbleDoseRate(): Calculate dose rate of slices in a spherical cobble. Function version 0.1.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Author(s)

Svenja Riedesel, Aberystwyth University (United Kingdom)
Martin Autzen, DTU NUTECH Center for Nuclear Technologies (Denmark) , RLum Developer Team

References

Riedesel, S., Autzen, M., 2020. Beta and gamma dose rate attenuation in rocks and sediment. Radiation Measurements 133, 106295.

See Also

convert_Concentration2DoseRate

Examples

## load example data
data("ExampleData.CobbleData", envir = environment())

## run function
calc_CobbleDoseRate(ExampleData.CobbleData)

Description

Function to calculate the common dose of a De distribution.

Usage

calc_CommonDose(data, sigmab, log = TRUE, ...)

Arguments

Details

(Un-)logged model

When log = TRUE this function calculates the weighted mean of logarithmic De values. Each of the estimates is weighted by the inverse square of its relative standard error. The weighted mean is then transformed back to the dose scale (Galbraith & Roberts 2012, p. 14).

The log transformation is not applicable if the De estimates are close to zero or negative. In this case the un-logged model can be applied instead (log = FALSE). The weighted mean is then calculated using the un-logged estimates of De and their absolute standard error (Galbraith & Roberts 2012, p. 14).

Value

Returns a terminal output. In addition an RLum.Results object is returned containing the following element:

The output should be accessed using the function get_RLum

Function version

0.1.1

How to cite

Burow, C., 2024. calc_CommonDose(): Apply the (un-)logged common age model after Galbraith et al. (1999) to a given De distribution. Function version 0.1.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

Author(s)

Christoph Burow, University of Cologne (Germany) , RLum Developer Team

References

Galbraith, R.F. & Laslett, G.M., 1993. Statistical models for mixed fission track ages. Nuclear Tracks Radiation Measurements 4, 459-470.

Galbraith, R.F., Roberts, R.G., Laslett, G.M., Yoshida, H. & Olley, J.M., 1999. Optical dating of single grains of quartz from Jinmium rock shelter, northern Australia. Part I: experimental design and statistical models. Archaeometry 41, 339-364.

Galbraith, R.F. & Roberts, R.G., 2012. Statistical aspects of equivalent dose and error calculation and display in OSL dating: An overview and some recommendations. Quaternary Geochronology 11, 1-27.

Further reading

Arnold, L.J. & Roberts, R.G., 2009. Stochastic modelling of multi-grain equivalent dose (De) distributions: Implications for OSL dating of sediment mixtures. Quaternary Geochronology 4, 204-230.

Bailey, R.M. & Arnold, L.J., 2006. Statistical modelling of single grain quartz De distributions and an assessment of procedures for estimating burial dose. Quaternary Science Reviews 25, 2475-2502.

Cunningham, A.C. & Wallinga, J., 2012. Realizing the potential of fluvial archives using robust OSL chronologies. Quaternary Geochronology 12, 98-106.

Rodnight, H., Duller, G.A.T., Wintle, A.G. & Tooth, S., 2006. Assessing the reproducibility and accuracy of optical dating of fluvial deposits. Quaternary Geochronology, 1 109-120.

Rodnight, H., 2008. How many equivalent dose values are needed to obtain a reproducible distribution?. Ancient TL 26, 3-10.

See Also

calc_CentralDose, calc_FiniteMixture, calc_FuchsLang2001, calc_MinDose

Examples

## load example data
data(ExampleData.DeValues, envir = environment())

## apply the common dose model
calc_CommonDose(ExampleData.DeValues$CA1)

Description

This function calculates the cosmic dose rate taking into account the soft- and hard-component of the cosmic ray flux and allows corrections for geomagnetic latitude, altitude above sea-level and geomagnetic field changes.

Usage

calc_CosmicDoseRate(
  depth,
  density,
  latitude,
  longitude,
  altitude,
  corr.fieldChanges = FALSE,
  est.age = NA,
  half.depth = FALSE,
  error = 10,
  ...
)

Arguments

Details

This function calculates the total cosmic dose rate considering both the soft- and hard-component of the cosmic ray flux.

Internal calculation steps

(1) Calculate total depth of all absorber in hg/cm^2 (1 hg/cm^2 = 100 g/cm^2)

$absorber = depth_1*density_1 + depth_2*density_2 + ... + depth_n*density_n$

(2) If half.depth = TRUE

$absorber = absorber/2$

(3) Calculate cosmic dose rate at sea-level and 55 deg. latitude

a) If absorber is > 167 g/cm^2 (only hard-component; Allkofer et al. 1975): apply equation given by Prescott & Hutton (1994) (c.f. Barbouti & Rastin 1983)

$D0 = C/(((absorber+d)^\alpha+a)*(absober+H))*exp(-B*absorber)$

b) If absorber is < 167 g/cm^2 (soft- and hard-component): derive D0 from Fig. 1 in Prescott & Hutton (1988).

(4) Calculate geomagnetic latitude (Prescott & Stephan 1982, Prescott & Hutton 1994)

$\lambda = arcsin(0.203*cos(latitude)*cos(longitude-291)+0.979* sin(latitude))$