Luminescence Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 292

Download
Open PDF In Browser	View PDF

Package ‘Luminescence’
April 27, 2019
Type Package
Title Comprehensive Luminescence Dating Data Analysis
Version 0.9.1.9000-2
Date 2019-04-27
Author Sebastian Kreutzer [aut, trl, cre, dtc] (),
Christoph Burow [aut, trl, dtc] (),
Michael Dietze [aut] (),
Margret C. Fuchs [aut],
Christoph Schmidt [aut] (),
Manfred Fischer [aut, trl],
Johannes Friedrich [aut] (),
Norbert Mercier [ctb] (),
Rachel K. Smedley [ctb] (),
Claire Christophe [ctb],
Antoine Zink [ctb] (),
Julie Durcan [ctb] (),
Georgina E. King [ctb, dtc] (),
Anne Philippe [ctb],
Guillaume Guerin [ctb] (),
Svenja Riedesel [ctb] (),
Martin Autzen [ctb],
Markus Fuchs [ths]
Maintainer Sebastian Kreutzer 
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.
Contact Package Developers 
License GPL-3
BugReports https://github.com/R-Lum/Luminescence/issues
Depends R (>= 3.4.0), utils, magrittr (>= 1.5)
LinkingTo Rcpp (>= 1.0.0), RcppArmadillo (>= 0.9.300.0.0)
Imports bbmle (>= 1.0.20), data.table (>= 1.12.0), DEoptim (>= 2.2-4),
httr (>= 1.4.0), matrixStats (>= 0.54.0), methods, minpack.lm
(>= 1.2), plotrix (>= 3.7), raster (>= 2.8-0), readxl (>=
1.3.0), shape (>= 1.4.3), parallel, XML (>= 3.98-1.9), zoo (>=
1.8)
1

2
Suggests RLumShiny (>= 0.2.2), RLumModel (>= 0.2.2), plotly (>=
4.9.0), rmarkdown (>= 1.12), rstudioapi (>= 0.7), rjags (>=
4-8), coda (>= 0.19-1), pander (>= 0.6.1), testthat (>= 2.0.0),
devtools (>= 2.0.0), R.rsp (>= 0.43.0)
VignetteBuilder R.rsp
URL https://CRAN.R-project.org/package=Luminescence
Encoding UTF-8
Collate 'Analyse_SAR.OSLdata.R' 'CW2pHMi.R' 'CW2pLM.R' 'CW2pLMi.R'
'CW2pPMi.R' 'Luminescence-package.R' 'PSL2Risoe.BINfileData.R'
'RcppExports.R' 'replicate_RLum.R' 'RLum-class.R'
'smooth_RLum.R' 'names_RLum.R' 'structure_RLum.R'
'length_RLum.R' 'set_RLum.R' 'get_RLum.R'
'RLum.Analysis-class.R' 'RLum.Data-class.R' 'bin_RLum.Data.R'
'RLum.Data.Curve-class.R' 'RLum.Data.Image-class.R'
'RLum.Data.Spectrum-class.R' 'RLum.Results-class.R'
'Risoe.BINfileData2RLum.Analysis.R'
'Risoe.BINfileData2RLum.Data.Curve.R' 'set_Risoe.BINfileData.R'
'get_Risoe.BINfileData.R' 'RisoeBINfileData-class.R'
'Second2Gray.R' 'addins_RLum.R' 'analyse_Al2O3C_CrossTalk.R'
'analyse_Al2O3C_ITC.R' 'analyse_Al2O3C_Measurement.R'
'analyse_FadingMeasurement.R' 'analyse_IRSAR.RF.R'
'analyse_SAR.CWOSL.R' 'analyse_SAR.TL.R' 'analyse_baSAR.R'
'analyse_pIRIRSequence.R' 'analyse_portableOSL.R' 'app_RLum.R'
'apply_CosmicRayRemoval.R' 'apply_EfficiencyCorrection.R'
'calc_AliquotSize.R' 'calc_AverageDose.R' 'calc_CentralDose.R'
'calc_CommonDose.R' 'calc_CosmicDoseRate.R' 'calc_FadingCorr.R'
'calc_FastRatio.R' 'calc_FiniteMixture.R'
'calc_FuchsLang2001.R' 'calc_HomogeneityTest.R'
'calc_Huntley2006.R' 'calc_IEU.R' 'calc_Kars2008.R'
'calc_Lamothe2003.R' 'calc_MaxDose.R' 'calc_MinDose.R'
'calc_OSLLxTxRatio.R' 'calc_SourceDoseRate.R'
'calc_Statistics.R' 'calc_TLLxTxRatio.R'
'calc_ThermalLifetime.R' 'calc_WodaFuchs2008.R' 'calc_gSGC.R'
'convert_Activity2Concentration.R' 'convert_BIN2CSV.R'
'convert_Daybreak2CSV.R' 'convert_PSL2CSV.R'
'convert_RLum2Risoe.BINfileData.R'
'convert_Wavelength2Energy.R' 'convert_XSYG2CSV.R'
'extract_IrradiationTimes.R' 'fit_CWCurve.R'
'fit_EmissionSpectra.R' 'fit_LMCurve.R' 'fit_OSLLifeTimes.R'
'fit_SurfaceExposure.R' 'fit_ThermalQuenching.R' 'get_Layout.R'
'get_Quote.R' 'get_rightAnswer.R' 'github.R'
'install_DevelopmentVersion.R' 'internal_as.latex.table.R'
'internals_RLum.R' 'merge_RLum.Analysis.R'
'merge_RLum.Data.Curve.R' 'merge_RLum.R' 'merge_RLum.Results.R'
'merge_Risoe.BINfileData.R' 'methods_DRAC.R' 'methods_RLum.R'
'model_LuminescenceSignals.R' 'plot_AbanicoPlot.R'
'plot_DRCSummary.R' 'plot_DRTResults.R' 'plot_DetPlot.R'
'plot_FilterCombinations.R' 'plot_GrowthCurve.R'
'plot_Histogram.R' 'plot_KDE.R' 'plot_NRt.R'
'plot_RLum.Analysis.R' 'plot_RLum.Data.Curve.R'
'plot_RLum.Data.Image.R' 'plot_RLum.Data.Spectrum.R'

R topics documented:

3

'plot_RLum.R' 'plot_RLum.Results.R' 'plot_RadialPlot.R'
'plot_Risoe.BINfileData.R' 'plot_ViolinPlot.R' 'read_BIN2R.R'
'read_Daybreak2R.R' 'read_PSL2R.R' 'read_RF2R.R' 'read_SPE2R.R'
'read_XSYG2R.R' 'report_RLum.R' 'scale_GammaDose.R'
'template_DRAC.R' 'tune_Data.R' 'use_DRAC.R' 'utils_DRAC.R'
'verify_SingleGrainData.R' 'write_R2BIN.R' 'write_RLum2CSV.R'
'zzz.R'
RoxygenNote 6.1.1
NeedsCompilation yes

R topics documented:
Luminescence-package . . . . . . .
analyse_Al2O3C_CrossTalk . . . .
analyse_Al2O3C_ITC . . . . . . .
analyse_Al2O3C_Measurement . .
analyse_baSAR . . . . . . . . . . .
analyse_FadingMeasurement . . . .
analyse_IRSAR.RF . . . . . . . . .
analyse_pIRIRSequence . . . . . .
analyse_portableOSL . . . . . . . .
analyse_SAR.CWOSL . . . . . . .
Analyse_SAR.OSLdata . . . . . . .
analyse_SAR.TL . . . . . . . . . .
apply_CosmicRayRemoval . . . . .
apply_EfficiencyCorrection . . . . .
app_RLum . . . . . . . . . . . . .
as . . . . . . . . . . . . . . . . . .
BaseDataSet.ConversionFactors . .
BaseDataSet.CosmicDoseRate . . .
BaseDataSet.FractionalGammaDose
bin_RLum.Data . . . . . . . . . . .
calc_AliquotSize . . . . . . . . . .
calc_AverageDose . . . . . . . . .
calc_CentralDose . . . . . . . . . .
calc_CommonDose . . . . . . . . .
calc_CosmicDoseRate . . . . . . .
calc_FadingCorr . . . . . . . . . .
calc_FastRatio . . . . . . . . . . . .
calc_FiniteMixture . . . . . . . . .
calc_FuchsLang2001 . . . . . . . .
calc_gSGC . . . . . . . . . . . . .
calc_HomogeneityTest . . . . . . .
calc_Huntley2006 . . . . . . . . . .
calc_IEU . . . . . . . . . . . . . .
calc_Kars2008 . . . . . . . . . . .
calc_Lamothe2003 . . . . . . . . .
calc_MaxDose . . . . . . . . . . .
calc_MinDose . . . . . . . . . . . .
calc_OSLLxTxRatio . . . . . . . .
calc_SourceDoseRate . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

5
7
9
12
14
21
24
31
34
35
39
42
44
46
47
48
49
50
52
53
54
56
59
61
63
67
71
73
76
78
80
81
86
88
90
92
95
100
104

R topics documented:

4
calc_Statistics . . . . . . . . . . .
calc_ThermalLifetime . . . . . . .
calc_TLLxTxRatio . . . . . . . .
calc_WodaFuchs2008 . . . . . . .
convert_Activity2Concentration .
convert_BIN2CSV . . . . . . . .
convert_Daybreak2CSV . . . . .
convert_PSL2CSV . . . . . . . .
convert_RLum2Risoe.BINfileData
convert_Wavelength2Energy . . .
convert_XSYG2CSV . . . . . . .
CW2pHMi . . . . . . . . . . . .
CW2pLM . . . . . . . . . . . . .
CW2pLMi . . . . . . . . . . . . .
CW2pPMi . . . . . . . . . . . . .
ExampleData.Al2O3C . . . . . .
ExampleData.BINfileData . . . .
ExampleData.CW_OSL_Curve . .
ExampleData.DeValues . . . . . .
ExampleData.Fading . . . . . . .
ExampleData.FittingLM . . . . .
ExampleData.LxTxData . . . . .
ExampleData.LxTxOSLData . . .
ExampleData.portableOSL . . . .
ExampleData.RLum.Analysis . .
ExampleData.RLum.Data.Image .
ExampleData.ScaleGammaDose .
ExampleData.SurfaceExposure . .
ExampleData.TR_OSL . . . . . .
ExampleData.XSYG . . . . . . .
extdata . . . . . . . . . . . . . . .
extract_IrradiationTimes . . . . .
fit_CWCurve . . . . . . . . . . .
fit_EmissionSpectra . . . . . . . .
fit_LMCurve . . . . . . . . . . .
fit_OSLLifeTimes . . . . . . . . .
fit_SurfaceExposure . . . . . . . .
fit_ThermalQuenching . . . . . .
get_Layout . . . . . . . . . . . .
get_Quote . . . . . . . . . . . . .
get_rightAnswer . . . . . . . . .
get_Risoe.BINfileData . . . . . .
get_RLum . . . . . . . . . . . . .
GitHub-API . . . . . . . . . . . .
install_DevelopmentVersion . . .
length_RLum . . . . . . . . . . .
merge_Risoe.BINfileData . . . . .
merge_RLum . . . . . . . . . . .
model_LuminescenceSignals . . .
names_RLum . . . . . . . . . . .
plot_AbanicoPlot . . . . . . . . .
plot_DetPlot . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

106
108
111
113
114
116
117
118
119
120
123
124
128
129
132
135
136
137
138
139
141
141
143
144
144
145
146
146
149
150
152
153
155
159
162
166
169
172
175
176
177
178
179
180
182
183
184
186
187
189
190
197

Luminescence-package

5

plot_DRCSummary . . . . . . . . .
plot_DRTResults . . . . . . . . . .
plot_FilterCombinations . . . . . .
plot_GrowthCurve . . . . . . . . .
plot_Histogram . . . . . . . . . . .
plot_KDE . . . . . . . . . . . . . .
plot_NRt . . . . . . . . . . . . . .
plot_RadialPlot . . . . . . . . . . .
plot_Risoe.BINfileData . . . . . . .
plot_RLum . . . . . . . . . . . . .
plot_RLum.Analysis . . . . . . . .
plot_RLum.Data.Curve . . . . . . .
plot_RLum.Data.Image . . . . . . .
plot_RLum.Data.Spectrum . . . . .
plot_RLum.Results . . . . . . . . .
plot_ViolinPlot . . . . . . . . . . .
PSL2Risoe.BINfileData . . . . . . .
read_BIN2R . . . . . . . . . . . . .
read_Daybreak2R . . . . . . . . . .
read_PSL2R . . . . . . . . . . . . .
read_RF2R . . . . . . . . . . . . .
read_SPE2R . . . . . . . . . . . . .
read_XSYG2R . . . . . . . . . . .
replicate_RLum . . . . . . . . . . .
report_RLum . . . . . . . . . . . .
Risoe.BINfileData2RLum.Analysis
RLum-class . . . . . . . . . . . . .
scale_GammaDose . . . . . . . . .
Second2Gray . . . . . . . . . . . .
set_Risoe.BINfileData . . . . . . .
set_RLum . . . . . . . . . . . . . .
smooth_RLum . . . . . . . . . . .
sTeve . . . . . . . . . . . . . . . .
structure_RLum . . . . . . . . . . .
template_DRAC . . . . . . . . . . .
tune_Data . . . . . . . . . . . . . .
use_DRAC . . . . . . . . . . . . .
verify_SingleGrainData . . . . . . .
write_R2BIN . . . . . . . . . . . .
write_RLum2CSV . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

Index

Luminescence-package

Description

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

200
203
206
209
214
216
219
222
226
229
230
232
234
235
239
241
243
244
246
248
249
250
253
256
257
260
262
263
267
269
270
272
273
274
276
278
279
281
284
286
288

Comprehensive Luminescence Dating Data Analysis

6

Luminescence-package

Details
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.
Author(s)
Full list of authors and contributors (alphabetic order)
Christoph Burow
Claire Christophe
Michael Dietze
Julie Durcan
Manfred Fischer
Margret C. Fuchs
Martin Autzen
Johannes Friedrich
Guillaume Guérin
Georgina E. King
Sebastian Kreutzer
Norbert Mercier
Svenja Riedesel
Christoph Schmidt
Rachel K. Smedley
Anne Philippe
Antoine Zink

University of Cologne, Germany*
IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne, France
GFZ Helmholtz Centre Potsdam, Germany
University of Oxford, United Kingdom
University of Bayreuth, Germany
Helmholtz-Zentrum Dresden-Rossendorf, Helmholtz-Institute Freiberg for Resource Technology, Fre
DTU NUTECH Center for Nuclear Technologies
Chair of Geomorphology, University of Bayreuth, Germany
IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne, France
University of Lausanne, Switzerland
IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne, France
IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne, France
Aberystwyth University, United Kingdom
Chair of Geomorophology, University of Bayreuth, Germany
Liverpool University, United Kingdom
Universite de Nantes and ANJA INRIA, Rennes, France
C2RMF, Palais du Louvre, Paris, France

Supervisor of the initial version in 2012
Markus Fuchs, Justus-Liebig-University Giessen, Germany
Support contact

We may further encourage the usage of our support forum. For this please visit our project website
(link below).
Bug reporting
•  or
• https://github.com/R-Lum/Luminescence/issues
Project website
• http://www.r-luminescence.org
Project source code repository
• https://github.com/R-Lum/Luminescence
Related package projects
• https://cran.r-project.org/package=RLumShiny
• http://shiny.r-luminescence.org
• https://cran.r-project.org/package=RLumModel

analyse_Al2O3C_CrossTalk

7

Package maintainer
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS- Université Bordeaux Montaigne, France,

Funding
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)
Between 2014–2019, the work of Sebastian Kreutzer as maintainer of the package was supported
by LabEx LaScArBxSK (ANR - n. ANR-10-LABX-52).
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.
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

analyse_Al2O3C_CrossTalk
Al2O3:C Reader Cross Talk Analysis

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, ...)

8

analyse_Al2O3C_CrossTalk

Arguments
object
RLum.Analysis (required): measurement input
signal_integral
numeric (optional): signal integral, used for the signal and the background. If
nothing is provided the full range is used
dose_points

numeric (with default): vector with dose points, if dose points are repeated, only
the general pattern needs to be provided. Default values follow the suggestions
made by Kreutzer et al., 2018

recordType

character (with default): input curve selection, which is passed to function get_RLum.
To deactivate the automatic selection set the argument to NULL
irradiation_time_correction
numeric or RLum.Results (optional): information on the used irradiation time
correction obained by another experiements.

method_control list (optional): optional parameters to control the calculation. See details for
further explanations
plot

logical (with default): enable/disable plot output

...

further arguments that can be passed to the plot output

Value
Function returns results numerically and graphically:
———————————–
[ NUMERICAL OUTPUT ]
———————————–
RLum.Results-object
slot: @data
Element
$data
$data_full
$fit
$col.seq

Type
data.frame
data.frame
lm
numeric

Description
summed apparent dose table
full apparent dose table
the linear model obtained from fitting
the used colour vector

slot: @info
The original function call
————————
[ PLOT OUTPUT ]
————————

• An overview of the obtained apparent dose values
Function version
0.1.2 (2018-04-27 17:34:30)

analyse_Al2O3C_ITC

9

How to cite
Kreutzer, S. (2019). analyse_Al2O3C_CrossTalk(): Al2O3:C Reader Cross Talk Analysis. Function version 0.1.2. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Université Bordeaux Montaigne (France)
R Luminescence Package 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. Geochromometria 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)

analyse_Al2O3C_ITC

Al2O3 Irradiation Time Correction Analysis

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
object

RLum.Analysis or list (required): results obtained from the measurement. Alternatively a list of ’RLum.Analysis’ objects can be provided to allow an automatic analysis.

10

analyse_Al2O3C_ITC
signal_integral
numeric (optional): signal integral, used for the signal and the background. If
nothing is provided the full range is used. Argument can be provided as list.
dose_points

numeric (with default): vector with dose points, if dose points are repeated, only
the general pattern needs to be provided. Default values follow the suggestions
made by Kreutzer et al., 2018. Argument can be provided as list.

recordType

character (with default): input curve selection, which is passed to function get_RLum.
To deactivate the automatic selection set the argument to NULL

method_control list (optional): optional parameters to control the calculation. See details for
further explanations
verbose

logical (with default): enable/disable verbose mode

plot

logical (with default): enable/disable plot output

...

further arguments that can be passed to the plot output

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:
ARGUMENT
mode
fit.method

FUNCTION
plot_GrowthCurve
plot_GrowthCurve

DESCRIPTION
as in plot_GrowthCurve; sets the mode used for fitting
as in plot_GrowthCurve; sets the function applied for fitting

Value
Function returns results numerically and graphically:
———————————–
[ NUMERICAL OUTPUT ]
———————————–
RLum.Results-object
slot: @data
Element
$data
$table
$table_mean
$fit

Type
data.frame
data.frame
data.frame
lm or nls

Description
correction value and error
table used for plotting
table used for fitting
the fitting as returned by the function plot_GrowthCurve

analyse_Al2O3C_ITC

11

slot: @info
The original function call
————————
[ PLOT OUTPUT ]
————————

• A dose response curve with the marked correction values

Function version
0.1.1 (2018-04-27 17:34:30)

How to cite
Kreutzer, S. (2019). 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. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence

Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Université Bordeaux Montaigne (France)
R Luminescence Package 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. Geochromometria 45, 56-67. doi: 10.1515/geochr-2015-0086

See Also
plot_GrowthCurve

Examples
##load data
data(ExampleData.Al2O3C, envir = environment())
##run analysis
analyse_Al2O3C_ITC(data_ITC)

12

analyse_Al2O3C_Measurement

analyse_Al2O3C_Measurement
Al2O3:C Passive Dosimeter Measurement Analysis

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
object
RLum.Analysis (required): measurement input
signal_integral
numeric (optional): signal integral, used for the signal and the background. Example: c(1:10) for the first 10 channels. If nothing is provided the full range is
used
dose_points

numeric (with default): vector with dose points, if dose points are repeated, only
the general pattern needs to be provided. Default values follow the suggestions
made by Kreutzer et al., 2018

recordType

character (with default): input curve selection, which is passed to function get_RLum.
To deactivate the automatic selection set the argument to NULL
calculate_TL_dose
logical (with default): Enables/disables experimental dose estimation based on
the TL curves. Taken is the ratio of the peak sums of each curves +/- 5 channels.
irradiation_time_correction
numeric or RLum.Results (optional): information on the used irradiation time
correction obained by another experiements. I a numeric is provided it has to
be of length two: mean, standard error
cross_talk_correction
numeric or RLum.Results (optional): information on the used irradiation time
correction obained by another experiements. If a numeric vector is provided it
has to be of length three: mean, 2.5 % quantile, 97.5 % quantile.
travel_dosimeter
numeric (optional): specify the position of the travel dosimeter (so far measured
a the same time). The dose of travel dosimeter will be subtracted from all other
values.
test_parameters
list (with default): set test parameters. Supported parameters are: TL_peak_shift
All input: numeric values, NA and NULL (s. Details)
verbose

logical (with default): enable/disable verbose mode

analyse_Al2O3C_Measurement

13

plot

logical (with default): enable/disable plot output, if object is of type list, a
numeric vector can be provided to limit the plot output to certain aliquots

...

further arguments that can be passed to the plot output, supported are norm,
main, mtext

Details
Working with a travel dosimeter
The function allows to define particular aliquots as travel dosimeters. For example: travel_dosimeter
= c(1,3,5) sets aliquots 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 fallback 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.
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 delievered 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
Element
$data
$data_table
test_parameters
data_TDcorrected

Type
data.frame
data.frame
data.frame
data.frame

Description
the estimated equivalent dose
full dose and signal table
results with test paramaters
travel dosimeter corrected results (only if TD was provided)

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

14

analyse_baSAR
————————
[ PLOT OUTPUT ]
————————
• OSL and TL curves, combined on two plots.

Function version
0.2.4 (2019-04-18 14:06:24)
How to cite
Kreutzer, S. (2019). analyse_Al2O3C_Measurement(): Al2O3:C Passive Dosimeter Measurement
Analysis. Function version 0.2.4. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt,
C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data
Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France)
R Luminescence Package 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. Geochromometria 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_Measurement(data_CrossTalk)

analyse_baSAR

Bayesian models (baSAR) applied on luminescence data

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 Combes 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 adaption of this
approach for the R environment and (II) an extension and a technical refinement of the published
code.

analyse_baSAR

15

Usage
analyse_baSAR(object, XLS_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.single = FALSE, verbose = TRUE, ...)
Arguments
object

Risoe.BINfileData, RLum.Results, RLum.Analysis character or list (required):
input object used for the Bayesian analysis. If a character is provided the function assumes a file connection and tries to import a BIN-file using the provided
path. If a list is provided the list can only contain either Risoe.BINfileData
objects or characters providing a file connection. Mixing of both types is not
allowed. If an RLum.Results is provided the function directly starts with the
Bayesian Analysis (see details)

XLS_file

character (optional): XLS_file with data for the analysis. This file must contain
3 columns: the name of the file, the disc position and the grain position (the last
being 0 for multi-grain measurements).
Alternatively a data.frame of similar structure can be provided.

aliquot_range

numeric (optional): allows to limit the range of the aliquots used for the analysis.
This argument has only an effect if the argument XLS_file is used or the input
is the previous output (i.e. is RLum.Results). In this case the new selection will
add the aliquots to the removed aliquots table.

source_doserate
numeric (required): source dose rate of beta-source used for the measuremnt
and its uncertainty in Gy/s, e.g., source_doserate = c(0.12,0.04). Paramater
can be provided as list, for the case that more than one BIN-file is provided,
e.g., source_doserate = list(c(0.04,0.004),c(0.05,0.004)).
signal.integral
vector (required): vector with the limits for the signal integral used for the calculation, e.g., signal.integral = c(1:5). Ignored if object is an RLum.Results
object. The parameter can be provided as list, see source_doserate.
signal.integral.Tx
vector (optional): vector with the limits for the signal integral for the Tx curve. I
f nothing is provided the value from signal.integral is used and it is ignored
if object is an RLum.Results object. The parameter can be provided as list,
see source_doserate.
background.integral
vector (required): vector with the bounds for the background integral. Ignored
if object is an RLum.Results object. The parameter can be provided as list,
see source_doserate.
background.integral.Tx
vector (optional): vector with the limits for the background integral for the Tx
curve. If nothing is provided the value from background.integral is used.
Ignored if object is an RLum.Results object. The parameter can be provided
as list, see source_doserate.

16

analyse_baSAR
irradiation_times
numeric (optional): if set this vector replaces all irradiation times for one aliquot
and one cycle (Lx and Tx curves) and recycles it for all others cycles and
aliquots. Plesae note that if this argument is used, for every(!) single curve
in the dataset an irradiation time needs to be set.
sigmab

numeric (with default): option to set a manual value for the overdispersion (for
LnTx and TnTx), used for the Lx/Tx error calculation. The value should be provided as absolute squared count values, cf. calc_OSLLxTxRatio. The parameter
can be provided as list, see source_doserate.

sig0

numeric (with default): allow adding an extra component of error to the final
Lx/Tx error value (e.g., instrumental errror, see details is calc_OSLLxTxRatio).
The parameter can be provided as list, see source_doserate.

distribution

character (with default): type of distribution that is used during Bayesian calculations for determining the Central dose and overdispersion values. Allowed
inputs are "cauchy", "normal" and "log_normal".

baSAR_model

character (optional): option to provide an own modified or new model for the
Bayesian calculation (see details). If an own model is provided the argument
distribution is ignored and set to 'user_defined'

n.MCMC

integer (with default): number of iterations for the Markov chain Monte Carlo
(MCMC) simulations

fit.method

character (with default): fit method used for fitting the growth curve using the
function plot_GrowthCurve. Here supported methods: EXP, EXP+LIN and LIN
fit.force_through_origin
logical (with default): force fitting through origin
fit.includingRepeatedRegPoints
logical (with default): includes the recycling point (assumed to be measured
during the last cycle)
method_control list (optional): named list of control parameters that can be directly passed to the
Bayesian analysis, e.g., method_control = list(n.chains = 4). See details
for further information
digits
integer (with default): round output to the number of given digits
distribution_plot
character (with default): sets the final distribution plot that shows equivalent
doses obtained using the frequentist approach and sets in the central dose as
comparison obtained using baSAR. Allowed input is 'abanico' or 'kde'. If
set to NULL nothing is plotted.
plot

logical (with default): enables or disables plot output

plot_reduced

logical (with default): enables or disables the advanced plot output

plot.single

logical (with default): enables or disables single plots or plots arranged by
analyse_baSAR

verbose

logical (with default): enables or disables verbose mode

...

parameters that can be passed to the function calc_OSLLxTxRatio (almost full
support), readxl::read_excel (full support), read_BIN2R (n.records, position,
duplicated.rm), see details.

Details
Internally the function consists of two parts: (I) The Bayesian core for the Bayesian calculations
and applying the hierchical model and (II) a data pre-processing part. The Bayesian core can be

analyse_baSAR

17

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 the systematic error contribution is 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

SE(central.dose.f inal) =

p

X

SE(source.doserate)

SE(central.dose)2 + systematic.error2

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 filename and/or a path is provided. In both cases
it will become the data that can be used for the analysis.
[XLS_file = NULL]
If no XLS file (or data frame with the same format) is provided the functions 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
[XLS_file != NULL]
If an XLS-file is provided or a data.frame providing similar information the pre-processing steps
consists of the following steps:
1. Calculate Lx/Tx values using the function calc_OSLLxTxRatio
2. Calculate De values using the function plot_GrowthCurve
Means, the XLS 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 the Bayesian analysis. This option is very powerful as it allows to change parameters for the

18

analyse_baSAR
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:

Parameter
lower_centralD
upper_centralD
n.chains
inits
thin
variable.names

Type
numeric
numeric
integer
list
numeric
character

Descritpion
sets the lower bound for the expected De range. Change it only if you know what you are
sets the upper bound for the expected De range. Change it only if you know what you are
sets number of parallel chains for the model (default = 3) (cf. rjags::jags.model)
option to set initialisation values (cf. rjags::jags.model)
thinning interval for monitoring the Bayesian process (cf. rjags::jags.model)
set the variables to be monitored during the MCMC run, default: ’central_D’, ’sigma_D

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 funtion 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.
Supported argument
threshold
sheet

Corresponding function
verify_SingleGrainData
readxl::read_excel

Default
30
1

**Short description **
change rejection threshold for curve
select XLS-sheet for import

analyse_baSAR

19

col_names
col_types
skip
n.records
duplicated.rm
pattern
position
background.count.distribution
fit.weights
fit.bounds
NumberIterations.MC
output.plot
output.plotExtended

readxl::read_excel
readxl::read_excel
readxl::read_excel
read_BIN2R
read_BIN2R
read_BIN2R
read_BIN2R
calc_OSLLxTxRatio
plot_GrowthCurve
plot_GrowthCurve
plot_GrowthCurve
plot_GrowthCurve
plot_GrowthCurve

TRUE
NULL
0
NULL
TRUE
TRUE
NULL
"non-poisson"
TRUE
TRUE
100
TRUE
TRUE

first row in XLS-file is header
limit import to specific columns
number of rows to be skipped durin
limit records during BIN-file impor
remove duplicated records in the BI
select BIN-file by name pattern
limit import to a specific position
set assumed count distribution
enables / disables fit weights
enables / disables fit bounds
number of MC runs for error calcul
enables / disables dose response cu
enables / disables extended dose res

Value
Function returns results numerically and graphically:
———————————–
[ NUMERICAL OUTPUT ]
———————————–
RLum.Results-object
slot: @data
Element
$summary
$mcmc
$models
$input_object
$removed_aliquots

Type
data.frame
mcmc
character
data.frame
data.frame

Description
statistical summary, including the central dose
coda::mcmc.list object including raw output
implemented models used in the baSAR-model core
summarising table (same format as the XLS-file) including, e.g., Lx/Tx values
table with removed aliquots (e.g., NaN, or Inf Lx/Tx values). If nothing was remov

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.

20

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

Function version
0.1.33 (2018-06-06 14:45:55)
How to cite
Mercier, N., Kreutzer, S. (2019). 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. (2019). Luminescence: Comprehensive Luminescence Dating Data
Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
If you provide more than one BIN-file, it is strongly recommanded 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, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
The underlying Bayesian model based on a contribution by Combes et al., 2015.
R Luminescence Package Team
References
Combes, B., Philippe, A., Lanos, P., Mercier, N., Tribolo, C., Guerin, G., Guibert, P., Lahaye,
C., 2015. A Bayesian central equivalent dose model for optically stimulated luminescence dating.
Quaternary Geochronology 28, 62-70. 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)00253X
Plummer, M., 2017. JAGS Version 4.3.0 user manual. https://sourceforge.net/projects/mcmcjags/files/Manuals/4.x/jags_user_manual.pdf/download
See Also
read_BIN2R, calc_OSLLxTxRatio, plot_GrowthCurve, readxl::read_excel, verify_SingleGrainData,
rjags::jags.model, rjags::coda.samples, boxplot.default

analyse_FadingMeasurement
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)
##XLS_file template
##copy and paste this the code below in the terminal
##you can further use the function write.csv() to export the example
XLS_file  36.5 deg.):
y = −0.0001 ∗ x + 0.2347
J (non-linear part, λ < 34 deg.):
y = 5 ∗ 10− 6 ∗ x3 − 5 ∗ 10− 5 ∗ x2 + 0.0026 ∗ x + 0.5177
J (linear part, λ > 34 deg.):
y = 0.0005 ∗ x + 0.7388
H (non-linear part, λ < 36 deg.):
y = −3 ∗ 10− 6 ∗ x3 − 5 ∗ 10− 5 ∗ x2 − 0.0031 ∗ x + 4.398
H (linear part, λ > 36 deg.):
y = 0.0002 ∗ x + 4.0914

52

BaseDataSet.FractionalGammaDose

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)

BaseDataSet.FractionalGammaDose
Base data set of fractional gamma-dose values

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:
Aitken1985:

Fractional gamma-dose values from table H.1

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")

bin_RLum.Data

bin_RLum.Data

53

Channel binning - method dispatchter

Description
Function calls the object-specific bin functions for RLum.Data S4 class objects.
Usage
bin_RLum.Data(object, ...)
Arguments
object

RLum.Data (required): S4 object of class RLum.Data

...

further arguments passed to the specifc class method

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 (2019-01-24 22:59:09)
How to cite
Kreutzer, S. (2019). bin_RLum.Data(): Channel binning - method dispatchter. Function version
0.2.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J.
(2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version
0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
Currently only RLum.Data objects of class RLum.Data.Curve and RLum.Data.Spectrum are supported!
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5050, CNRS - Université Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
RLum.Data.Curve, RLum.Data.Spectrum

54

calc_AliquotSize

Examples
##load example data
data(ExampleData.CW_OSL_Curve, envir = environment())
##create RLum.Data.Curve object from this example
curve  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)α + 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).

calc_CosmicDoseRate

65

(4) Calculate geomagnetic latitude (Prescott & Stephan 1982, Prescott & Hutton 1994)
λ = arcsin(0.203 ∗ cos(latitude) ∗ cos(longitude − 291) + 0.979 ∗ sin(latitude))
(5) Apply correction for geomagnetic latitude and altitude above sea-level. Values for F, J and H
were read from Fig. 3 shown in Prescott & Stephan (1982) and fitted with 3-degree polynomials for
lambda < 35 degree and a linear fit for lambda > 35 degree.
Dc = D0 ∗ (F + J ∗ exp((altitude/1000)/H))
(6) Optional: Apply correction for geomagnetic field changes in the last 0-80 ka (Prescott & Hutton
1994). Correction and altitude factors are given in Table 1 and Fig. 1 in Prescott & Hutton (1994).
Values for altitude factor were fitted with a 2-degree polynomial. The altitude factor is operated on
the decimal part of the correction factor.
Dc0 = Dc ∗ correctionF actor
Usage of depth and density
(1) If only one value for depth and density is provided, the cosmic dose rate is calculated for exactly
one sample and one absorber as overburden (i.e. depth*density).
(2) In some cases it might be useful to calculate the cosmic dose rate for a sample that is overlain
by more than one absorber, e.g. in a profile with soil layers of different thickness and a distinct
difference in density. This can be calculated by providing a matching number of values for depth
and density (e.g. depth = c(1,2),density = c(1.7,2.4))
(3) Another possibility is to calculate the cosmic dose rate for more than one sample of the same
profile. This is done by providing more than one values for depth and only one for density.
For example, depth = c(1,2,3) and density = 1.7 will calculate the cosmic dose rate for three
samples in 1, 2 and 3 m depth in a sediment of density 1.7 g/cm^3.
Value
Returns a terminal output. In addition an RLum.Results-object is returned containing the following
element:
summary

data.frame summary of all relevant calculation results.

args

list used arguments

call

call the function call

The output should be accessed using the function get_RLum
Function version
0.5.2 (2019-03-04 18:26:22)
How to cite
Burow, C. (2019). calc_CosmicDoseRate(): Calculate the cosmic dose rate. Function version 0.5.2.
In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019).
Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6.
https://CRAN.R-project.org/package=Luminescence

66

calc_CosmicDoseRate

Note
Despite its universal use the equation to calculate the cosmic dose rate provided by Prescott &
Hutton (1994) is falsely stated to be valid from the surface to 10^4 hg/cm^2 of standard rock. The
original expression by Barbouti & Rastin (1983) only considers the muon flux (i.e. hard-component)
and is by their own definition only valid for depths between 10-10^4 hg/cm^2.
Thus, for near-surface samples (i.e. for depths < 167 g/cm^2) the equation of Prescott & Hutton
(1994) underestimates the total cosmic dose rate, as it neglects the influence of the soft-component
of the cosmic ray flux. For samples at zero depth and at sea-level the underestimation can be as
large as ~0.1 Gy/ka. In a previous article, Prescott & Hutton (1988) give another approximation of
Barbouti & Rastins equation in the form of
D = 0.21 ∗ exp(−0.070 ∗ absorber + 0.0005 ∗ absorber2 )
which is valid for depths between 150-5000 g/cm^2. For shallower depths (< 150 g/cm^2) they
provided a graph (Fig. 1) from which the dose rate can be read.
As a result, this function employs the equation of Prescott & Hutton (1994) only for depths > 167
g/cm^2, i.e. only for the hard-component of the cosmic ray flux. Cosmic dose rate values for depths
< 167 g/cm^2 were obtained from the "AGE" programm (Gruen 2009) and fitted with a 6-degree
polynomial curve (and hence reproduces the graph shown in Prescott & Hutton 1988). However,
these values assume an average overburden density of 2 g/cm^3.
It is currently not possible to obtain more precise cosmic dose rate values for near-surface samples
as there is no equation known to the author of this function at the time of writing.
Author(s)
Christoph Burow, University of Cologne (Germany)
R Luminescence Package Team
References
Allkofer, O.C., Carstensen, K., Dau, W.D., Jokisch, H., 1975. Letter to the editor. The absolute
cosmic ray flux at sea level. Journal of Physics G: Nuclear and Particle Physics 1, L51-L52.
Barbouti, A.I., Rastin, B.C., 1983. A study of the absolute intensity of muons at sea level and under
various thicknesses of absorber. Journal of Physics G: Nuclear and Particle Physics 9, 1577-1595.
Crookes, J.N., Rastin, B.C., 1972. An investigation of the absolute intensity of muons at sea-level.
Nuclear Physics B 39, 493-508.
Gruen, R., 2009. The "AGE" program for the calculation of luminescence age estimates. Ancient
TL 27, 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, 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, 497-500.
Prescott, J.R., Stephan, L.G., 1982. The contribution of cosmic radiation to the environmental dose
for thermoluminescence dating. Latitude, altitude and depth dependences. PACT 6, 17-25.
See Also
BaseDataSet.CosmicDoseRate

calc_FadingCorr

67

Examples
##(1) calculate cosmic dose rate (one absorber)
calc_CosmicDoseRate(depth = 2.78, density = 1.7,
latitude = 38.06451, longitude = 1.49646,
altitude = 364, error = 10)
##(2a) calculate cosmic dose rate (two absorber)
calc_CosmicDoseRate(depth = c(5.0, 2.78), density = c(2.65, 1.7),
latitude = 38.06451, longitude = 1.49646,
altitude = 364, error = 10)
##(2b) calculate cosmic dose rate (two absorber) and
##correct for geomagnetic field changes
calc_CosmicDoseRate(depth = c(5.0, 2.78), density = c(2.65, 1.7),
latitude = 12.04332, longitude = 4.43243,
altitude = 364, corr.fieldChanges = TRUE,
est.age = 67, error = 15)
##(3) calculate cosmic dose rate and export results to .csv file
#calculate cosmic dose rate and save to variable
results<- calc_CosmicDoseRate(depth = 2.78, density = 1.7,
latitude = 38.06451, longitude = 1.49646,
altitude = 364, error = 10)
# the results can be accessed by
get_RLum(results, "summary")
#export results to .csv file - uncomment for usage
#write.csv(results, file = "c:/users/public/results.csv")
##(4) calculate cosmic dose rate for 6 samples from the same profile
##
and save to .csv file
#calculate cosmic dose rate and save to variable
results<- calc_CosmicDoseRate(depth = c(0.1, 0.5 , 2.1, 2.7, 4.2, 6.3),
density = 1.7, latitude = 38.06451,
longitude = 1.49646, altitude = 364,
error = 10)
#export results to .csv file - uncomment for usage
#write.csv(results, file = "c:/users/public/results_profile.csv")

calc_FadingCorr

Apply a fading correction according to Huntley & Lamothe (2001) for
a given g-value and a given tc

Description
This function solves the equation used for correcting the fading affected age including the error for
a given g-value according to Huntley & Lamothe (2001).

68

calc_FadingCorr

Usage
calc_FadingCorr(age.faded, g_value, tc = NULL, tc.g_value = tc,
n.MC = 10000, seed = NULL, interval = c(0.01, 500),
txtProgressBar = TRUE, verbose = TRUE)
Arguments
age.faded

numeric vector (required): uncorrected age with error in ka (see example)

g_value

vector (required): g-value and error obtained from separate fading measurements (see example). Alternatively an RLum.Results object can be provided
produced by the function analyse_FadingMeasurement, in this case tc is set automatically

tc

numeric (required): time in seconds between irradiation and the prompt measurement (cf. Huntley & Lamothe 2001). Argument will be ignored if g_value
was an RLum.Results object

tc.g_value

numeric (with default): the time in seconds between irradiation and the prompt
measurement used for estimating the g-value. If the g-value was normalised to,
e.g., 2 days, this time in seconds (i.e., 172800) should be given here. If nothing
is provided the time is set to tc, which is usual case for g-values obtained using
the SAR method and g-values that had been not normalised to 2 days.

n.MC

integer (with default): number of Monte Carlo simulation runs for error estimation. If n.MC = 'auto' is used the function tries to find a ’stable’ error for the
age. Note: This may take a while!

seed

integer (optional): sets the seed for the random number generator in R using
set.seed

interval

numeric (with default): a vector containing the end-points (age interval) of the
interval to be searched for the root in ’ka’. This argument is passed to the function stats::uniroot used for solving the equation.

txtProgressBar logical (with default): enables or disables txtProgressBar
verbose

logical (with default): enables or disables terminal output

Details
As the g-value sligthly depends on the time between irradiation and the prompt measurement, this
is tc, always a tc value needs to be provided. If the g-value was normalised to a distinct time or
evaluated with a different tc value (e.g., external irradiation), also the tc value for the g-value needs
to be provided (argument tc.g_value and then the g-value is recalcualted to tc of the measurement
used for estimating the age applying the following equation:
κtc = κtc.g /(1 − κtc.g ∗ log(tc/tc.g))
where
κtc.g = g/100/log(10)
with log the natural logarithm.
The error of the fading-corrected age is determined using a Monte Carlo simulation approach. Solving of the equation is realised using uniroot. Large values for n.MC will significantly increase the

calc_FadingCorr

69

computation time.
n.MC = ’auto’
The error estimation based on a stochastic process, i.e. for a small number of MC runs the calculated
error varies considerably every time the function is called, even with the same input values. The
argument option n.MC = 'auto' tries to find a stable value for the standard error, i.e. the standard
deviation of values calculated during the MC runs (age.corr.MC), within a given precision (2
digits) by increasing the number of MC runs stepwise and calculating the corresponding error.
If the determined error does not differ from the 9 values calculated previously within a precision of
(here) 3 digits the calculation is stopped as it is assumed that the error is stable. Please note that (a)
the duration depends on the input values as well as on the provided computation ressources and it
may take a while, (b) the length (size) of the output vector age.corr.MC, where all the single values
produced during the MC runs are stored, equals the number of MC runs (here termed observations).
To avoid an endless loop the calculation is stopped if the number of observations exceeds 10^7. This
limitation can be overwritten by setting the number of MC runs manually, e.g. n.MC = 10000001.
Note: For this case the function is not checking whether the calculated error is stable.
seed
This option allows to recreate previously calculated results by setting the seed for the R random
number generator (see set.seed for details). This option should not be mixed up with the option
n.MC = ’auto’. The results may appear similar, but they are not comparable!
FAQ
Q: Which tc value is expected?
A: tc is the time in seconds between irradiation and the prompt measurement applied during your
De measurement. However, this tc might differ from the tc used for estimating the g-value. In the
case of an SAR measurement tc should be similar, however, if it differs, you have to provide this tc
value (the one used for estimating the g-value) using the argument tc.g_value.

Value
Returns an S4 object of type RLum.Results.
Slot: @data
Object
age.corr
age.corr.MC

Type
data.frame
numeric

Comment
Corrected age
MC simulation results with all possible ages from that simulation

Slot: @info
Object
info

Type
character

Comment
the original function call

70

calc_FadingCorr

Function version
0.4.2 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). calc_FadingCorr(): Apply a fading correction according to Huntley & Lamothe
(2001) for a given g-value and a given tc. Function version 0.4.2. In: Kreutzer, S., Burow, C.,
Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence
Note
Special thanks to Sebastien Huot for his support and clarification via e-mail.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
References
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.
See Also
RLum.Results, get_RLum, uniroot
Examples
##run the examples given in the appendix of Huntley and Lamothe, 2001
##(1) faded age: 100 a
results <- calc_FadingCorr(
age.faded = c(0.1,0),
g_value = c(5.0, 1.0),
tc = 2592000,
tc.g_value = 172800,
n.MC = 100)
##(2) faded age: 1 ka
results <- calc_FadingCorr(
age.faded = c(1,0),
g_value = c(5.0, 1.0),
tc = 2592000,
tc.g_value = 172800,
n.MC = 100)
##(3) faded age: 10.0 ka
results <- calc_FadingCorr(
age.faded = c(10,0),
g_value = c(5.0, 1.0),
tc = 2592000,

calc_FastRatio

71

tc.g_value = 172800,
n.MC = 100)
##access the last output
get_RLum(results)

calc_FastRatio

Calculate the Fast Ratio for CW-OSL curves

Description
Function to calculate the fast ratio of quartz CW-OSL single grain or single aliquot curves after
Durcan & Duller (2011).
Usage
calc_FastRatio(object, stimulation.power = 30.6, wavelength = 470,
sigmaF = 2.6e-17, sigmaM = 4.28e-18, Ch_L1 = 1, Ch_L2 = NULL,
Ch_L3 = NULL, x = 1, x2 = 0.1, dead.channels = c(0, 0),
fitCW.sigma = FALSE, fitCW.curve = FALSE, plot = TRUE, ...)
Arguments
object

RLum.Analysis, RLum.Data.Curve or data.frame (required): x, y data of measured values (time and counts).
stimulation.power
numeric (with default): Stimulation power in mW/cm^2
wavelength

numeric (with default): Stimulation wavelength in nm

sigmaF

numeric (with default): Photoionisation cross-section (cm^2) of the fast component. Default value after Durcan & Duller (2011).

sigmaM

numeric (with default): Photoionisation cross-section (cm^2) of the medium
component. Default value after Durcan & Duller (2011).

Ch_L1

numeric (with default): An integer specifying the channel for L1.

Ch_L2

numeric (optional): An integer specifying the channel for L2.

Ch_L3

numeric (optional): A vector of length 2 with integer values specifying the start
and end channels for L3 (e.g., c(40,50)).

x

numeric (with default): % of signal remaining from the fast component. Used
to define the location of L2 and L3 (start).

x2

numeric (with default): % of signal remaining from the medium component.
Used to define the location of L3 (end).

dead.channels

numeric (with default): Vector of length 2 in the form of c(x,y). Channels that
do not contain OSL data, i.e. at the start or end of measurement.

fitCW.sigma

logical (optional): fit CW-OSL curve using fit_CWCurve to calculate sigmaF
and sigmaM (experimental).

fitCW.curve

logical (optional): fit CW-OSL curve using fit_CWCurve and derive the counts
of L2 and L3 from the fitted OSL curve (experimental).

plot

logical (with default): plot output (TRUE/FALSE)

...

available options: verbose (logical). Further arguments passed to fit_CWCurve.

72

calc_FastRatio

Details
This function follows the equations of Durcan & Duller (2011). The energy required to reduce
the fast and medium quartz OSL components to x and x2 % respectively using eq. 3 to determine
channels L2 and L3 (start and end). The fast ratio is then calculated from: (L1 − L3)/(L2 − L3).
Value
Returns a plot (optional) and an S4 object of type RLum.Results. The slot data contains a list with
the following elements:
summary

data.frame summary of all relevant results

data

the original input data

fit

RLum.Results object if either fitCW.sigma or fitCW.curve is TRUE

args

list of used arguments

call

[call] the function call

Function version
0.1.1 (2018-03-09 09:04:33)
How to cite
King, G.E., Durcan, J., Burow, C. (2019). calc_FastRatio(): Calculate the Fast Ratio for CW-OSL
curves. Function version 0.1.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt,
C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data
Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Georgina E. King, University of Bern (Switzerland)
Julie A. Durcan, University of Oxford (United Kingdom)
Christoph Burow, University of Cologne (Germany)
R Luminescence Package Team
References
Durcan, J.A. & Duller, G.A.T., 2011. The fast ratio: A rapid measure for testing the dominance of
the fast component in the initial OSL signal from quartz. Radiation Measurements 46, 1065-1072.
Madsen, A.T., Duller, G.A.T., Donnelly, J.P., Roberts, H.M. & Wintle, A.G., 2009. A chronology of hurricane landfalls at Little Sippewissett Marsh, Massachusetts, USA, using optical dating.
Geomorphology 109, 36-45.
Further reading
Steffen, D., Preusser, F. & Schlunegger, 2009. OSL quartz age underestimation due to unstable
signal components. Quaternary Geochronology 4, 353-362.
See Also
fit_CWCurve, get_RLum, RLum.Analysis, RLum.Results, RLum.Data.Curve

calc_FiniteMixture

73

Examples
# load example CW-OSL curve
data("ExampleData.CW_OSL_Curve")
# calculate the fast ratio w/o further adjustments
res <- calc_FastRatio(ExampleData.CW_OSL_Curve)
# show the summary table
get_RLum(res)

calc_FiniteMixture

Apply the finite mixture model (FMM) after Galbraith (2005) to a
given De distribution

Description
This function fits a k-component mixture to a De distribution with differing known standard errors.
Parameters (doses and mixing proportions) are estimated by maximum likelihood assuming that the
log dose estimates are from a mixture of normal distributions.
Usage
calc_FiniteMixture(data, sigmab, n.components, grain.probability = FALSE,
dose.scale, pdf.weight = TRUE, pdf.sigma = "sigmab",
pdf.colors = "gray", pdf.scale, plot.proportions = TRUE,
plot = TRUE, ...)
Arguments
data

RLum.Results or data.frame (required): for data.frame: two columns with De
(data[,1]) and De error (values[,2])

sigmab

numeric (required): spread in De values given as a fraction (e.g. 0.2). This
value represents the expected overdispersion in the data should the sample be
well-bleached (Cunningham & Wallinga 2012, p. 100).

n.components

numeric (required): number of components to be fitted. If a vector is provided
(e.g. c(2:8)) the finite mixtures for 2, 3 ... 8 components are calculated and a
plot and a statistical evaluation of the model performance (BIC score and maximum log-likelihood) is provided.
grain.probability
logical (with default): prints the estimated probabilities of which component
each grain is in
dose.scale

numeric: manually set the scaling of the y-axis of the first plot with a vector in
the form of c(min,max)

pdf.weight

logical (with default): weight the probability density functions by the components proportion (applies only when a vector is provided for n.components)

pdf.sigma

character (with default): if "sigmab" the components normal distributions are
plotted with a common standard deviation (i.e. sigmab) as assumed by the FFM.
Alternatively, "se" takes the standard error of each component for the sigma
parameter of the normal distribution

74

calc_FiniteMixture
pdf.colors

character (with default): color coding of the components in the the plot. Possible
options are "gray", "colors" and "none"

pdf.scale

numeric: manually set the max density value for proper scaling of the x-axis of
the first plot
plot.proportions
logical (with default): plot barplot showing the proportions of components
plot

logical (with default): plot output

...

further arguments to pass. See details for their usage.

Details
This model uses the maximum likelihood and Bayesian Information Criterion (BIC) approaches.
Indications of overfitting are:
• increasing BIC
• repeated dose estimates
• covariance matrix not positive definite
• covariance matrix produces NaNs
• convergence problems
Plot
If a vector (c(k.min:k.max)) is provided for n.components a plot is generated showing the the k
components equivalent doses as normal distributions. By default pdf.weight is set to FALSE, so
that the area under each normal distribution is always 1. If TRUE, the probability density functions
are weighted by the components proportion for each iteration of k components, so the sum of areas
of each component equals 1. While the density values are on the same scale when no weights are
used, the y-axis are individually scaled if the probability density are weighted by the components
proportion.
The standard deviation (sigma) of the normal distributions is by default determined by a common
sigmab (see pdf.sigma). For pdf.sigma = "se" the standard error of each component is taken
instead.
The stacked barplot shows the proportion of each component (in per cent) calculated by the FFM.
The last plot shows the achieved BIC scores and maximum log-likelihood estimates for each iteration of k.
Value
Returns a plot (optional) and terminal output. In addition an RLum.Results object is returned containing the following elements:
.$summary

data.frame summary of all relevant model results.

.$data

data.frame original input data

.$args

list used arguments

.$call

call the function call

.$mle

covariance matrices of the log likelhoods

.$BIC

BIC score

.$llik
maximum log likelihood
.$grain.probability
probabilities of a grain belonging to a component

calc_FiniteMixture

75

.$components

matrix estimates of the de, de error and proportion for each component

.$single.comp

data.frame single componente FFM estimate

If a vector for n.components is provided (e.g. c(2:8)), mle and grain.probability are lists
containing matrices of the results for each iteration of the model.
The output should be accessed using the function get_RLum
Function version
0.4.1 (2019-01-17 17:56:46)
How to cite
Burow, C. (2019). calc_FiniteMixture(): Apply the finite mixture model (FMM) after Galbraith
(2005) to a given De distribution. Function version 0.4.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence
Author(s)
Christoph Burow, University of Cologne (Germany)
Based on a rewritten S script of Rex Galbraith, 2006.
R Luminescence Package Team
References
Galbraith, R.F. & Green, P.F., 1990. Estimating the component ages in a finite mixture. Nuclear
Tracks and Radiation Measurements 17, 197-206.
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., 2012. Statistical aspects of equivalent dose and error calculation
and display in OSL dating: An overview and some recommendations. Quaternary Geochronology
11, 1-27.
Roberts, R.G., Galbraith, R.F., Yoshida, H., Laslett, G.M. & Olley, J.M., 2000. Distinguishing dose
populations in sediment mixtures: a test of single-grain optical dating procedures using mixtures of
laboratory-dosed quartz. Radiation Measurements 32, 459-465.
Galbraith, R.F., 2005. Statistics for Fission Track Analysis, Chapman & Hall/CRC, Boca Raton.
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.
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.

76

calc_FuchsLang2001

See Also
calc_CentralDose, calc_CommonDose, calc_FuchsLang2001, calc_MinDose
Examples
## load example data
data(ExampleData.DeValues, envir = environment())
## (1) apply the finite mixture model
## NOTE: the data set is not suitable for the finite mixture model,
## which is why a very small sigmab is necessary
calc_FiniteMixture(ExampleData.DeValues$CA1,
sigmab = 0.2, n.components = 2,
grain.probability = TRUE)
## (2) repeat the finite mixture model for 2, 3 and 4 maximum number of fitted
## components and save results
## NOTE: The following example is computationally intensive. Please un-comment
## the following lines to make the example work.
FMM<- calc_FiniteMixture(ExampleData.DeValues$CA1,
sigmab = 0.2, n.components = c(2:4),
pdf.weight = TRUE, dose.scale = c(0, 100))
## show structure of the results
FMM
## show the results on equivalent dose, standard error and proportion of
## fitted components
get_RLum(object = FMM, data.object = "components")

calc_FuchsLang2001

Apply the model after Fuchs & Lang (2001) to a given De distribution.

Description
This function applies the method according to Fuchs & Lang (2001) for heterogeneously bleached
samples with a given coefficient of variation threshold.
Usage
calc_FuchsLang2001(data, cvThreshold = 5, startDeValue = 1,
plot = TRUE, ...)
Arguments
data

RLum.Results or data.frame (required): for data.frame: two columns with De
(data[,1]) and De error (values[,2])

cvThreshold

numeric (with default): coefficient of variation in percent, as threshold for the
method, e.g. cvThreshold = 3. See details .

startDeValue

numeric (with default): number of the first aliquot that is used for the calculations

calc_FuchsLang2001

77

plot

logical (with default): plot output TRUE/FALSE

...

further arguments and graphical parameters passed to plot

Details
Used values
If the coefficient of variation (c[v]) of the first two values is larger than the threshold c[v_threshold],
the first value is skipped. Use the startDeValue argument to define a start value for calculation
(e.g. 2nd or 3rd value).
Basic steps of the approach
1. Estimate natural relative variation of the sample using a dose recovery test
2. Sort the input values ascendingly
3. Calculate a running mean, starting with the lowermost two values and add values iteratively.
4. Stop if the calculated c[v] exceeds the specified cvThreshold
Value
Returns a plot (optional) and terminal output. In addition an RLum.Results object is returned containing the following elements:
summary

data.frame summary of all relevant model results.

data

data.frame original input data

args

list used arguments

call

call the function call

usedDeValues

data.frame containing the used values for the calculation

Function version
0.4.1 (2018-01-21 17:22:38)
How to cite
Kreutzer, S., Burow, C. (2019). calc_FuchsLang2001(): Apply the model after Fuchs & Lang
(2001) to a given De distribution.. Function version 0.4.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence
Note
Please consider the requirements and the constraints of this method (see Fuchs & Lang, 2001)
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
Christoph Burow, University of Cologne (Germany)
R Luminescence Package Team

78

calc_gSGC

References
Fuchs, M. & Lang, A., 2001. OSL dating of coarse-grain fluvial quartz using single-aliqout protocols on sediments from NE Peloponnese, Greece. In: Quaternary Science Reviews 20, 783-787.
Fuchs, M. & Wagner, G.A., 2003. Recognition of insufficient bleaching by small aliquots of quartz
for reconstructing soil erosion in Greece. Quaternary Science Reviews 22, 1161-1167.
See Also
plot, calc_MinDose, calc_FiniteMixture, calc_CentralDose, calc_CommonDose, RLum.Results
Examples
## load example data
data(ExampleData.DeValues, envir = environment())
## calculate De according to Fuchs & Lang (2001)
temp<- calc_FuchsLang2001(ExampleData.DeValues$BT998, cvThreshold = 5)

calc_gSGC

Calculate De value based on the gSGC by Li et al., 2015

Description
Function returns De value and De value error using the global standardised growth curve (gSGC)
assumption proposed by Li et al., 2015 for OSL dating of sedimentary quartz
Usage
calc_gSGC(data, gSGC.type = "0-250", gSGC.parameters, n.MC = 100,
verbose = TRUE, plot = TRUE, ...)
Arguments
data

gSGC.type
gSGC.parameters

n.MC
verbose
plot
...

data.frame (required): input data of providing the following columns: ’LnTn’,
’LnTn.error’, Lr1Tr1’, ’Lr1Tr1.error’, ’Dr1’ Note: column names are not required. The function expect the input data in the given order
character (with default): define the function parameters that should be used for
the iteration procedure: Li et al., 2015 (Table 2) presented function parameters
for two dose ranges: "0-450" and "0-250"

list (optional): option to provide own function parameters used for fitting as
named list. Nomenclature follows Li et al., 2015, i.e. list(A,A.error,D0,D0.error,c,c.error,Y0
range requires a vector for the range the function is considered as valid, e.g.
range = c(0,250)
Using this option overwrites the default parameter list of the gSGC, meaning the
argument gSGC.type will be without effect
integer (with default): number of Monte Carlo simulation runs for error estimation, see details.
logical: enable or disable terminal output
logical: enable or disable graphical feedback as plot
parameters will be passed to the plot output

calc_gSGC

79

Details
The error of the De value is determined using a Monte Carlo simulation approach. Solving of the
equation is realised using uniroot. Large values for n.MC will significantly increase the computation
time.
Value
Returns an S4 object of type RLum.Results.
@data
$ De.value (data.frame)
.. $ De
.. $ De.error
.. $ Eta
$ De.MC (list) contains the matricies from the error estimation.
$ uniroot (list) contains the uniroot outputs of the De estimations
@info
‘$ call“ (call) the original function call
Function version
0.1.1 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). calc_gSGC(): Calculate De value based on the gSGC by Li et al., 2015.
Function version 0.1.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montagine (France)
R Luminescence Package Team
References
Li, B., Roberts, R.G., Jacobs, Z., Li, S.-H., 2015. Potential of establishing a ’global standardised
growth curve’ (gSGC) for optical dating of quartz from sediments. Quaternary Geochronology 27,
94-104. doi:10.1016/j.quageo.2015.02.011
See Also
RLum.Results, get_RLum, uniroot
Examples
results <- calc_gSGC(data = data.frame(
LnTn = 2.361, LnTn.error = 0.087,
Lr1Tr1 = 2.744, Lr1Tr1.error = 0.091,
Dr1 = 34.4))

80

calc_HomogeneityTest
get_RLum(results, data.object = "De")

calc_HomogeneityTest

Apply a simple homogeneity test after Galbraith (2003)

Description
A simple homogeneity test for De estimates
Usage
calc_HomogeneityTest(data, log = TRUE, ...)
Arguments
data

RLum.Results or data.frame (required): for data.frame: two columns with De
(data[,1]) and De error (values[,2])

log

logical (with default): perform the homogeneity test with (un-)logged data

...

further arguments (for internal compatibility only).

Details
For details see Galbraith (2003).
Value
Returns a terminal output. In addition an RLum.Results-object is returned containing the following
elements:
summary

data.frame summary of all relevant model results.

data

data.frame original input data

args

list used arguments

call

call the function call

The output should be accessed using the function get_RLum
Function version
0.3.0 (2018-01-21 17:22:38)
How to cite
Burow, C., Kreutzer, S. (2019). calc_HomogeneityTest(): Apply a simple homogeneity test after
Galbraith (2003). Function version 0.3.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C.,
Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence

calc_Huntley2006

81

Author(s)
Christoph Burow, University of Cologne (Germany), Sebastian Kreutzer, IRAMAT-CRP2A, Université Bordeaux Montaigne (France)
R Luminescence Package Team
References
Galbraith, R.F., 2003. A simple homogeneity test for estimates of dose obtained using OSL. Ancient
TL 21, 75-77.
See Also
pchisq
Examples
## load example data
data(ExampleData.DeValues, envir = environment())
## apply the homogeneity test
calc_HomogeneityTest(ExampleData.DeValues$BT998)
## using the data presented by Galbraith (2003)
df  max(t)
NOTE: The number of values for t’ < min(t) depends on the stimulation rate parameter delta. To
avoid the production of too many artificial data at the raising tail of the determined pHM curve, it
is recommended to use the automatic estimation routine for delta, i.e. provide no value for delta.
Value
The function returns the same data type as the input data type with the transformed curve values.
RLum.Data.Curve
$CW2pHMi.x.t
$CW2pHMi.method

: transformed time values
: used method for the production of the new data points

data.frame
$x
$y.t
$x.t
$method

:
:
:
:

time
transformed count values
transformed time values
used method for the production of the new data points

Function version
0.2.2 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). CW2pHMi(): Transform a CW-OSL curve into a pHM-OSL curve via interpolation under hyperbolic modulation conditions. Function version 0.2.2. In: Kreutzer, S.,

126

CW2pHMi
Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence:
Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence

Note
According to Bos & Wallinga (2012), the number of extrapolated points should be limited to avoid
artificial intensity data. If delta is provided manually and more than two points are extrapolated, a
warning message is returned.
The function approx may produce some Inf and NaN data. The function tries to manually interpolate these values by calculating the mean using the adjacent channels. If two invalid values are
succeeding, the values are removed and no further interpolation is attempted. In every case a warning message is shown.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
Based on comments and suggestions from:
Adrie J.J. Bos, Delft University of Technology, The Netherlands
R Luminescence Package Team
References
Bos, A.J.J. & Wallinga, J., 2012. How to visualize quartz OSL signal components. Radiation Measurements, 47, 752-758.
Further Reading
Bulur, E., 1996. An Alternative Technique For Optically Stimulated Luminescence (OSL) Experiment. Radiation Measurements, 26, 701-709.
Bulur, E., 2000. A simple transformation for converting CW-OSL curves to LM-OSL curves. Radiation Measurements, 32, 141-145.
See Also
CW2pLM, CW2pLMi, CW2pPMi, fit_LMCurve, lm, RLum.Data.Curve
Examples
##(1) - simple transformation
##load CW-OSL curve data
data(ExampleData.CW_OSL_Curve, envir = environment())
##transform values
values.transformed<-CW2pHMi(ExampleData.CW_OSL_Curve)
##plot
plot(values.transformed$x, values.transformed$y.t, log = "x")
##(2) - load CW-OSL curve from BIN-file and plot transformed values
##load BINfile
#BINfileData<-readBIN2R("[path to BIN-file]")

CW2pHMi
data(ExampleData.BINfileData, envir = environment())
##grep first CW-OSL curve from ALQ 1
curve.ID<-CWOSL.SAR.Data@METADATA[CWOSL.SAR.Data@METADATA[,"LTYPE"]=="OSL" &
CWOSL.SAR.Data@METADATA[,"POSITION"]==1
,"ID"]
curve.HIGH<-CWOSL.SAR.Data@METADATA[CWOSL.SAR.Data@METADATA[,"ID"]==curve.ID[1]
,"HIGH"]
curve.NPOINTS<-CWOSL.SAR.Data@METADATA[CWOSL.SAR.Data@METADATA[,"ID"]==curve.ID[1]
,"NPOINTS"]
##combine curve to data set
curve<-data.frame(x = seq(curve.HIGH/curve.NPOINTS,curve.HIGH,
by = curve.HIGH/curve.NPOINTS),
y=unlist(CWOSL.SAR.Data@DATA[curve.ID[1]]))
##transform values
curve.transformed <- CW2pHMi(curve)
##plot curve
plot(curve.transformed$x, curve.transformed$y.t, log = "x")
##(3) - produce Fig. 4 from Bos & Wallinga (2012)
##load data
data(ExampleData.CW_OSL_Curve, envir = environment())
values <- CW_Curve.BosWallinga2012
##open plot area
plot(NA, NA,
xlim=c(0.001,10),
ylim=c(0,8000),
ylab="pseudo OSL (cts/0.01 s)",
xlab="t [s]",
log="x",
main="Fig. 4 - Bos & Wallinga (2012)")
values.t<-CW2pLMi(values, P=1/20)
lines(values[1:length(values.t[,1]),1],CW2pLMi(values, P=1/20)[,2],
col="red" ,lwd=1.3)
text(0.03,4500,"LM", col="red" ,cex=.8)
values.t<-CW2pHMi(values, delta=40)
lines(values[1:length(values.t[,1]),1],CW2pHMi(values, delta=40)[,2],
col="black", lwd=1.3)
text(0.005,3000,"HM", cex=.8)
values.t<-CW2pPMi(values, P=1/10)
lines(values[1:length(values.t[,1]),1],CW2pPMi(values, P=1/10)[,2],
col="blue", lwd=1.3)
text(0.5,6500,"PM", col="blue" ,cex=.8)

127

128

CW2pLM

CW2pLM

Transform a CW-OSL curve into a pLM-OSL curve

Description
Transforms a conventionally measured continuous-wave (CW) curve into a pseudo linearly modulated (pLM) curve using the equations given in Bulur (2000).
Usage
CW2pLM(values)
Arguments
values

RLum.Data.Curve or data.frame (required): RLum.Data.Curve data object.
Alternatively, a data.frame of the measured curve data of type stimulation time
(t) (values[,1]) and measured counts (cts) (values[,2]) can be provided.

Details
According to Bulur (2000) the curve data are transformed by introducing two new parameters P
(stimulation period) and u (transformed time):
P = 2 ∗ max(t)
p
u = (2 ∗ t ∗ P )
The new count values are then calculated by
ctsN EW = cts(u/P )
and the returned data.frame is produced by: data.frame(u,ctsNEW)
The output of the function can be further used for LM-OSL fitting.
Value
The function returns the same data type as the input data type with the transformed curve values
(data.frame or RLum.Data.Curve).
Function version
0.4.1 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). CW2pLM(): Transform a CW-OSL curve into a pLM-OSL curve. Function version 0.4.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence

CW2pLMi

129

Note
The transformation is recommended for curves recorded with a channel resolution of at least 0.05
s/channel.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
References
Bulur, E., 2000. A simple transformation for converting CW-OSL curves to LM-OSL curves. Radiation Measurements, 32, 141-145.
Further Reading
Bulur, E., 1996. An Alternative Technique For Optically Stimulated Luminescence (OSL) Experiment. Radiation Measurements, 26, 701-709.
See Also
CW2pHMi, CW2pLMi, CW2pPMi, fit_LMCurve, lm, RLum.Data.Curve
Examples
##read curve from CWOSL.SAR.Data transform curve and plot values
data(ExampleData.BINfileData, envir = environment())
##read id for the 1st OSL curve
id.OSL <- CWOSL.SAR.Data@METADATA[CWOSL.SAR.Data@METADATA[,"LTYPE"] == "OSL","ID"]
##produce x and y (time and count data for the data set)
x<-seq(CWOSL.SAR.Data@METADATA[id.OSL[1],"HIGH"]/CWOSL.SAR.Data@METADATA[id.OSL[1],"NPOINTS"],
CWOSL.SAR.Data@METADATA[id.OSL[1],"HIGH"],
by = CWOSL.SAR.Data@METADATA[id.OSL[1],"HIGH"]/CWOSL.SAR.Data@METADATA[id.OSL[1],"NPOINTS"])
y <- unlist(CWOSL.SAR.Data@DATA[id.OSL[1]])
values <- data.frame(x,y)
##transform values
values.transformed <- CW2pLM(values)
##plot
plot(values.transformed)

CW2pLMi

Transform a CW-OSL curve into a pLM-OSL curve via interpolation
under linear modulation conditions

Description
Transforms a conventionally measured continuous-wave (CW) OSL-curve into a pseudo linearly
modulated (pLM) curve under linear modulation conditions using the interpolation procedure described by Bos & Wallinga (2012).

130

CW2pLMi

Usage
CW2pLMi(values, P)
Arguments
values

RLum.Data.Curve or data.frame (required): RLum.Data.Curve or data.frame
with measured curve data of type stimulation time (t) (values[,1]) and measured counts (cts) (values[,2])

P

vector (optional): stimulation time in seconds. If no value is given the optimal
value is estimated automatically (see details). Greater values of P produce more
points in the rising tail of the curve.

Details
The complete procedure of the transformation is given in Bos & Wallinga (2012). The input
data.frame consists of two columns: time (t) and count values (CW(t))
Nomenclature
• P = stimulation time (s)
• 1/P = stimulation rate (1/s)
Internal transformation steps
(1) log(CW-OSL) values
(2) Calculate t’ which is the transformed time:
t0 = 1/2 ∗ 1/P ∗ t2
(3) Interpolate CW(t’), i.e. use the log(CW(t)) to obtain the count values for the transformed time
(t’). Values beyond min(t) and max(t) produce NA values.
(4) Select all values for t’ < min(t), i.e. values beyond the time resolution of t. Select the first two
values of the transformed data set which contain no NA values and use these values for a linear fit
using lm.
(5) Extrapolate values for t’ < min(t) based on the previously obtained fit parameters.
(6) Transform values using
pLM (t) = t/P ∗ CW (t0 )
(7) Combine values and truncate all values for t’ > max(t)
NOTE: The number of values for t’ < min(t) depends on the stimulation period (P) and therefore
on the stimulation rate 1/P. To avoid the production of too many artificial data at the raising tail of
the determined pLM curves it is recommended to use the automatic estimation routine for P, i.e.
provide no own value for P.
Value
The function returns the same data type as the input data type with the transformed curve values.
RLum.Data.Curve
$CW2pLMi.x.t
$CW2pLMi.method

: transformed time values
: used method for the production of the new data points

CW2pLMi

131

Function version
0.3.1 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). CW2pLMi(): Transform a CW-OSL curve into a pLM-OSL curve via interpolation under linear modulation conditions. Function version 0.3.1. In: Kreutzer, S., Burow, C.,
Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence
Note
According to Bos & Wallinga (2012) the number of extrapolated points should be limited to avoid
artificial intensity data. If P is provided manually and more than two points are extrapolated, a
warning message is returned.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne
Based on comments and suggestions from:
Adrie J.J. Bos, Delft University of Technology, The Netherlands
R Luminescence Package Team
References
Bos, A.J.J. & Wallinga, J., 2012. How to visualize quartz OSL signal components. Radiation
Measurements, 47, 752-758.
Further Reading
Bulur, E., 1996. An Alternative Technique For Optically Stimulated Luminescence (OSL) Experiment. Radiation Measurements, 26, 701-709.
Bulur, E., 2000. A simple transformation for converting CW-OSL curves to LM-OSL curves. Radiation Measurements, 32, 141-145.
See Also
CW2pLM, CW2pHMi, CW2pPMi, fit_LMCurve, RLum.Data.Curve
Examples
##(1)
##load CW-OSL curve data
data(ExampleData.CW_OSL_Curve, envir = environment())
##transform values
values.transformed <- CW2pLMi(ExampleData.CW_OSL_Curve)
##plot
plot(values.transformed$x, values.transformed$y.t, log = "x")
##(2) - produce Fig. 4 from Bos & Wallinga (2012)
##load data

132

CW2pPMi
data(ExampleData.CW_OSL_Curve, envir = environment())
values <- CW_Curve.BosWallinga2012
##open plot area
plot(NA, NA,
xlim = c(0.001,10),
ylim = c(0,8000),
ylab = "pseudo OSL (cts/0.01 s)",
xlab = "t [s]",
log = "x",
main = "Fig. 4 - Bos & Wallinga (2012)")
values.t <- CW2pLMi(values, P = 1/20)
lines(values[1:length(values.t[,1]),1],CW2pLMi(values, P = 1/20)[,2],
col = "red", lwd = 1.3)
text(0.03,4500,"LM", col = "red", cex = .8)
values.t <- CW2pHMi(values, delta = 40)
lines(values[1:length(values.t[,1]),1],CW2pHMi(values, delta = 40)[,2],
col = "black", lwd = 1.3)
text(0.005,3000,"HM", cex =.8)
values.t <- CW2pPMi(values, P = 1/10)
lines(values[1:length(values.t[,1]),1], CW2pPMi(values, P = 1/10)[,2],
col = "blue", lwd = 1.3)
text(0.5,6500,"PM", col = "blue", cex = .8)

CW2pPMi

Transform a CW-OSL curve into a pPM-OSL curve via interpolation
under parabolic modulation conditions

Description
Transforms a conventionally measured continuous-wave (CW) OSL-curve into a pseudo parabolic
modulated (pPM) curve under parabolic modulation conditions using the interpolation procedure
described by Bos & Wallinga (2012).
Usage
CW2pPMi(values, P)
Arguments
values

RLum.Data.Curve or data.frame (required): RLum.Data.Curve or data.frame
with measured curve data of type stimulation time (t) (values[,1]) and measured counts (cts) (values[,2])

P

vector (optional): stimulation period in seconds. If no value is given, the optimal
value is estimated automatically (see details). Greater values of P produce more
points in the rising tail of the curve.

CW2pPMi

133

Details
The complete procedure of the transformation is given in Bos & Wallinga (2012). The input
data.frame consists of two columns: time (t) and count values (CW(t))
Nomenclature
• P = stimulation time (s)
• 1/P = stimulation rate (1/s)
Internal transformation steps
(1) log(CW-OSL) values
(2) Calculate t’ which is the transformed time:
t0 = (1/3) ∗ (1/P 2 )t3
(3) Interpolate CW(t’), i.e. use the log(CW(t)) to obtain the count values for the transformed time
(t’). Values beyond min(t) and max(t) produce NA values.
(4) Select all values for t’ < min(t), i.e. values beyond the time resolution of t. Select the first two
values of the transformed data set which contain no NA values and use these values for a linear fit
using lm.
(5) Extrapolate values for t’ < min(t) based on the previously obtained fit parameters. The extrapolation is limited to two values. Other values at the beginning of the transformed curve are set to
0.
(6) Transform values using
pLM (t) = t2 /P 2 ∗ CW (t0 )
(7) Combine all values and truncate all values for t’ > max(t)
NOTE: The number of values for t’ < min(t) depends on the stimulation period P. To avoid the
production of too many artificial data at the raising tail of the determined pPM curve, it is recommended to use the automatic estimation routine for P, i.e. provide no value for P.
Value
The function returns the same data type as the input data type with the transformed curve values.
RLum.Data.Curve
$CW2pPMi.x.t
$CW2pPMi.method

: transformed time values
: used method for the production of the new data points

data.frame
$x
$y.t
$x.t
$method

:
:
:
:

time
transformed count values
transformed time values
used method for the production of the new data points

Function version
0.2.1 (2018-01-21 17:22:38)

134

CW2pPMi

How to cite
Kreutzer, S. (2019). CW2pPMi(): Transform a CW-OSL curve into a pPM-OSL curve via interpolation under parabolic modulation conditions. Function version 0.2.1. In: Kreutzer, S., Burow, C.,
Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence
Note
According to Bos & Wallinga (2012), the number of extrapolated points should be limited to avoid
artificial intensity data. If P is provided manually, not more than two points are extrapolated.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
Based on comments and suggestions from:
Adrie J.J. Bos, Delft University of Technology, The Netherlands
R Luminescence Package Team
References
Bos, A.J.J. & Wallinga, J., 2012. How to visualize quartz OSL signal components. Radiation
Measurements, 47, 752-758.
Further Reading
Bulur, E., 1996. An Alternative Technique For Optically Stimulated Luminescence (OSL) Experiment. Radiation Measurements, 26, 701-709.
Bulur, E., 2000. A simple transformation for converting CW-OSL curves to LM-OSL curves. Radiation Measurements, 32, 141-145.
See Also
CW2pLM, CW2pLMi, CW2pHMi, fit_LMCurve, RLum.Data.Curve
Examples

##(1)
##load CW-OSL curve data
data(ExampleData.CW_OSL_Curve, envir = environment())
##transform values
values.transformed <- CW2pPMi(ExampleData.CW_OSL_Curve)
##plot
plot(values.transformed$x,values.transformed$y.t, log = "x")
##(2) - produce Fig. 4 from Bos & Wallinga (2012)
##load data
data(ExampleData.CW_OSL_Curve, envir = environment())
values <- CW_Curve.BosWallinga2012

ExampleData.Al2O3C

135

##open plot area
plot(NA, NA,
xlim = c(0.001,10),
ylim = c(0,8000),
ylab = "pseudo OSL (cts/0.01 s)",
xlab = "t [s]",
log = "x",
main = "Fig. 4 - Bos & Wallinga (2012)")
values.t <- CW2pLMi(values, P = 1/20)
lines(values[1:length(values.t[,1]),1],CW2pLMi(values, P = 1/20)[,2],
col = "red",lwd = 1.3)
text(0.03,4500,"LM", col = "red", cex = .8)
values.t <- CW2pHMi(values, delta = 40)
lines(values[1:length(values.t[,1]),1], CW2pHMi(values, delta = 40)[,2],
col = "black", lwd = 1.3)
text(0.005,3000,"HM", cex = .8)
values.t <- CW2pPMi(values, P = 1/10)
lines(values[1:length(values.t[,1]),1], CW2pPMi(values, P = 1/10)[,2],
col = "blue", lwd = 1.3)
text(0.5,6500,"PM", col = "blue", cex = .8)

ExampleData.Al2O3C

Example Al2O3:C Measurement Data

Description
Measurement data obtained from measuring Al2O3:C chips at the IRAMAT-CRP2A, Université
Bordeaux Montainge in 2017 on a Freiberg Instruments lexsyg SMART reader. The example data
used in particular to allow test of the functions developed in framework of the work by Kreutzer et
al., 2018.
Format
Two datasets comprising RLum.Analysis data imported using the function read_XSYG2R
data_ITC: Measurement data to determine the irradiation time correction, the data can be
analysed with the function analyse_Al2O3C_ITC
data_CrossTalk: Measurement data obtained while estimating the irradiation cross-talk of
the reader used for the experiments. The data can be analysed either with the function analyse_Al2O3C_CrossTalk or analyse_Al2O3C_Measurement
Note
From both datasets unneeded curves have been removed and the number of aliquots have been reduced to a required minimum to keep the file size small, but still being able to run the corresponding
functions.
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/geochr20150086

136

ExampleData.BINfileData

See Also
analyse_Al2O3C_ITC, analyse_Al2O3C_CrossTalk, analyse_Al2O3C_Measurement
Examples
##(1) curves
data(ExampleData.Al2O3C, envir = environment())
plot_RLum(data_ITC[1:2])

ExampleData.BINfileData
Example data from a SAR OSL and SAR TL measurement for the package Luminescence

Description
Example data from a SAR OSL and TL measurement for package Luminescence directly extracted
from a Risoe BIN-file and provided in an object of type Risoe.BINfileData
Format
CWOSL.SAR.Data: SAR OSL measurement data
TL.SAR.Data: SAR TL measurement data
Each class object contains two slots: (a) METADATA is a data.frame with all metadata stored in the
BIN file of the measurements and (b) DATA contains a list of vectors of the measured data (usually
count values).
Version
0.1
Note
Please note that this example data cannot be exported to a BIN-file using the function writeR2BIN
as it was generated and implemented in the package long time ago. In the meantime the BIN-file
format changed.
Source
CWOSL.SAR.Data
Lab:
Lab-Code:
Location:
Material:
Reference:

Luminescence Laboratory Bayreuth
BT607
Saxony/Germany
Middle grain quartz measured on aluminum cups on a Risoe TL/OSL DA-15 reader
unpublished

TL.SAR.Data

ExampleData.CW_OSL_Curve
Lab:
Lab-Code:
Location:
Material:
Setup:
Reference:
Remarks:

137

Luminescence Laboratory of Cologne
LP1_5
Spain
Flint
Risoe TL/OSL DA-20 reader (Filter: Semrock Brightline, HC475/50, N2, unpolished steel discs)
unpublished
dataset limited to one position

References
CWOSL.SAR.Data: unpublished data
TL.SAR.Data: unpublished data
Examples
## show first 5 elements of the METADATA and DATA elements in the terminal
data(ExampleData.BINfileData, envir = environment())
CWOSL.SAR.Data@METADATA[1:5,]
CWOSL.SAR.Data@DATA[1:5]

ExampleData.CW_OSL_Curve
Example CW-OSL curve data for the package Luminescence

Description
data.frame containing CW-OSL curve data (time, counts)
Format
Data frame with 1000 observations on the following 2 variables:
list("x") a numeric vector, time
list("y") a numeric vector, counts
Source
ExampleData.CW_OSL_Curve
Lab:
Lab-Code:
Location:
Material:
Reference:

Luminescence Laboratory Bayreuth
BT607
Saxony/Germany
Middle grain quartz measured on aluminum cups on a Risoe TL/OSL DA-15 reader.
unpublished data

CW_Curve.BosWallinga2012
Lab:
Lab-Code:

Netherlands Centre for Luminescence Dating (NCL)
NCL-2108077

138

ExampleData.DeValues
Location:
Material:
Reference:

Guadalentin Basin, Spain
Coarse grain quartz
Bos & Wallinga (2012) and Baartman et al. (2011)

References
Baartman, J.E.M., Veldkamp, A., Schoorl, J.M., Wallinga, J., Cammeraat, L.H., 2011. Unravelling Late Pleistocene and Holocene landscape dynamics: The Upper Guadalentin Basin, SE Spain.
Geomorphology, 125, 172-185.
Bos, A.J.J. & Wallinga, J., 2012. How to visualize quartz OSL signal components. Radiation
Measurements, 47, 752-758.
Examples
data(ExampleData.CW_OSL_Curve, envir = environment())
plot(ExampleData.CW_OSL_Curve)

ExampleData.DeValues

Example De data sets for the package Luminescence

Description
Equivalent dose (De) values measured for a fine grain quartz sample from a loess section in Rottewitz (Saxony/Germany) and for a coarse grain quartz sample from a fluvial deposit in the rock
shelter of Cueva Anton (Murcia/Spain).
Format
A list with two elements, each containing a two column data.frame:
$BT998: De and De error values for a fine grain quartz sample from a loess section in Rottewitz.
$CA1: Single grain De and De error values for a coarse grain quartz sample from a fluvial
deposit in the rock shelter of Cueva Anton
References
BT998
Unpublished data
CA1
Burow, C., Kehl, M., Hilgers, A., Weniger, G.-C., Angelucci, D., Villaverde, V., Zapata, J. and
Zilhao, J. (2015). Luminescence dating of fluvial deposits in the rock shelter of Cueva Anton,
Spain. Geochronometria 52, 107-125.
BT998
Lab:
Lab-Code:
Location:
Material:
Units:
Dose Rate:
Measurement Date:

Luminescence Laboratory Bayreuth
BT998
Rottewitz (Saxony/Germany)
Fine grain quartz measured on aluminum discs on a Risoe TL/OSL DA-15 reader
Values are given in seconds
Dose rate of the beta-source at measurement ca. 0.0438 Gy/s +/- 0.0019 Gy/s
2012-01-27

ExampleData.Fading

139

CA1
Lab:
Lab-Code:
Location:
Material:
Units:
Measurement Date:

Cologne Luminescence Laboratory (CLL)
C-L2941
Cueva Anton (Murcia/Spain)
Coarse grain quartz (200-250 microns) measured on single grain discs on a Risoe TL/OSL DA-20 re
Values are given in Gray
2012

Examples
##(1) plot values as histogram
data(ExampleData.DeValues, envir = environment())
plot_Histogram(ExampleData.DeValues$BT998, xlab = "De [s]")
##(2) plot values as histogram (with second to gray conversion)
data(ExampleData.DeValues, envir = environment())
De.values <- Second2Gray(ExampleData.DeValues$BT998,
dose.rate = c(0.0438, 0.0019))
plot_Histogram(De.values, xlab = "De [Gy]")

ExampleData.Fading

Example data for feldspar fading measurements

Description
Example data set for fading measurements of the IR50, IR100, IR150 and IR225 feldspar signals
of sample UNIL/NB123. It further contains regular equivalent dose measurement data of the same
sample, which can be used to apply a fading correction to.
Format

A list with two elements, each containing a further list of data.frames containing the data on the
fading and equivalent dose measurements:
$fading.data: A named list of data.frames, each having three named columns (LxTx,LxTx.error,timeSinceIrr
..$IR50: Fading data of the IR50 signal.
..$IR100: Fading data of the IR100 signal.
..$IR150: Fading data of the IR150 signal.
..$IR225: Fading data of the IR225 signal.
$equivalentDose.data: A named of data.frames, each having three named columns (dose,LxTx,LxTx.error).
..$IR50: Equivalent dose measurement data of the IR50 signal.
..$IR100: Equivalent dose measurement data of the IR100 signal.
..$IR150: Equivalent dose measurement data of the IR150 signal.
..$IR225: Equivalent dose measurement data of the IR225 signal.

140

ExampleData.Fading

Source
These data were kindly provided by Georgina E. King. Detailed information on the sample UNIL/NB123
can be found in the reference given below. The raw data can be found in the accompanying supplementary information.
References
King, G.E., Herman, F., Lambert, R., Valla, P.G., Guralnik, B., 2016. Multi-OSL-thermochronometry
of feldspar. Quaternary Geochronology 33, 76-87. doi:10.1016/j.quageo.2016.01.004
Details
Lab:
Lab-Code:
Location:
Material:
Units:
Lab Dose Rate:
Environmental Dose Rate:

University of Lausanne
UNIL/NB123
Namche Barwa (eastern Himalaya)
Coarse grained (180-212 microns) potassium feldspar
Values are given in seconds
Dose rate of the beta-source at measurement ca. 0.1335 +/- 0.004 Gy/s
7.00 +/- 0.92 Gy/ka (includes internal dose rate)

Examples
## Load example data
data("ExampleData.Fading", envir = environment())
## Get fading measurement data of the IR50 signal
IR50_fading <- ExampleData.Fading$fading.data$IR50
head(IR50_fading)
## Determine g-value and rho' for the IR50 signal
IR50_fading.res <- analyse_FadingMeasurement(IR50_fading)
## Show g-value and rho' results
gval <- get_RLum(IR50_fading.res)
rhop <- get_RLum(IR50_fading.res, "rho_prime")
gval
rhop
## Get LxTx values of the IR50 DE measurement
IR50_De.LxTx <- ExampleData.Fading$equivalentDose.data$IR50
## Calculate the De of the IR50 signal
IR50_De <- plot_GrowthCurve(IR50_De.LxTx,
mode = "interpolation",
fit.method = "EXP")
## Extract the calculated De and its error
IR50_De.res <- get_RLum(IR50_De)
De <- c(IR50_De.res$De, IR50_De.res$De.Error)
## Apply fading correction (age conversion greatly simplified)
IR50_Age <- De / 7.00
IR50_Age.corr <- calc_FadingCorr(IR50_Age, g_value = IR50_fading.res)

ExampleData.LxTxData

141

ExampleData.FittingLM Example data for fit_LMCurve() in the package Luminescence

Description
Lineraly modulated (LM) measurement data from a quartz sample from Norway including background measurement. Measurements carried out in the luminescence laboratory at the University
of Bayreuth.
Format
Two objects (data.frames) with two columns (time and counts).
Source
Lab:
Lab-Code:
Location:
Material:

Luminescence Laboratory Bayreuth
BT900
Norway
Beach deposit, coarse grain quartz measured on aluminum discs on a Risoe TL/OSL DA-15 reader

References
Fuchs, M., Kreutzer, S., Fischer, M., Sauer, D., Soerensen, R., 2012. OSL and IRSL dating of
raised beach sand deposits along the southeastern coast of Norway. Quaternary Geochronology, 10,
195-200.
Examples
##show LM data
data(ExampleData.FittingLM, envir = environment())
plot(values.curve,log="x")

ExampleData.LxTxData

Example Lx/Tx data from CW-OSL SAR measurement

Description
LxTx data from a SAR measurement for the package Luminescence.
Format
A data.frame with 4 columns (Dose, LxTx, LxTx.Error, TnTx).

142
Source

ExampleData.LxTxData

ExampleData.LxTxOSLData
Lab:
Lab-Code:
Location:
Material:

Luminescence Laboratory Bayreuth
BT607
Ostrau (Saxony-Anhalt/Germany)
Middle grain (38-63 µm) quartz measured on a Risoe TL/OSL DA-15 reader.

References
unpublished data
Examples
## plot Lx/Tx data vs dose [s]
data(ExampleData.LxTxData, envir = environment())
plot(LxTxData$Dose,LxTxData$LxTx)

ExampleData.LxTxOSLData
Example Lx and Tx curve data from an artificial OSL measurement

Description
Lx and Tx data of continous wave (CW-) OSL signal curves.
Format
Two data.frames containing time and count values.
Source
Arbitrary OSL measurement.
References
unpublished data
Examples
##load data
data(ExampleData.LxTxOSLData, envir = environment())
##plot data
plot(Lx.data)
plot(Tx.data)

143

144

ExampleData.RLum.Analysis

ExampleData.portableOSL
Example portable OSL curve data for the package Luminescence

Description
A list of RLum.Analysis objects, each containing the same number of RLum.Data.Curve objects
representing individual OSL, IRSL and dark count measurements of a sample.
Source
ExampleData.portableOSL
Lab:
Lab-Code:
Location:
Material:
Reference:

Cologne Luminescence Laboratory

Nievenheim/Germany
Fine grain quartz
unpublished data

Examples
data(ExampleData.portableOSL, envir = environment())
plot_RLum(ExampleData.portableOSL)

ExampleData.RLum.Analysis
Example data as RLum.Analysis objects

Description
Collection of different RLum.Analysis objects for protocol analysis.
Format
IRSAR.RF.Data: IRSAR.RF.Data on coarse grain feldspar
Each object contains data needed for the given protocol analysis.
Version
0.1
Source
IRSAR.RF.Data
These data were kindly provided by Tobias Lauer and Matthias Krbetschek.
Lab:

Luminescence Laboratory TU Bergakademie Freiberg

ExampleData.RLum.Data.Image
Lab-Code:
Location:
Material:
Reference:

145

ZEU/SA1
Zeuchfeld (Zeuchfeld Sandur; Saxony-Anhalt/Germany)
K-feldspar (130-200 µm)
Kreutzer et al. (2014)

References
IRSAR.RF.Data
Kreutzer, S., Lauer, T., Meszner, S., Krbetschek, M.R., Faust, D., Fuchs, M., 2014. Chronology of
the Quaternary profile Zeuchfeld in Saxony-Anhalt / Germany - a preliminary luminescence dating
study. Zeitschrift fuer Geomorphologie 58, 5-26. doi: 10.1127/0372-8854/2012/S-00112
Examples
##load data
data(ExampleData.RLum.Analysis, envir = environment())
##plot data
plot_RLum(IRSAR.RF.Data)

ExampleData.RLum.Data.Image
Example data as RLum.Data.Image objects

Description
Measurement of Princton Instruments camera imported with the function read_SPE2R to R to produce an RLum.Data.Image object.
Format
Object of class RLum.Data.Image
Version
0.1
Source
ExampleData.RLum.Data.Image
These data were kindly provided by Regina DeWitt.
Lab.:
Lab-Code:
Location:
Material:
Reference:

Department of Physics, East-Carolina University, NC, USA
-

146

ExampleData.SurfaceExposure
Image data is a measurement of fluorescent ceiling lights with a cooled Princeton Instruments (TM)
camera fitted on Risoe DA-20 TL/OSL reader.

Examples
##load data
data(ExampleData.RLum.Data.Image, envir = environment())
##plot data
plot_RLum(ExampleData.RLum.Data.Image)

ExampleData.ScaleGammaDose
Example data for scale_GammaDose()

Description
An example data set for the function scale_GammaDose() containing layer specific information to
scale the gamma dose rate considering variations in soil radioactivity.
Format
A data.frame. Please see ?scale_GammaDose() for a detailed description of its structure.
Version
0.1
Examples
## Load data
data("ExampleData.ScaleGammaDose")

ExampleData.SurfaceExposure
Example OSL surface exposure dating data

Description
A set of synthetic OSL surface exposure dating data to demonstrate the fit_SurfaceExposure functionality. See examples to reproduce the data interactively.

ExampleData.SurfaceExposure

147

Format
A list with 4 elements:
Element
$sample_1
$sample_2
$set_1
$set_2

Content
A data.frame with 3 columns (depth, intensity, error)
A data.frame with 3 columns (depth, intensity, error)
A list of 4 data.frames, each representing a sample with different ages
A list of 5 data.frames, each representing a sample with different ages

Details
$sample_1
mu
0.9

sigmaphi
5e-10

age
10000

$sample_2
mu
0.9

sigmaphi
5e-10

age
10000

Dose rate
2.5

D0
40

$set_1
mu
0.9

sigmaphi
5e-10

ages
1e3, 1e4, 1e5, 1e6

$set_2
mu
0.9

sigmaphi
5e-10

ages
1e2, 1e3, 1e4, 1e5, 1e6

Source
See examples for the code used to create the data sets.
References
Unpublished synthetic data
Examples
## ExampleData.SurfaceExposure$sample_1
sigmaphi <- 5e-10
age <- 10000
mu <- 0.9
x <- seq(0, 10, 0.1)

Dose rate
1.0

D0
40

148

ExampleData.SurfaceExposure
fun <- exp(-sigmaphi * age * 365.25*24*3600 * exp(-mu * x))
set.seed(666)
synth_1 <- data.frame(depth = x,
intensity = jitter(fun, 1, 0.1),
error = runif(length(x), 0.01, 0.2))
## VALIDATE sample_1
fit_SurfaceExposure(synth_1, mu = mu, sigmaphi = sigmaphi)

## ExampleData.SurfaceExposure$sample_2
sigmaphi <- 5e-10
age <- 10000
mu <- 0.9
x <- seq(0, 10, 0.1)
Ddot <- 2.5
/ 1000 / 365.25 / 24 / 60 / 60 # 2.5 Gy/ka in Seconds
D0 <- 40
fun <- (sigmaphi * exp(-mu * x) *
exp(-(age * 365.25*24*3600) *
(sigmaphi * exp(-mu * x) + Ddot/D0)) + Ddot/D0) /
(sigmaphi * exp(-mu * x) + Ddot/D0)
set.seed(666)
synth_2 <- data.frame(depth = x,
intensity = jitter(fun, 1, 0.1),
error = runif(length(x), 0.01, 0.2))
## VALIDATE sample_2
fit_SurfaceExposure(synth_2, mu = mu, sigmaphi = sigmaphi, Ddot = 2.5, D0 = D0)

## ExampleData.SurfaceExposure$set_1
sigmaphi <- 5e-10
mu <- 0.9
x <- seq(0, 15, 0.2)
age <- c(1e3, 1e4, 1e5, 1e6)
set.seed(666)
synth_3 <- vector("list", length = length(age))
for (i in 1:length(age)) {
fun <- exp(-sigmaphi * age[i] * 365.25*24*3600 * exp(-mu * x))
synth_3[[i]] <- data.frame(depth = x,
intensity = jitter(fun, 1, 0.05))
}
## VALIDATE set_1
fit_SurfaceExposure(synth_3, age = age, sigmaphi = sigmaphi)

## ExampleData.SurfaceExposure$set_2

ExampleData.TR_OSL

149

sigmaphi <- 5e-10
mu <- 0.9
x <- seq(0, 15, 0.2)
age <- c(1e2, 1e3, 1e4, 1e5, 1e6)
Ddot <- 1.0 / 1000 / 365.25 / 24 / 60 / 60 # 2.0 Gy/ka in Seconds
D0 <- 40
set.seed(666)
synth_4 <- vector("list", length = length(age))
for (i in 1:length(age)) {
fun <- (sigmaphi * exp(-mu * x) *
exp(-(age[i] * 365.25*24*3600) *
(sigmaphi * exp(-mu * x) + Ddot/D0)) + Ddot/D0) /
(sigmaphi * exp(-mu * x) + Ddot/D0)

}

synth_4[[i]] <- data.frame(depth = x,
intensity = jitter(fun, 1, 0.05))

## VALIDATE set_2
fit_SurfaceExposure(synth_4, age = age, sigmaphi = sigmaphi, D0 = D0, Ddot = 1.0)
## Not run:
ExampleData.SurfaceExposure <- list(
sample_1 = synth_1,
sample_2 = synth_2,
set_1 = synth_3,
set_2 = synth_4
)
## End(Not run)

ExampleData.TR_OSL

Example TR-OSL data

Description
Single TR-OSL curve obtained by Schmidt et al. (under review) for quartz sample BT729 (origin:
Trebgast Valley, Germay, quartz, 90-200 µm, unpublished data).
Format
One RLum.Data.Curve dataset imported using the function read_XSYG2R
ExampleData.TR_OSL: A single RLum.Data.Curve object with the TR-OSL data
References
Schmidt, C., Simmank, O., Kreutzer, S., under review. Time-Resolved Optically Stimulated Luminescence of Quartz in the Nanosecond Time Domain. Journal of Luminescence, 1-90

150

ExampleData.XSYG

See Also
fit_OSLLifeTimes
Examples
##(1) curves
data(ExampleData.TR_OSL, envir = environment())
plot_RLum(ExampleData.TR_OSL)

ExampleData.XSYG

Example data for a SAR OSL measurement and a TL spectrum using
a lexsyg reader

Description
Example data from a SAR OSL measurement and a TL spectrum for package Luminescence imported from a Freiberg Instruments XSYG file using the function read_XSYG2R.
Format
OSL.SARMeasurement: SAR OSL measurement data
The data contain two elements: (a) $Sequence.Header is a data.frame with metadata from the
measurement,(b) Sequence.Object contains an RLum.Analysis object for further analysis.
TL.Spectrum: TL spectrum data
RLum.Data.Spectrum object for further analysis. The spectrum was cleaned from cosmic-rays
using the function
apply_CosmicRayRemoval. Note that no quantum efficiency calibration was performed.
Version
0.1
Source
OSL.SARMeasurement
Lab:
Lab-Code:
Location:
Material:
Reference:

Luminescence Laboratory Giessen
no code
not specified
Coarse grain quartz on steel cups on lexsyg research reader
unpublished

TL.Spectrum
Lab:
Lab-Code:
Location:
Material:

Luminescence Laboratory Giessen
BT753
Dolni Vestonice/Czech Republic
Fine grain polymineral on steel cups on lexsyg rearch reader

ExampleData.XSYG
Reference:
Spectrum:
Heating:

151
Fuchs et al., 2013
Integration time 19 s, channel time 20 s
1 K/s, up to 500 deg. C

References
Unpublished data measured to serve as example data for that package. Location origin of sample
BT753 is given here:
Fuchs, M., Kreutzer, S., Rousseau, D.D., Antoine, P., Hatte, C., Lagroix, F., Moine, O., Gauthier,
C., Svoboda, J., Lisa, L., 2013. The loess sequence of Dolni Vestonice, Czech Republic: A new
OSL-based chronology of the Last Climatic Cycle. Boreas, 42, 664–677.

See Also
read_XSYG2R, RLum.Analysis, RLum.Data.Spectrum, plot_RLum, plot_RLum.Analysis, plot_RLum.Data.Spectrum

Examples
##show data
data(ExampleData.XSYG, envir = environment())
## =========================================
##(1) OSL.SARMeasurement
OSL.SARMeasurement
##show $Sequence.Object
OSL.SARMeasurement$Sequence.Object
##grep OSL curves and plot the first curve
OSLcurve <- get_RLum(OSL.SARMeasurement$Sequence.Object,
recordType="OSL")[[1]]
plot_RLum(OSLcurve)
## =========================================
##(2) TL.Spectrum
TL.Spectrum
##plot simple spectrum (2D)
plot_RLum.Data.Spectrum(TL.Spectrum,
plot.type="contour",
xlim = c(310,750),
ylim = c(0,300),
bin.rows=10,
bin.cols = 1)
##plot 3d spectrum (uncomment for usage)
# plot_RLum.Data.Spectrum(TL.Spectrum, plot.type="persp",
# xlim = c(310,750), ylim = c(0,300), bin.rows=10,
# bin.cols = 1)

152

extdata

extdata

Collection of External Data

Description
Description and listing of data provided in the folder data/extdata
Details
The R package Luminescence includes a number of raw data files, which are mostly used in the
example sections of appropriate functions. They are also used internally for testing corresponding
functions using the testthat package (see files in tests/testthat/) to ensure their operational
reliability.
Accessibility
If the R package Luminescence is installed correctly the preferred way to access and use these data
from within R is as follows:
system.file("extdata/",package = "Luminescence")
Individual file descriptions
»Daybreak_TestFile.DAT/.txt«
Type: raw measurement data
Device: Daybreak OSL/TL reader
Measurement date: unknown
Location: unknown
Provided by: unknown
Related R function(s): read_Daybreak2R()
Reference: unknown
»DorNie_0016.psl«
Type: raw measurement data
Device: SUERC portable OSL reader
Measurement date: 19/05/2016
Location: Dormagen-Nievenheim, Germany
Provided by: Christoph Burow (University of Cologne)
Related R function(s): read_PSL2R()
Reference: unpublished
Additional information: Sample measured at an archaeological site near
Dormagen-Nievenheim (Germany) during a practical course on Luminesence dating in 2016.
»QNL84_2_bleached.txt, QNL84_2_unbleached.txt«
Type: Test data for exponential fits
Reference: Berger, G.W., Huntley, D.J., 1989. Test data for exponential fits. Ancient TL 7, 43-46.
»STRB87_1_bleached.txt, STRB87_1_unbleached.txt«
Type: Test data for exponential fits
Reference: Berger, G.W., Huntley, D.J., 1989. Test data for exponential fits. Ancient TL 7, 43-46.
»XYSG_file.xysg

extract_IrradiationTimes

153

Type: XSYG-file stump
**Info: ** XSYG-file with some basic curves to test functions
Reference: no reference available

extract_IrradiationTimes
Extract Irradiation Times from an XSYG-file

Description
Extracts irradiation times, dose and times since last irradiation, from a Freiberg Instruments XSYGfile. These information can be further used to update an existing BINX-file.
Usage
extract_IrradiationTimes(object, file.BINX,
recordType = c("irradiation (NA)", "IRSL (UVVIS)", "OSL (UVVIS)",
"TL (UVVIS)"), compatibility.mode = TRUE, txtProgressBar = TRUE)
Arguments
object

character, RLum.Analysis or list (required): path and file name of the XSYG
file or an RLum.Analysis produced by the function read_XSYG2R; alternatively
a list of RLum.Analysis can be provided.
Note: If an RLum.Analysis is used, any input for the arguments file.BINX and
recordType will be ignored!

file.BINX

character (optional): path and file name of an existing BINX-file. If a file name
is provided the file will be updated with the information from the XSYG file in
the same folder as the original BINX-file.
Note: The XSYG and the BINX-file have to be originate from the same measurement!

recordType

character (with default): select relevant curves types from the XSYG file or
RLum.Analysis object. As the XSYG-file format comprises much more information than usually needed for routine data analysis and allowed in the BINXfile format, only the relevant curves are selected by using the function get_RLum.
The argument recordType works as described for this function.
Note: A wrong selection will causes a function error. Please change this argument only if you have reasons to do so.
compatibility.mode
logical (with default): this option is parsed only if a BIN/BINX file is produced
and it will reset all position values to a max. value of 48, cf.write_R2BIN
txtProgressBar logical (with default): enables TRUE or disables FALSE the progression bars during import and export
Details
The function was written to compensate missing information in the BINX-file output of Freiberg
Instruments lexsyg readers. As all information are available within the XSYG-file anyway, these
information can be extracted and used for further analysis or/and to stored in a new BINX-file,
which can be further used by other software, e.g., Analyst (Geoff Duller).

154

extract_IrradiationTimes
Typical application example: g-value estimation from fading measurements using the Analyst or
any other self written script.
Beside the some simple data transformation steps the function applies the functions read_XSYG2R,
read_BIN2R, write_R2BIN for data import and export.

Value
An RLum.Results object is returned with the following structure:
.. $irr.times (data.frame)
If a BINX-file path and name is set, the output will be additionally transferred into a new BINX-file
with the function name as suffix. For the output the path of the input BINX-file itself is used. Note
that this will not work if the input object is a file path to an XSYG-file, instead of a link to only one
file. In this case the argument input for file.BINX is ignored.
In the self call mode (input is a list of RLum.Analysis objects a list of RLum.Results is returned.
Function version
0.3.1 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). extract_IrradiationTimes(): Extract Irradiation Times from an XSYG-file.
Function version 0.3.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
The produced output object contains still the irradiation steps to keep the output transparent. However, for the BINX-file export this steps are removed as the BINX-file format description does not
allow irradiations as separat sequences steps.
BINX-file ’Time Since Irradiation’ value differs from the table output?
The way the value ’Time Since Irradiation’ is defined differs. In the BINX-file the ’Time Since
Irradiation’ is calculated as the ’Time Since Irradiation’ plus the ’Irradiation Time’. The table
output returns only the real ’Time Since Irradiation’, i.e. time between the end of the irradiation
and the next step.
Negative values for TIMESINCELAS.STEP?
Yes, this is possible and no bug, as in the XSYG-file multiple curves are stored for one step. Example: TL step may comprise three curves:
• (a) counts vs. time,
• (b) measured temperature vs. time and
• (c) predefined temperature vs. time.
Three curves, but they are all belonging to one TL measurement step, but with regard to the time
stamps this could produce negative values as the important function (read_XSYG2R) do not change
the order of entries for one step towards a correct time order.

fit_CWCurve

155

Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
References
Duller, G.A.T., 2015. The Analyst software package for luminescence data: overview and recent
improvements. Ancient TL 33, 35-42.
See Also
RLum.Analysis, RLum.Results, Risoe.BINfileData, read_XSYG2R, read_BIN2R, write_R2BIN
Examples

## (1) - example for your own data
##
## set files and run function
#
# file.XSYG <- file.choose()
# file.BINX <- file.choose()
#
#
output <- extract_IrradiationTimes(file.XSYG = file.XSYG, file.BINX = file.BINX)
#
get_RLum(output)
#
## export results additionally to a CSV.file in the same directory as the XSYG-file
#
write.table(x = get_RLum(output),
#
file = paste0(file.BINX,"_extract_IrradiationTimes.csv"),
#
sep = ";",
#
row.names = FALSE)

fit_CWCurve

Nonlinear Least Squares Fit for CW-OSL curves [beta version]

Description
The function determines the weighted least-squares estimates of the component parameters of a
CW-OSL signal for a given maximum number of components and returns various component parameters. The fitting procedure uses the nls function with the port algorithm.
Usage
fit_CWCurve(values, n.components.max, fit.failure_threshold = 5,
fit.method = "port", fit.trace = FALSE, fit.calcError = FALSE,
LED.power = 36, LED.wavelength = 470, cex.global = 0.6,
sample_code = "Default", output.path, output.terminal = TRUE,
output.terminalAdvanced = TRUE, plot = TRUE, ...)

156

fit_CWCurve

Arguments
values

RLum.Data.Curve or data.frame (required): x, y data of measured values (time
and counts). See examples.
n.components.max
vector (optional): maximum number of components that are to be used for fitting. The upper limit is 7.
fit.failure_threshold
vector (with default): limits the failed fitting attempts.
fit.method

character (with default): select fit method, allowed values: 'port' and 'LM'.
'port' uses the ’port’ routine usint the funtion nls 'LM' utilises the function
nlsLM from the package minpack.lm and with that the Levenberg-Marquardt
algorithm.

fit.trace

logical (with default): traces the fitting process on the terminal.

fit.calcError

logical (with default): calculate 1-sigma error range of components using confint

LED.power

numeric (with default): LED power (max.) used for intensity ramping in mW/cm^2.
Note: The value is used for the calculation of the absolute photoionisation cross
section.

LED.wavelength numeric (with default): LED wavelength used for stimulation in nm. Note: The
value is used for the calculation of the absolute photoionisation cross section.
cex.global

numeric (with default): global scaling factor.

sample_code

character (optional): sample code used for the plot and the optional output table
(mtext).

output.path

character (optional): output path for table output containing the results of the fit.
The file name is set automatically. If the file already exists in the directory, the
values are appended.

output.terminal
logical (with default): terminal ouput with fitting results.
output.terminalAdvanced
logical (with default): enhanced terminal output. Requires output.terminal =
TRUE. If output.terminal = FALSE no advanced output is possible.
plot

logical (with default): returns a plot of the fitted curves.

...

further arguments and graphical parameters passed to plot.

Details
Fitting function
The function for the CW-OSL fitting has the general form:
y = I01 ∗ λ1 ∗ exp(−λ1 ∗ x)+, . . . , +I0i ∗ λi ∗ exp(−λi ∗ x)
where 0 < i < 8
and λ is the decay constant
and I0 the intial number of trapped electrons.
(for the used equation cf. Boetter-Jensen et al., 2003, Eq. 2.31)
Start values
Start values are estimated automatically by fitting a linear function to the logarithmized input data
set. Currently, there is no option to manually provide start parameters.

fit_CWCurve

157

Goodness of fit
The goodness of the fit is given as pseudoR^2 value (pseudo coefficient of determination). According to Lave (1970), the value is calculated as:
pseudoR2 = 1 − RSS/T SS
where RSS = Residual Sum of Squares
and T SS = T otal Sum of Squares
Error of fitted component parameters
The 1-sigma error for the components is calculated using the function confint. Due to considerable
calculation time, this option is deactived by default. In addition, the error for the components can be
estimated by using internal R functions like summary. See the nls help page for more information.
For details on the nonlinear regression in R, see Ritz & Streibig (2008).
Value
plot (optional)
the fitted CW-OSL curves are returned as plot.
table (optional)
an output table (*.csv) with parameters of the fitted components is provided if the output.path is
set.
RLum.Results
Beside the plot and table output options, an RLum.Results object is returned.
fit: an nls object ($fit) for which generic R functions are provided, e.g. summary, confint,
profile. For more details, see nls.
output.table: a data.frame containing the summarised parameters including the error
component.contribution.matrix: matrix containing the values for the component to sum contribution plot ($component.contribution.matrix).
Matrix structure:
Column 1 and 2: time and rev(time) values
Additional columns are used for the components, two for each component, containing I0 and n0.
The last columns cont. provide information on the relative component contribution for each time
interval including the row sum for this values.
object
beside the plot and table output options, an RLum.Results object is returned.
fit: an nls object ($fit) for which generic R functions are provided, e.g. summary, confint,
profile. For more details, see nls.
output.table: a data.frame containing the summarised parameters including the error
component.contribution.matrix: matrix containing the values for the component to sum contribution plot ($component.contribution.matrix).
Matrix structure:
Column 1 and 2: time and rev(time) values
Additional columns are used for the components, two for each component, containing I0 and n0.
The last columns cont. provide information on the relative component contribution for each time
interval including the row sum for this values.

158

fit_CWCurve

Function version
0.5.2 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). fit_CWCurve(): Nonlinear Least Squares Fit for CW-OSL curves [beta version]. Function version 0.5.2. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt,
C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data
Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
Beta version - This function has not been properly tested yet and should therefore not be used
for publication purposes!
The pseudo-R^2 may not be the best parameter to describe the goodness of the fit. The trade off
between the n.components and the pseudo-R^2 value is currently not considered.
The function does not ensure that the fitting procedure has reached a global minimum rather than a
local minimum!
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
References
Boetter-Jensen, L., McKeever, S.W.S., Wintle, A.G., 2003. Optically Stimulated Luminescence
Dosimetry. Elsevier Science B.V.
Lave, C.A.T., 1970. The Demand for Urban Mass Transportation. The Review of Economics and
Statistics, 52 (3), 320-323.
Ritz, C. & Streibig, J.C., 2008. Nonlinear Regression with R. In: R. Gentleman, K. Hornik, G.
Parmigiani, eds., Springer, p. 150.
See Also
fit_LMCurve, plot,nls, RLum.Data.Curve, RLum.Results, get_RLum, minpack.lm::nlsLM
Examples
##load data
data(ExampleData.CW_OSL_Curve, envir = environment())
##fit data
fit <- fit_CWCurve(values = ExampleData.CW_OSL_Curve,
main = "CW Curve Fit",
n.components.max = 4,
log = "x")

fit_EmissionSpectra

159

fit_EmissionSpectra

Luminescence Emission Spectra Deconvolution

Description
Luminescence spectra deconvolution on RLum.Data.Spectrum and matrix objects on an energy
scale. The function is optimised for emission spectra typially obtained in the context of TL, OSL
and RF measurements detected between 200 and 1000 nm.
Usage
fit_EmissionSpectra(object, frame = NULL, start_parameters = NULL,
sub_negative = 0, input_scale = NULL, method_control = list(),
verbose = TRUE, plot = TRUE, ...)
Arguments
object

RLum.Data.Spectrum, matrix (required): input object. Please note that an energy spectrum is expected

frame
numeric (optional): defines the frame to be analysed
start_parameters
(optional): allows to provide own start parameters for a semi-automated precedure. ##TODO
sub_negative

numeric (with default): substitute negative values in the input object by the number provided here (default: 0). Can be set to NULL, i.e. negative values are kept.

input_scale

character (optional): defines whether your x-values define wavelength or energy values. For the analysis an energy scale is expected, allowed values are
'wavelength' and 'energy'. If nothing (NULL) is defined, the function tries to
understand the input automatically.

method_control list (optional): options to control the fit method, see details
verbose

logical (with default): enable/disable verbose mode

plot

logical (with default): enable/disable plot output

...

further arguments to be passed to control the plot output (supported: main,
xlab, ylab, xlim, ylim, log, mtext, legend (TRUE or FALSE), legend.text,
legend.pos)

Details
Used equation
The emission spectra (on an energy scale) can be best described as the sum of multiple Gaussian
components:
’
y = ΣCi ∗ 1/(σi ∗

p
(2 ∗ π)) ∗ exp(1/2 ∗ ((x − µi )/σi ))2 )

with the parameters σ (peak width) and µ (peak centre) and C (scaling factor).
Start parameter estimation and fitting algorithm
The spectrum deconvolution consits of the following steps:

160

fit_EmissionSpectra
1. Peak finding
2. Start parameter estimation
3. Fitting via minpack.lm::nls.lm
The peak finding is realised by an approach (re-)suggested by Petr Pikal via the R-help mailing list
(https://stat.ethz.ch/pipermail/r-help/2005-November/thread.html) in November 2005. This goes
back to even earlier discussion in 2001 based on Prof Brian Ripley’s idea. It smartly uses the functions stats::embed and max.col to identify peaks positions. For the use in this context, the algorithm
has been further modified to scale on the input data resolution (cv source code).
The start parameter estimation uses random sampling from a range of meaningful parameters and
repeats the fitting until 100 sucessful fits have been produced or the set max.runs value is exceeded.
Currently the best fit is the one with the lowest number for squared residuals.
Supported method_control settings

Parameter
max.runs
trace

Type
integer
logical

Default
1000
FALSE

Descritpion
maximum allowed search iterations, if exceed the searching stops
enables/disables the tracing of the minimisation routine

Value
———————————–
[ NUMERICAL OUTPUT ]
———————————–
RLum.Results-object
slot: @data
Element
$data
$fit

Type
matrix
nls

Description
the final fit matrix
the fit object returned by minpack.lm::nls.lm

slot: @info
The original function call
————————
[ TERMINAL OUTPUT ]
————————
The terminal output provides brief information on the deconvolution process and the obtained results. Terminal output is only shown of the argument verbose = TRUE.
————————
[ PLOT OUTPUT ]
————————
The function returns a plot showing the raw signal with the detected components. If the fitting
failed, a basic plot is returned showing the raw data and indicating the peaks detected for the start

fit_EmissionSpectra

161

parameter estimation.
Function version
0.1.0 (2019-02-25 19:18:38)
How to cite
Kreutzer, S. (2019). fit_EmissionSpectra(): Luminescence Emission Spectra Deconvolution. Function version 0.1.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
Beta version, not uet recommended for productive usage
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France)
R Luminescence Package Team
References
##TODO
See Also
RLum.Data.Spectrum, RLum.Results, plot_RLum, convert_Wavelength2Energy, minpack.lm::nls.lm
Examples
##deconvolution of a TL spectrum
##TODO should be modified ...
## Not run:
##load example data
data(ExampleData.XSYG, envir = environment())
##subtract background
TL.Spectrum@data <- TL.Spectrum@data[] - TL.Spectrum@data[,15]
##replace 0 values
results <- fit_EmissionSpectra(
object = TL.Spectrum,
frame = 5, main = "TL spectrum"
)
## End(Not run)

162

fit_LMCurve

fit_LMCurve

Nonlinear Least Squares Fit for LM-OSL curves

Description
The function determines weighted nonlinear least-squares estimates of the component parameters of
an LM-OSL curve (Bulur 1996) for a given number of components and returns various component
parameters. The fitting procedure uses the function nls with the port algorithm.
Usage
fit_LMCurve(values, values.bg, n.components = 3, start_values,
input.dataType = "LM", fit.method = "port", sample_code = "",
sample_ID = "", LED.power = 36, LED.wavelength = 470,
fit.trace = FALSE, fit.advanced = FALSE, fit.calcError = FALSE,
bg.subtraction = "polynomial", verbose = TRUE, plot = TRUE,
plot.BG = FALSE, ...)
Arguments
values

RLum.Data.Curve or data.frame (required): x,y data of measured values (time
and counts). See examples.

values.bg

RLum.Data.Curve or data.frame (optional): x,y data of measured values (time
and counts) for background subtraction.

n.components

integer (with default): fixed number of components that are to be recognised
during fitting (min = 1, max = 7).

start_values

data.frame (optional): start parameters for lm and xm data for the fit. If no start
values are given, an automatic start value estimation is attempted (see details).

input.dataType character (with default): alter the plot output depending on the input data: "LM"
or "pLM" (pseudo-LM). See: CW2pLM
fit.method

character (with default): select fit method, allowed values: 'port' and 'LM'.
'port' uses the ’port’ routine usint the funtion nls 'LM' utilises the function
nlsLM from the package minpack.lm and with that the Levenberg-Marquardt
algorithm.

sample_code

character (optional): sample code used for the plot and the optional output table
(mtext).

sample_ID

character (optional): additional identifier used as column header for the table
output.

LED.power

numeric (with default): LED power (max.) used forintensity ramping in mW/cm^2.
Note: This value is used for the calculation of the absolute photoionisation cross
section.

LED.wavelength numeric (with default): LED wavelength in nm used for stimulation. Note: This
value is used for the calculation of the absolute photoionisation cross section.
fit.trace

logical (with default): traces the fitting process on the terminal.

fit.advanced

logical (with default): enables advanced fitting attempt for automatic start parameter recognition. Works only if no start parameters are provided. Note: It
may take a while and it is not compatible with fit.method = "LM".

fit_LMCurve
fit.calcError

163
logical (with default): calculate 1-sigma error range of components using confint.

bg.subtraction character (with default): specifies method for background subtraction (polynomial,
linear, channel, see Details). Note: requires input for values.bg.
verbose

logical (with default): terminal output with fitting results.

plot

logical (with default): returns a plot of the fitted curves.

plot.BG

logical (with default): returns a plot of the background values with the fit used
for the background subtraction.

...

Further arguments that may be passed to the plot output, e.g. xlab, xlab, main,
log.

Details
Fitting function
The function for the fitting has the general form:
y = (exp(0.5)∗Im1 ∗x/xm1 )∗exp(−x2 /(2∗xm21 ))+, . . . , +exp(0.5)∗Imi ∗x/xmi )∗exp(−x2 /(2∗xm2i ))
where 1 < i < 8
This function and the equations for the conversion to b (detrapping probability) and n0 (proportional
to initially trapped charge) have been taken from Kitis et al. (2008):
xmi =

p

max(t)/bi

Imi = exp(−0.5)n0/xmi
Background subtraction
Three methods for background subtraction are provided for a given background signal (values.bg).
• polynomial: default method. A polynomial function is fitted using glm and the resulting
function is used for background subtraction:
y = a ∗ x4 + b ∗ x3 + c ∗ x2 + d ∗ x + e
• linear: a linear function is fitted using glm and the resulting function is used for background
subtraction:
y =a∗x+b
• channel: the measured background signal is subtracted channelwise from the measured signal.
Start values
The choice of the initial parameters for the nls-fitting is a crucial point and the fitting procedure
may mainly fail due to ill chosen start parameters. Here, three options are provided:
(a) If no start values (start_values) are provided by the user, a cheap guess is made by using the
detrapping values found by Jain et al. (2003) for quartz for a maximum of 7 components. Based
on these values, the pseudo start parameters xm and Im are recalculated for the given data set. In
all cases, the fitting starts with the ultra-fast component and (depending on n.components) steps
through the following values. If no fit could be achieved, an error plot (for plot = TRUE) with the
pseudo curve (based on the pseudo start parameters) is provided. This may give the opportunity to
identify appropriate start parameters visually.

164

fit_LMCurve
(b) If start values are provided, the function works like a simple nls fitting approach.
(c) If no start parameters are provided and the option fit.advanced = TRUE is chosen, an advanced
start paramter estimation is applied using a stochastical attempt. Therefore, the recalculated start
parameters (a) are used to construct a normal distribution. The start parameters are then sampled
randomly from this distribution. A maximum of 100 attempts will be made. Note: This process
may be time consuming.
Goodness of fit
The goodness of the fit is given by a pseudoR^2 value (pseudo coefficient of determination). According to Lave (1970), the value is calculated as:
pseudoR2 = 1 − RSS/T SS
where RSS = Residual Sum of Squares and T SS = T otal Sum of Squares
Error of fitted component parameters
The 1-sigma error for the components is calculated using the function confint. Due to considerable
calculation time, this option is deactived by default. In addition, the error for the components can be
estimated by using internal R functions like summary. See the nls help page for more information.
For more details on the nonlinear regression in R, see Ritz & Streibig (2008).

Value
Various types of plots are returned. For details see above. Furthermore an RLum.Results object is
returned with the following structure:
@data:
.. $data : data.frame with fitting results
.. $fit : nls (nls object)
.. $component.contribution.matrix : list component distribution matrix
info:
.. $call : call the original function call
Matrix structure for the distribution matrix:
Column 1 and 2: time and rev(time) values
Additional columns are used for the components, two for each component, containing I0 and n0.
The last columns cont. provide information on the relative component contribution for each time
interval including the row sum for this values.
Function version
0.3.2 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). fit_LMCurve(): Nonlinear Least Squares Fit for LM-OSL curves. Function
version 0.3.2. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M.,
Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence

fit_LMCurve

165

Note
The pseudo-R^2 may not be the best parameter to describe the goodness of the fit. The trade off
between the n.components and the pseudo-R^2 value currently remains unconsidered.
The function does not ensure that the fitting procedure has reached a global minimum rather than a
local minimum! In any case of doubt, the use of manual start values is highly recommended.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
References
Bulur, E., 1996. An Alternative Technique For Optically Stimulated Luminescence (OSL) Experiment. Radiation Measurements, 26, 5, 701-709.
Jain, M., Murray, A.S., Boetter-Jensen, L., 2003. Characterisation of blue-light stimulated luminescence components in different quartz samples: implications for dose measurement. Radiation
Measurements, 37 (4-5), 441-449.
Kitis, G. & Pagonis, V., 2008. Computerized curve deconvolution analysis for LM-OSL. Radiation
Measurements, 43, 737-741.
Lave, C.A.T., 1970. The Demand for Urban Mass Transportation. The Review of Economics and
Statistics, 52 (3), 320-323.
Ritz, C. & Streibig, J.C., 2008. Nonlinear Regression with R. R. Gentleman, K. Hornik, & G.
Parmigiani, eds., Springer, p. 150.
See Also
fit_CWCurve, plot, nls, minpack.lm::nlsLM, get_RLum
Examples
##(1) fit LM data without background subtraction
data(ExampleData.FittingLM, envir = environment())
fit_LMCurve(values = values.curve, n.components = 3, log = "x")
##(2) fit LM data with background subtraction and export as JPEG
## -alter file path for your preferred system
##jpeg(file = "~/Desktop/Fit_Output\%03d.jpg", quality = 100,
## height = 3000, width = 3000, res = 300)
data(ExampleData.FittingLM, envir = environment())
fit_LMCurve(values = values.curve, values.bg = values.curveBG,
n.components = 2, log = "x", plot.BG = TRUE)
##dev.off()
##(3) fit LM data with manual start parameters
data(ExampleData.FittingLM, envir = environment())
fit_LMCurve(values = values.curve,
values.bg = values.curveBG,
n.components = 3,
log = "x",
start_values = data.frame(Im = c(170,25,400), xm = c(56,200,1500)))

166

fit_OSLLifeTimes

fit_OSLLifeTimes

Fitting and Deconvolution of OSL Lifetime Components

Description
Fitting and Deconvolution of OSL Lifetime Components
Usage
fit_OSLLifeTimes(object, tp = 0, signal_range = NULL,
n.components = NULL, method_control = list(), plot = TRUE,
verbose = TRUE, ...)
Arguments
object

RLum.Data.Curve, RLum.Analysis, data.frame or matrix (required): Input object containing the data to be analysed. All objects can be provided also as list
for an automated processing. Please note: NA values are automatically removed
and the dataset should comprise at least 5 data points.

tp

numeric (with default): option to account for the stimulation pulse width. For
off-time measurements the default value is 0. tp has the same unit as the measurement data, e.g., µs. Please set this parameter carefully, if it all, otherwise
you may heavily bias your fit results.

signal_range

numeric (optional): allows to set a channel range, by default all channels are
used, e.g. signal_range = c(2,100) considers only channels 2 to 100 and
signal_range = c(2) considers only channels from channel 2 onwards.

n.components

numeric (optional): Fix the number of components. If set the algorithm will try
to fit the number of predefined components. If nothing is set, the algorithm will
try to find the best number of components.

method_control list (optonal): Named to allow a more fine control of the fitting process. See
details for allowed options.
plot

logical (with default): Enable/disable plot output

verbose

logical (with default): Enable/disable terminal feedback

...

parameters passed to plot.default to control the plot output. Please note that not
all parameters are supported.

Details
The function intends to provide an easy access to pulsed optically stimulated luminescence (POSL)
data, in order determine signal lifetimes. The fitting is currently optimised to work with the off-time
flank of POSL measurements only. For the signal deconvolution, a differential evolution optimisation is combined with nonlinear least-square fitting following the approach by Bluszcz & Adamiec
(2006).
Component deconvolution algorithm
The component deconvolution consists of two steps:
(1) Adaption phase
In the adaption phase the function tries to figure out the optimal and statistically justified number
of signal components following roughly the approach suggestd by Bluszcz & Adamiec (2006). In

fit_OSLLifeTimes

167

contrast to their work, for the optimisation by differential evolution here the package ’DEoptim’ is
used.
The function to be optimized has the form:
χ2 =

X
X
(w ∗ (ni /c −
(Ai ∗ exp(−x/(taui + tp ))))2 )

with w = 1 for unweighted regression analysis (method_control = list(weights = FALSE)) or
w = c2 /ni for weighted regression analysis. The default values is TRUE.
F = (∆χ2 /2)/(χ2 /(N − 2 ∗ m − 2))
(2) Final fitting
method_control
Parameter
p
seed
DEoptim.trace
DEoptim.itermax
weights
nlsLM.trace
nlsLM.upper
nlsLM.lower

Type
numeric
numeric
logical
logical
logical
logical
logical
logical

Description
controls the probability for the F statistic reference values. For a significance level of 5%
set the seed for the random number generator, provide a value here to get reproducible res
enables/disables the tracing of the differential evolution (cf. DEoptim::DEoptim.control)
controls the number of the allowed generations (cf. DEoptim::DEoptim.control)
enables/disables the weighting for the start parameter estimation and fitting (see equations
enables/disables trace mode for the nls fitting (minpack.lm::nlsLM), can be used to identi
enables/disables upper parameter boundary, default is TRUE
enables/disables lower parameter boundary, default is TRUE

Value
———————————–
[ NUMERICAL OUTPUT ]
———————————–
RLum.Results-object
slot: @data
Element
$data
$start_matrix
$total_counts
$fit

Type
matrix
matrix
integer
nls

Description
the final fit matrix
the start matrix used for the fitting
Photon count sum
the fit object returned by minpack.lm::nls.lm

slot: @info
The original function call
————————
[ TERMINAL OUTPUT ]
————————
Terminal output is only shown of the argument verbose = TRUE.
(1) Start parameter and component adapation
Trave of the parameter adaption process

168

fit_OSLLifeTimes
(2) Fitting results (sorted by ascending tau)
The fitting results sorted by ascending tau value. Please note that if you access the nls fitting object,
the values are not sorted.
(3) Further information
• The photon count sum
• Durbin-Watson residual statistic to asses whether the residuals are correlated, ideally the residuals should be not correlated at all. Rough measures are:
D = 0: the residuls are systematically correlated
D = 2: the residuals are randomly distributed
D = 4: the residuals are systematically anticorrlated
You should be suspicious if D differs largely from 2.
————————
[ PLOT OUTPUT ]
————————
A plot showing the original data and the fit so far possible. The lower plot shows the residuals of
the fit.

Function version
0.1.3 (2019-04-20 14:15:11)
How to cite
Kreutzer, S., Schmidt, C. (2019). fit_OSLLifeTimes(): Fitting and Deconvolution of OSL Lifetime Components. Function version 0.1.3. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C.,
Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS-Université Bordeaux Montaigne (France),
Christoph Schmidt, University of Bayreuth (Germany)
R Luminescence Package Team
References
Bluszcz, A., Adamiec, G., 2006. Application of differential evolution to fitting OSL decay curves.
Radiation Measurements 41, 886-891. doi:10.1016/j.radmeas.2006.05.016
Durbin, J., Watson, G.S., 1950. Testing for Serial Correlation in Least Squares Regression: I.
Biometrika 37, 409-21. doi:10.2307/2332391
Further reading
Hughes, I., Hase, T., 2010. Measurements and Their Uncertainties. Oxford University Press.
Storn, R., Price, K., 1997. Differential Evolution – A Simple and Efficient Heuristic for Global
Optimization over Continuous Spaces. Journal of Global Optimization 11, 341–359.

fit_SurfaceExposure

169

See Also
minpack.lm::nls.lm, DEoptim::DEoptim
Examples
##load example data
data(ExampleData.TR_OSL, envir = environment())
##fit lifetimes (short run)
fit_OSLLifeTimes(
object = ExampleData.TR_OSL,
n.components = 1)
##long example
## Not run:
fit_OSLLifeTimes(
object = ExampleData.TR_OSL)
## End(Not run)

fit_SurfaceExposure

Nonlinear Least Squares Fit for OSL surface exposure data

Description
This function determines the (weighted) least-squares estimates of the parameters of either eq. 1 in
Sohbati et al. (2012a) or eq. 12 in Sohbati et al. (2012b) for a given OSL surface exposure data set
(BETA).
Usage
fit_SurfaceExposure(data, sigmaphi = NULL, mu = NULL, age = NULL,
Ddot = NULL, D0 = NULL, weights = FALSE, plot = TRUE,
legend = TRUE, error_bars = TRUE, coord_flip = FALSE, ...)
Arguments
data

data.frame or list (required): Measured OSL surface exposure data with the
following structure:
(optional)
| depth (a.u.)| intensity | error |
|
[ ,1] |
[ ,2] | [ ,3] |
|-------------|-----------|-------|
[1, ]|
~~~~
|
~~~~ | ~~~~ |
[2, ]|
~~~~
|
~~~~ | ~~~~ |
... |
...
|
... | ... |
[x, ]|
~~~~
|
~~~~ | ~~~~ |

170

fit_SurfaceExposure

sigmaphi
mu
age

Ddot

D0

weights
plot
legend
error_bars
coord_flip
...

Alternatively, a list of data.frames can be provided, where each data.frame
has the same structure as shown above, with the exception that they must not include the optional error column. Providing a list as input automatically activates
the global fitting procedure (see details).
numeric (optional): A numeric value for sigmaphi, i.e. the charge detrapping
rate. Example: sigmaphi = 5e-10
numeric (optional): A numeric value for mu, i.e. the light attenuation coefficient. Example: mu = 0.9
numeric (optional): The age (a) of the sample, if known. If data is a list of x
samples, then age must be a numeric vector of length x. Example: age = 10000,
or age = c(1e4,1e5,1e6).
numeric (optional): A numeric value for the environmental dose rate (Gy/ka).
For this argument to be considered a value for D0 must also be provided; otherwise it will be ignored.
numeric (optional): A numeric value for the characteristic saturation dose (Gy).
For this argument to be considered a value for Ddot must also be provided;
otherwise it will be ignored.
logical (optional): If TRUE the fit will be weighted by the inverse square of the
error. Requires data to be a data.frame with three columns.
logical (optional): Show or hide the plot.
logical (optional): Show or hide the equation inside the plot.
logical (optional): Show or hide error bars (only applies if errors were provided).
logical (optional): Flip the coordinate system.
Further parameters passed to plot. Custom parameters include:
• verbose (logical): show or hide console output
• line_col: Color of the fitted line
• line_lty: Type of the fitted line (see lty in ?par)
• line_lwd: Line width of the fitted line (see lwd in ?par)

Details
Weighted fitting
If weights = TRUE the function will use the inverse square of the error (1/σ 2 ) as weights during
fitting using minpack.lm::nlsLM. Naturally, for this to take effect individual errors must be provided
in the third column of the data.frame for data. Weighted fitting is not supported if data is a list
of multiple data.frames, i.e., it is not available for global fitting.
Dose rate
If any of the arguments Ddot or D0 is at its default value (NULL), this function will fit eq. 1 in Sohbati
et al. (2012a) to the data. If the effect of dose rate (i.e., signal saturation) needs to be considered,
numeric values for the dose rate (Ddot) (in Gy/ka) and the characteristic saturation dose (D0) (in
Gy) must be provided. The function will then fit eq. 12 in Sohbati et al. (2012b) to the data.
NOTE: Currently, this function does not consider the variability of the dose rate with sample depth
(x)! In the original equation the dose rate D is an arbitrary function of x (term D(x)), but here D is
assumed constant.
Global fitting
If data is list of multiple data.frames, each representing a separate sample, the function automatically performs a global fit to the data. This may be useful to better constrain the parameters
sigmaphi or mu and requires that known ages for each sample is provided (e.g., age = c(100,1000)
if data is a list with two samples).

fit_SurfaceExposure

171

Value
Function returns results numerically and graphically:
———————————–
[ NUMERICAL OUTPUT ]
———————————–
RLum.Results-object
slot: @data
Element
$summary
$data
$fit
$args
$call

Type
data.frame
data.frame
nls
character
call

Description
summary of the fitting results
the original input data
the fitting object produced by minpack.lm::nlsLM
arguments of the call
the original function call

slot: @info
Currently unused.
————————
[ PLOT OUTPUT ]
————————
A scatter plot of the provided depth-intensity OSL surface exposure data with the fitted model.
Function version
0.1.0 (2019-03-04 17:37:29)
How to cite
Burow, C. (2019). fit_SurfaceExposure(): Nonlinear Least Squares Fit for OSL surface exposure
data. Function version 0.1.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt,
C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data
Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
This function has BETA status. If possible, results should be cross-checked.
Author(s)
Christoph Burow, University of Cologne (Germany)
R Luminescence Package Team
References
Sohbati, R., Murray, A.S., Chapot, M.S., Jain, M., Pederson, J., 2012a. Optically stimulated luminescence (OSL) as a chronometer for surface exposure dating. Journal of Geophysical Research
117, B09202. doi:10.1029/2012JB009383

172

fit_ThermalQuenching
Sohbati, R., Jain, M., Murray, A.S., 2012b. Surface exposure dating of non-terrestial bodies using
optically stimulated luminescence: A new method. Icarus 221, 160-166.

See Also
ExampleData.SurfaceExposure, minpack.lm::nlsLM
Examples
## Load example data
data("ExampleData.SurfaceExposure")
## Example 1 - Single sample
# Known parameters: 10000 a, mu = 0.9, sigmaphi = 5e-10
sample_1 <- ExampleData.SurfaceExposure$sample_1
head(sample_1)
results <- fit_SurfaceExposure(sample_1, mu = 0.9, sigmaphi = 5e-10)
get_RLum(results)
## Example 2 - Single sample and considering dose rate
# Known parameters: 10000 a, mu = 0.9, sigmaphi = 5e-10,
# dose rate = 2.5 Gy/ka, D0 = 40 Gy
sample_2 <- ExampleData.SurfaceExposure$sample_2
head(sample_2)
results <- fit_SurfaceExposure(sample_2, mu = 0.9, sigmaphi = 5e-10,
Ddot = 2.5, D0 = 40)
get_RLum(results)
## Example 3 - Multiple samples (global fit) to better constrain 'mu'
# Known parameters: ages = 1e3, 1e4, 1e5, 1e6 a, mu = 0.9, sigmaphi = 5e-10
set_1 <- ExampleData.SurfaceExposure$set_1
str(set_1, max.level = 2)
results <- fit_SurfaceExposure(set_1, age = c(1e3, 1e4, 1e5, 1e6),
sigmaphi = 5e-10)
get_RLum(results)
## Example 4 - Multiple samples (global fit) and considering dose rate
# Known parameters: ages = 1e2, 1e3, 1e4, 1e5, 1e6 a, mu = 0.9, sigmaphi = 5e-10,
# dose rate = 1.0 Ga/ka, D0 = 40 Gy
set_2 <- ExampleData.SurfaceExposure$set_2
str(set_2, max.level = 2)
results <- fit_SurfaceExposure(set_2, age = c(1e2, 1e3, 1e4, 1e5, 1e6),
sigmaphi = 5e-10, Ddot = 1, D0 = 40)
get_RLum(results)

fit_ThermalQuenching

Fitting Thermal Quenching Data

fit_ThermalQuenching

173

Description
Applying a nls-fitting to thermal quenching data.
Usage
fit_ThermalQuenching(data, start_param = list(),
method_control = list(), n.MC = 100, verbose = TRUE, plot = TRUE,
...)
Arguments
data

data.frame (required): input data with three columns, the first column contains
temperature values in deg. C, colmns 2 and 3 the dependent values with its error

start_param

list (optional): option to provide own start parameters for the fitting, see detalis

method_control list (optianl): further options to fine tune the fitting, see details for further information
n.MC

numeric (with default): number of Monte Carlo runs for the error estimation. If
n.MC is NULL or <=1, the error estimation is skipped

verbose

logical (with default): enables/disables terminal output

plot

logical (with default): enables/disables plot output

...

further arguments that can be passed to control the plotting, support are main,
pch, col_fit, col_points, lty, lwd, xlab, ylab, xlim, ylim, xaxt

Details
Used equation
The equation used for the fitting is
y = (A/(1 + C ∗ (exp(−W/(k ∗ x))))) + c
W is the energy depth in eV and C is dimensionless constant. A and c are used to adjust the curve
for the given signal. k is the Blotzmann in eV/K and x is the absolute temperature in K.
Error estimation
The error estimation is done be varying the input parameters using the given uncertanties in a Monte
Carlo simulation. Errors are assumed to follow a normal distribution.
start_param
The function allows the injection of own start parameters via the argument start_param. The
parameters needs to be provided as names list. The names are the parameters to be optimised.
Examples: start_param = list(A = 1,C = 1e+5,W = 0.5,c = 0)
method_control
The following arguments can be provided via method_control. Please note that arguments provided via method_control are not further tested, i.e., if the function crashs your input was probably
wrong.

174

fit_ThermalQuenching

ARGUMENT
upper
lower
trace
weights

TYPE
named vector
names vector
logical
numeric

DESCRIPTION
sets upper fitting boundaries, if provided boundaries for all arguments are requried, e.g.,
sets lower fitting boundaries (see upper for details)
enables/disables progression trace for minpack.lm::nlsLM
option to provide own weights for the fitting, the length of this vector needs to be equal t

Value
The function returns numerical output and an (optional) plot.
———————————–
[ NUMERICAL OUTPUT ]
———————————–
RLum.Results-object
slot: @data
[.. $data : data.frame]
A table with all fitting parameters and the number of Monte Carlo runs used for the error estimation.
[.. $fit : nls object]
The nls stats::nls object returned by the function minpack.lm::nlsLM. This object can be further
passed to other functions supporting an nls object (cf. details section in stats::nls)
slot: @info
[.. $call : call]
The original function call.
———————————–
[ GAPHICAL OUTPUT ]
———————————–
Plotted are temperature against the signal and their uncertainties. The fit is shown as dashed-line
(can be modified). Please note that for the fitting the absolute temperature values are used but are
re-calculated to deg. C for the plot.
Function version
0.1.0 (2019-04-19 19:06:03)
How to cite
Kreutzer, S. (2019). fit_ThermalQuenching(): Fitting Thermal Quenching Data. Function version
0.1.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J.
(2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version
0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR5060, CNRS - Université Bordeaux Montaigne (Frange)
R Luminescence Package Team

get_Layout

175

References
Wintle, A.G., 1975. Thermal Quenching of Thermoluminescence in Quartz. Geophys. J. R. astr.
Soc. 41, 107–113.
See Also
minpack.lm::nlsLM
Examples
##create short example dataset
data <- data.frame(
T = c(25, 40, 50, 60, 70, 80, 90, 100, 110),
V = c(0.06, 0.058, 0.052, 0.051, 0.041, 0.034, 0.035, 0.033, 0.032),
V_X = c(0.012, 0.009, 0.008, 0.008, 0.007, 0.006, 0.005, 0.005, 0.004))
##fit
fit_ThermalQuenching(
data = data,
n.MC = NULL)

get_Layout

Collection of layout definitions

Description
This helper function returns a list with layout definitions for homogeneous plotting.
Usage
get_Layout(layout)
Arguments
layout

character or list object (required): name of the layout definition to be returned.
If name is provided the respective definition is returned. One of the following
supported layout definitions is possible: "default", "journal.1", "small",
"empty".
User-specific layout definitions must be provided as a list object of predefined
structure, see details.

Details
The easiest way to create a user-specific layout definition is perhaps to create either an empty or a default layout object and fill/modify the definitions (user.layout <-get_Layout(data = "empty")).
Value
A list object with layout definitions for plot functions.

176

get_Quote

Function version
0.1 (2018-01-21 17:22:38)
How to cite
Dietze, M. (2019). get_Layout(): Collection of layout definitions. Function version 0.1. In:
Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019).
Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6.
https://CRAN.R-project.org/package=Luminescence
Author(s)
Michael Dietze, GFZ Potsdam (Germany)
R Luminescence Package Team
Examples
## read example data set
data(ExampleData.DeValues, envir = environment())
## show structure of the default layout definition
layout.default <- get_Layout(layout = "default")
str(layout.default)
## show colour definitions for Abanico plot, only
layout.default$abanico$colour
## set Abanico plot title colour to orange
layout.default$abanico$colour$main <- "orange"
## create Abanico plot with modofied layout definition
plot_AbanicoPlot(data = ExampleData.DeValues,
layout = layout.default)
## create Abanico plot with predefined layout "journal"
plot_AbanicoPlot(data = ExampleData.DeValues,
layout = "journal")

get_Quote

Function to return essential quotes

Description
This function returns one of the collected essential quotes in the growing library. If called without
any parameters, a random quote is returned.
Usage
get_Quote(ID, separated = FALSE)

get_rightAnswer

177

Arguments
ID

character (optional): qoute ID to be returned.

separated

logical (with default): return result in separated form.

Value
Returns a character with quote and respective (false) author.
Function version
0.1.4 (2019-04-19 09:59:27)
How to cite
Dietze, M., Kreutzer, S. (2019). get_Quote(): Function to return essential quotes. Function version
0.1.4. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J.
(2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version
0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Michael Dietze, GFZ Potsdam (Germany), Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060,
CNRS - Université Bordeaux Montaigne (France)
R Luminescence Package Team
Examples
## ask for an arbitrary qoute
get_Quote()

get_rightAnswer

Function to get the right answer

Description
This function returns just the right answer
Usage
get_rightAnswer(...)
Arguments
...

you can pass an infinite number of further arguments

Value
Returns the right answer

178

get_Risoe.BINfileData

Function version
0.1.0 (2018-01-21 17:22:38)
How to cite
NA, NA, , (2019). get_rightAnswer(): Function to get the right answer. Function version 0.1.0. In:
Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019).
Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6.
https://CRAN.R-project.org/package=Luminescence
Author(s)
inspired by R.G.
R Luminescence Package Team
Examples
## you really want to know?
get_rightAnswer()

get_Risoe.BINfileData General accessor function for RLum S4 class objects

Description
Function calls object-specific get functions for RisoeBINfileData S4 class objects.
Usage
get_Risoe.BINfileData(object, ...)
Arguments
object

Risoe.BINfileData (required): S4 object of class RLum

...

further arguments that one might want to pass to the specific get function

Details
The function provides a generalised access point for specific Risoe.BINfileData objects.
Depending on the input object, the corresponding get function will be selected. Allowed arguments
can be found in the documentations of the corresponding Risoe.BINfileData class.
Value
Return is the same as input objects as provided in the list
Function version
0.1.0 (2018-01-21 17:22:38)

get_RLum

179

How to cite
Kreutzer, S. (2019). get_Risoe.BINfileData(): General accessor function for RLum S4 class objects.
Function version 0.1.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
Risoe.BINfileData

get_RLum

General accessor function for RLum S4 class objects

Description
Function calls object-specific get functions for RLum S4 class objects.
Usage
get_RLum(object, ...)
## S4 method for signature 'list'
get_RLum(object, class = NULL, null.rm = FALSE, ...)
## S4 method for signature '`NULL`'
get_RLum(object, ...)
Arguments
object

RLum (required): S4 object of class RLum or an object of type list containing
only objects of type RLum

...

further arguments that will be passed to the object specific methods. For furter
details on the supported arguments please see the class documentation: RLum.Data.Curve,
RLum.Data.Spectrum, RLum.Data.Image, RLum.Analysis and RLum.Results

class

character (optional): allows to define the class that gets selected if applied to a
list, e.g., if a list consists of different type of RLum-class objects, this arguments
allows to make selection. If nothing is provided, all RLum-objects are treated.

null.rm

logical (with default): option to get rid of empty and NULL objects

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

180

GitHub-API

Value
Return is the same as input objects as provided in the list.
Methods (by class)
• list: Returns a list of RLum objects that had been passed to get_RLum
• NULL: Returns NULL
Function version
0.3.3 (2019-02-15 16:35:06)
How to cite
Kreutzer, S. (2019). get_RLum(): General accessor function for RLum S4 class objects. Function version 0.3.3. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
RLum.Data.Curve, RLum.Data.Image, RLum.Data.Spectrum, RLum.Analysis, RLum.Results
Examples
##Example based using data and from the calc_CentralDose() function
##load example data
data(ExampleData.DeValues, envir = environment())
##apply the central dose model 1st time
temp1 <- calc_CentralDose(ExampleData.DeValues$CA1)
##get results and store them in a new object
temp.get <- get_RLum(object = temp1)

GitHub-API

GitHub API

Description
R Interface to the GitHub API v3.

GitHub-API

181

Usage
github_commits(user = "r-lum", repo = "luminescence",
branch = "master", n = 5)
github_branches(user = "r-lum", repo = "luminescence")
github_issues(user = "r-lum", repo = "luminescence", verbose = TRUE)
Arguments
user

character (with default): GitHub user name (defaults to ’r-lum’).

repo

character (with default): name of a GitHub repository (defaults to ’luminescence’).

branch

character (with default): branch of a GitHub repository (defaults to ’master’).

n

integer (with default): number of commits returned (defaults to 5).

verbose

logical (with default): print the output to the console (defaults to TRUE).

Details
These functions can be used to query a specific repository hosted on GitHub.
github_commits lists the most recent n commits of a specific branch of a repository.
github_branches can be used to list all current branches of a repository and returns the corresponding SHA hash as well as an installation command to install the branch in R via the ’devtools’
package.
github_issues lists all open issues for a repository in valid YAML.
Value
github_commits: data.frame with columns:
[ ,1]
[ ,2]
[ ,3]
[ ,4]

SHA
AUTHOR
DATE
MESSAGE

github_branches: data.frame with columns:
[ ,1]
[ ,2]
[ ,3]

BRANCH
SHA
INSTALL

github_commits: Nested list with n elements. Each commit element is a list with elements:
[[1]]
[[2]]
[[3]]
[[4]]

NUMBER
TITLE
BODY
CREATED

182

install_DevelopmentVersion
[[5]]
[[6]]
[[7]]
[[8]]

UPDATED
CREATOR
URL
STATUS

Function version
0.1.0
How to cite
Burow, C. (2019). GitHub-API(): GitHub API. Function version 0.1.0. In: Kreutzer, S., Burow, C.,
Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence
Author(s)
Christoph Burow, University of Cologne (Germany)
R Luminescence Package Team
References
GitHub Developer API v3. https://developer.github.com/v3/, last accessed: 10/01/2017.
Examples
## Not run:
github_branches(user = "r-lum", repo = "luminescence")
github_issues(user = "r-lum", repo = "luminescence")
github_commits(user = "r-lum", repo = "luminescence", branch = "master", n = 10)
## End(Not run)

install_DevelopmentVersion
Attempts to install the development version of the ’Luminescence’
package

Description
This function is a convenient method for installing the development version of the R package ’Luminescence’ directly from GitHub.
Usage
install_DevelopmentVersion(force_install = FALSE)

length_RLum

183

Arguments
force_install

logical (optional): If FALSE (the default) the function produces and prints the
required code to the console for the user to run manually afterwards. When
TRUE and all requirements are fulfilled (see details) this function attempts to
install the package itself.

Details
This function uses Luminescence::github_branches to check which development branches of the R
package ’Luminescence’ are currently available on GitHub. The user is then prompted to choose
one of the branches to be installed. It further checks whether the R package ’devtools’ is currently
installed and available on the system. Finally, it prints R code to the console that the user can copy
and paste to the R console in order to install the desired development version of the package.
If force_install=TRUE the functions checks if ’devtools’ is available and then attempts to install
the chosen development branch via devtools::install_github.
Value
This function requires user input at the command prompt to choose the desired development branch
to be installed. The required R code to install the package is then printed to the console.
Examples
## Not run:
install_DevelopmentVersion()
## End(Not run)

length_RLum

General accessor function for RLum S4 class objects

Description
Function calls object-specific get functions for RLum S4 class objects.
Usage
length_RLum(object)
Arguments
object

RLum (required): S4 object of class RLum

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

184

merge_Risoe.BINfileData

Value
Return is the same as input objects as provided in the list.
Function version
0.1.0 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). length_RLum(): General accessor function for RLum S4 class objects. Function version 0.1.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
RLum.Data.Curve, RLum.Data.Image, RLum.Data.Spectrum, RLum.Analysis, RLum.Results

merge_Risoe.BINfileData
Merge Risoe.BINfileData objects or Risoe BIN-files

Description
Function allows merging Risoe BIN/BINX files or Risoe.BINfileData objects.
Usage
merge_Risoe.BINfileData(input.objects, output.file,
keep.position.number = FALSE, position.number.append.gap = 0)
Arguments
input.objects

output.file

character with Risoe.BINfileData objects (required): Character vector with path
and files names (e.g. input.objects = c("path/file1.bin","path/file2.bin")
or Risoe.BINfileData objects (e.g. input.objects = c(object1,object2)).
Alternatively a list is supported.

character (optional): File output path and name. If no value is given, a Risoe.BINfileData
is returned instead of a file.
keep.position.number
logical (with default): Allows keeping the original position numbers of the input
objects. Otherwise the position numbers are recalculated.
position.number.append.gap
integer (with default): Set the position number gap between merged BIN-file
sets, if the option keep.position.number = FALSE is used. See details for further information.

merge_Risoe.BINfileData

185

Details
The function allows merging different measurements to one file or one object. The record IDs are
recalculated for the new object. Other values are kept for each object. The number of input objects
is not limited.
position.number.append.gap option
If the option keep.position.number = FALSE is used, the position numbers of the new data set
are recalculated by adding the highest position number of the previous data set to the each position
number of the next data set. For example: The highest position number is 48, then this number will
be added to all other position numbers of the next data set (e.g. 1 + 48 = 49)
However, there might be cases where an additional addend (summand) is needed before the next
position starts. Example:
• Position number set (A): 1,3,5,7
• Position number set (B): 1,3,5,7
With no additional summand the new position numbers would be: 1,3,5,7,8,9,10,11. That might
be unwanted. Using the argument position.number.append.gap = 1 it will become: 1,3,5,7,9,11,13,15,17.
Value
Returns a file or a Risoe.BINfileData object.
Function version
0.2.7 (2019-01-15 01:11:37)
How to cite
Kreutzer, S. (2019). merge_Risoe.BINfileData(): Merge Risoe.BINfileData objects or Risoe BINfiles. Function version 0.2.7. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt,
C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data
Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
The validity of the output objects is not further checked.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
References
Duller, G., 2007. Analyst.
See Also
Risoe.BINfileData, read_BIN2R, write_R2BIN

186

merge_RLum

Examples
##merge two objects
data(ExampleData.BINfileData, envir = environment())
object1 <- CWOSL.SAR.Data
object2 <- CWOSL.SAR.Data
object.new <- merge_Risoe.BINfileData(c(object1, object2))

merge_RLum

General merge function for RLum S4 class objects

Description
Function calls object-specific merge functions for RLum S4 class objects.
Usage
merge_RLum(objects, ...)
Arguments
objects

list of RLum (required): list of S4 object of class RLum

...

further arguments that one might want to pass to the specific merge function

Details
The function provides a generalised access point for merge specific RLum objects. Depending on
the input object, the corresponding merge function will be selected. Allowed arguments can be
found in the documentations of each merge function. Empty list elements (NULL) are automatically
removed from the input list.
object
RLum.Data.Curve
RLum.Analysis
RLum.Results

:
:
:

corresponding merge function
merge_RLum.Data.Curve
merge_RLum.Analysis
merge_RLum.Results

Value
Return is the same as input objects as provided in the list.
Function version
0.1.2 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). merge_RLum(): General merge function for RLum S4 class objects. Function version 0.1.2. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,

model_LuminescenceSignals

187

M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
So far not for every RLum object a merging function exists.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
RLum.Data.Curve, RLum.Data.Image, RLum.Data.Spectrum, RLum.Analysis, RLum.Results
Examples

##Example based using data and from the calc_CentralDose() function
##load example data
data(ExampleData.DeValues, envir = environment())
##apply the central dose model 1st time
temp1 <- calc_CentralDose(ExampleData.DeValues$CA1)
##apply the central dose model 2nd time
temp2 <- calc_CentralDose(ExampleData.DeValues$CA1)
##merge the results and store them in a new object
temp.merged <- get_RLum(merge_RLum(objects = list(temp1, temp2)))

model_LuminescenceSignals
Model Luminescence Signals (wrapper)

Description
Wrapper for the function RLumModel::model_LuminescenceSignals from the package RLumModel::RLumModelpackage. For the further details and examples please see the manual of this package.
Usage
model_LuminescenceSignals(model, sequence, lab.dose_rate = 1,
simulate_sample_history = FALSE, plot = TRUE, verbose = TRUE,
show_structure = FALSE, own_parameters = NULL,
own_state_parameters = NULL, own_start_temperature = NULL, ...)

188

model_LuminescenceSignals

Arguments
model

character (required): set model to be used. Available models are: "Bailey2001", "Bailey2002", "Bailey2004", "Pagonis2007", "Pagonis2008", "Friedrich2017",
"Friedrich2018" and for own models "customized" (or "customised"). Note:
When model = "customized" is set, the argument ’own_parameters’ has to be
set.
sequence
list (required): set sequence to model as list or as *.seq file from the Riso
sequence editor. To simulate SAR measurements there is an extra option to set
the sequence list (cf. details).
lab.dose_rate numeric (with default): laboratory dose rate in XXX Gy/s for calculating seconds into Gray in the *.seq file.
simulate_sample_history
logical (with default): FALSE (with default): simulation begins at laboratory
conditions, TRUE: simulations begins at crystallization (all levels 0) process
plot
logical (with default): Enables or disables plot output
verbose
logical (with default): Verbose mode on/off
show_structure logical (with default): Shows the structure of the result. Recommended to
show record.id to analyse concentrations.
own_parameters list (with default): This argument allows the user to submit own parameter
sets. The list has to contain the following items:
• N: Concentration of electron- and hole traps [cm^(-3)]
• E: Electron/Hole trap depth [eV
• s: Frequency factor [s^(-1)]
• A: Conduction band to electron trap and valence band to hole trap transition
probability [s^(-1) * cm^(3)]. CAUTION: Not every publication uses the
same definition of parameter A and B! See vignette "RLumModel Usage with own parameter sets" for further details
• B: Conduction band to hole centre transition probability [s^(-1) * cm^(3)].
• Th: Photo-eviction constant or photoionisation cross section, respectively
• E_th: Thermal assistence energy [eV]
• k_B: Boltzman constant 8.617e-05 [eV/K]
• W: activation energy 0.64 [eV] (for UV)
• K: 2.8e7 (dimensionless constant)
• model: "customized"
• R (optional): Ionisation rate (pair production rate) equivalent to 1 Gy/s [s^(1) * cm^(-3)]
For further details see Bailey 2001, Wintle 1975, vignette "RLumModel - Using
own parameter sets" and example 3.
own_state_parameters
numeric (with default): Some publications (e.g. Pagonis 2009) offer state parameters. With this argument the user can submit this state parameters. For
further details see vignette ""RLumModel - Using own parameter sets" and example 3.
own_start_temperature
numeric (with default): Parameter to control the start temperature (in deg. C)
of a simulation. This parameter takes effect only when ’model = "customized"’
is choosen.
...
further arguments and graphical parameters passed to plot.default. See details for further information.

names_RLum

189

Function version
0.1.3 (2018-01-21 17:22:38)
How to cite
Friedrich, J., Kreutzer, S. (2019). model_LuminescenceSignals(): Model Luminescence Signals
(wrapper). Function version 0.1.3. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt,
C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data
Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Johannes Friedrich, University of Bayreuth (Germany)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaige (France)
R Luminescence Package Team

names_RLum

S4-names function for RLum S4 class objects

Description
Function calls object-specific names functions for RLum S4 class objects.
Usage
names_RLum(object)
## S4 method for signature 'list'
names_RLum(object)
Arguments
object

RLum (required): S4 object of class RLum

Details
The function provides a generalised access point for specific RLum objects.
Depending on the input object, the corresponding ’names’ function will be selected. Allowed arguments can be found in the documentations of the corresponding RLum class.
Value
Returns a character
Methods (by class)
• list: Returns a list of RLum objects that had been passed to names_RLum
Function version
0.1.0 (2018-01-30 16:35:49)

190

plot_AbanicoPlot

How to cite
Kreutzer, S. (2019). names_RLum(): S4-names function for RLum S4 class objects. Function version 0.1.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich,
J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version
0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
RLum.Data.Curve, RLum.Data.Image, RLum.Data.Spectrum, RLum.Analysis, RLum.Results

plot_AbanicoPlot

Function to create an Abanico Plot.

Description
A plot is produced which allows comprehensive presentation of data precision and its dispersion
around a central value as well as illustration of a kernel density estimate, histogram and/or dot plot
of the dose values.
Usage
plot_AbanicoPlot(data, na.rm = TRUE, log.z = TRUE,
z.0 = "mean.weighted", dispersion = "qr", plot.ratio = 0.75,
rotate = FALSE, mtext, summary, summary.pos, summary.method = "MCM",
legend, legend.pos, stats, rug = FALSE, kde = TRUE, hist = FALSE,
dots = FALSE, boxplot = FALSE, y.axis = TRUE, error.bars = FALSE,
bar, bar.col, polygon.col, line, line.col, line.lty, line.label,
grid.col, frame = 1, bw = "SJ", output = TRUE,
interactive = FALSE, ...)
Arguments
data

data.frame or RLum.Results object (required): for data.frame two columns:
De (data[,1]) and De error (data[,2]). To plot several data sets in one plot
the data sets must be provided as list, e.g. list(data.1,data.2).

na.rm

logical (with default): exclude NA values from the data set prior to any further
operations.

log.z

logical (with default): Option to display the z-axis in logarithmic scale. Default
is TRUE.

z.0

character or numeric: User-defined central value, used for centering of data.
One out of "mean", "mean.weighted" and "median" or a numeric value (not
its logarithm). Default is "mean.weighted".

dispersion

character (with default): measure of dispersion, used for drawing the scatter
polygon. One out of

plot_AbanicoPlot

191
•
•
•
•
•

"qr" (quartile range),
"pnn" (symmetric percentile range with nn the lower percentile, e.g.
"p05" depicting the range between 5 and 95
"sd" (standard deviation) and
"2sd" (2 standard deviations),

The default is "qr". Note that "sd" and "2sd" are only meaningful in combination with "z.0 = 'mean'" because the unweighted mean is used to center the
polygon.
plot.ratio

numeric: Relative space, given to the radial versus the cartesian plot part, default
is 0.75.

rotate

logical: Option to turn the plot by 90 degrees.

mtext

character: additional text below the plot title.

summary

character (optional): add statistic measures of centrality and dispersion to the
plot. Can be one or more of several keywords. See details for available keywords. Results differ depending on the log-option for the z-scale (see details).

summary.pos

numeric or character (with default): optional position coordinates or keyword
(e.g. "topright") for the statistical summary. Alternatively, the keyword "sub"
may be specified to place the summary below the plot header. However, this
latter option in only possible if mtext is not used.

summary.method character (with default): keyword indicating the method used to calculate the
statistic summary. One out of
• "unweighted",
• "weighted" and
• "MCM".
See calc_Statistics for details.
legend

character vector (optional): legend content to be added to the plot.

legend.pos

numeric or character (with default): optional position coordinates or keyword
(e.g. "topright") for the legend to be plotted.

stats

character: additional labels of statistically important values in the plot. One or
more out of the following:
• "min",
• "max",
• "median".

rug

logical: Option to add a rug to the KDE part, to indicate the location of individual values.

kde

logical: Option to add a KDE plot to the dispersion part, default is TRUE.

hist

logical: Option to add a histogram to the dispersion part. Only meaningful when
not more than one data set is plotted.

dots

logical: Option to add a dot plot to the dispersion part. If number of dots exceeds
space in the dispersion part, a square indicates this.

boxplot

logical: Option to add a boxplot to the dispersion part, default is FALSE.

y.axis

logical: Option to hide y-axis labels. Useful for data with small scatter.

error.bars

logical: Option to show De-errors as error bars on De-points. Useful in combination with y.axis = FALSE,bar.col = "none".

192

plot_AbanicoPlot
bar

numeric (with default): option to add one or more dispersion bars (i.e., bar showing the 2-sigma range) centered at the defined values. By default a bar is drawn
according to "z.0". To omit the bar set "bar = FALSE".

bar.col

character or numeric (with default): colour of the dispersion bar. Default is
"grey60".

polygon.col

character or numeric (with default): colour of the polygon showing the data
scatter. Sometimes this polygon may be omitted for clarity. To disable it use
FALSE or polygon = FALSE. Default is "grey80".

line

numeric: numeric values of the additional lines to be added.

line.col

character or numeric: colour of the additional lines.

line.lty

integer: line type of additional lines

line.label

character: labels for the additional lines.

grid.col

character or numeric (with default): colour of the grid lines (originating at [0,0]
and strechting to the z-scale). To disable grid lines use FALSE. Default is "grey".

frame

numeric (with default): option to modify the plot frame type. Can be one out of
•
•
•
•

0 (no frame),
1 (frame originates at 0,0 and runs along min/max isochrons),
2 (frame embraces the 2-sigma bar),
3 (frame embraces the entire plot as a rectangle).

Default is 1.
bw

character (with default): bin-width for KDE, choose a numeric value for manual
setting.

output

logical: Optional output of numerical plot parameters. These can be useful to
reproduce similar plots. Default is TRUE.

interactive

logical (with default): create an interactive abanico plot (requires the ’plotly’
package)

...

Further plot arguments to pass. xlab must be a vector of length 2, specifying
the upper and lower x-axes labels.

Details
The Abanico Plot is a combination of the classic Radial Plot (plot_RadialPlot) and a kernel
density estimate plot (e.g plot_KDE). It allows straightforward visualisation of data precision, error
scatter around a user-defined central value and the combined distribution of the values, on the actual
scale of the measured data (e.g. seconds, equivalent dose, years). The principle of the plot is shown
in Galbraith & Green (1990). The function authors are thankful for the thoughtprovocing figure in
this article.
The semi circle (z-axis) of the classic Radial Plot is bent to a straight line here, which actually is the
basis for combining this polar (radial) part of the plot with any other cartesian visualisation method
(KDE, histogram, PDF and so on). Note that the plot allows dispaying two measures of distribution.
One is the 2-sigma bar, which illustrates the spread in value errors, and the other is the polygon,
which stretches over both parts of the Abanico Plot (polar and cartesian) and illustrates the actual
spread in the values themselves.
Since the 2-sigma-bar is a polygon, it can be (and is) filled with shaded lines. To change density
(lines per inch, default is 15) and angle (default is 45 degrees) of the shading lines, specify these
parameters. See ?polygon() for further help.

plot_AbanicoPlot

193

The Abanico Plot supports other than the weighted mean as measure of centrality. When it is
obvious that the data is not (log-)normally distributed, the mean (weighted or not) cannot be a
valid measure of centrality and hence central dose. Accordingly, the median and the weighted
median can be chosen as well to represent a proper measure of centrality (e.g. centrality =
"median.weighted"). Also user-defined numeric values (e.g. from the central age model) can be
used if this appears appropriate.
The proportion of the polar part and the cartesian part of the Abanico Plot can be modfied for display
reasons (plot.ratio = 0.75). By default, the polar part spreads over 75 % and leaves 25 % for the
part that shows the KDE graph.
A statistic summary, i.e. a collection of statistic measures of centrality and dispersion (and further
measures) can be added by specifying one or more of the following keywords:
• "n" (number of samples)
• "mean" (mean De value)
• "median" (median of the De values)
• "sd.rel" (relative standard deviation in percent)
• "sd.abs" (absolute standard deviation)
• "se.rel" (relative standard error)
• "se.abs" (absolute standard error)
• "in.2s" (percent of samples in 2-sigma range)
• "kurtosis" (kurtosis)
• "skewness" (skewness)
Note that the input data for the statistic summary is sent to the function calc_Statistics() depending on the log-option for the z-scale. If "log.z = TRUE", the summary is based on the logarithms of the input data. If "log.z = FALSE" the linearly scaled data is used.
Note as well, that "calc_Statistics()" calculates these statistic measures in three different ways:
unweighted, weighted and MCM-based (i.e., based on Monte Carlo Methods). By default, the
MCM-based version is used. If you wish to use another method, indicate this with the appropriate
keyword using the argument summary.method.
The optional parameter layout allows to modify the entire plot more sophisticated. Each element
of the plot can be addressed and its properties can be defined. This includes font type, size and
decoration, colours and sizes of all plot items. To infer the definition of a specific layout style cf.
get_Layout() or type eg. for the layout type "journal" get_Layout("journal"). A layout type
can be modified by the user by assigning new values to the list object.
It is possible for the z-scale to specify where ticks are to be drawn by using the parameter at, e.g.
at = seq(80,200,20), cf. function documentation of axis. Specifying tick positions manually
overrides a zlim-definition.
Value
returns a plot object and, optionally, a list with plot calculus data.
Function version
0.1.10 (2018-02-28 22:48:58)

194

plot_AbanicoPlot

How to cite
Dietze, M., Kreutzer, S. (2019). plot_AbanicoPlot(): Function to create an Abanico Plot.. Function version 0.1.10. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Michael Dietze, GFZ Potsdam (Germany)
Sebastian Kreutzer, RAMAT-CRP2A, Universite Bordeaux Montaigne (France)
Inspired by a plot introduced by Galbraith & Green (1990)
R Luminescence Package Team
References
Galbraith, R. & Green, P., 1990. Estimating the component ages in a finite mixture. International
Journal of Radiation Applications and Instrumentation. Part D. Nuclear Tracks and Radiation Measurements, 17 (3), 197-206.
Dietze, M., Kreutzer, S., Burow, C., Fuchs, M.C., Fischer, M., Schmidt, C., 2015. The abanico
plot: visualising chronometric data with individual standard errors. Quaternary Geochronology.
doi:10.1016/j.quageo.2015.09.003
See Also
plot_RadialPlot, plot_KDE, plot_Histogram
Examples
## load example data and recalculate to Gray
data(ExampleData.DeValues, envir = environment())
ExampleData.DeValues <- ExampleData.DeValues$CA1
## plot the example data straightforward
plot_AbanicoPlot(data = ExampleData.DeValues)
## now with linear z-scale
plot_AbanicoPlot(data = ExampleData.DeValues,
log.z = FALSE)
## now with output of the plot parameters
plot1 <- plot_AbanicoPlot(data = ExampleData.DeValues,
output = TRUE)
str(plot1)
plot1$zlim
## now with adjusted z-scale limits
plot_AbanicoPlot(data = ExampleData.DeValues,
zlim = c(10, 200))
## now with adjusted x-scale limits
plot_AbanicoPlot(data = ExampleData.DeValues,
xlim = c(0, 20))
## now with rug to indicate individual values in KDE part

plot_AbanicoPlot
plot_AbanicoPlot(data = ExampleData.DeValues,
rug = TRUE)
## now with a smaller bandwidth for the KDE plot
plot_AbanicoPlot(data = ExampleData.DeValues,
bw = 0.04)
## now with a histogram instead of the KDE plot
plot_AbanicoPlot(data = ExampleData.DeValues,
hist = TRUE,
kde = FALSE)
## now with a KDE plot and histogram with manual number of bins
plot_AbanicoPlot(data = ExampleData.DeValues,
hist = TRUE,
breaks = 20)
## now with a KDE plot and a dot plot
plot_AbanicoPlot(data = ExampleData.DeValues,
dots = TRUE)
## now with user-defined plot ratio
plot_AbanicoPlot(data = ExampleData.DeValues,
plot.ratio = 0.5)
## now with user-defined central value
plot_AbanicoPlot(data = ExampleData.DeValues,
z.0 = 70)
## now with median as central value
plot_AbanicoPlot(data = ExampleData.DeValues,
z.0 = "median")
## now with the 17-83 percentile range as definition of scatter
plot_AbanicoPlot(data = ExampleData.DeValues,
z.0 = "median",
dispersion = "p17")
## now with user-defined green line for minimum age model
CAM <- calc_CentralDose(ExampleData.DeValues,
plot = FALSE)
plot_AbanicoPlot(data = ExampleData.DeValues,
line = CAM,
line.col = "darkgreen",
line.label = "CAM")
## now create plot with legend, colour, different points and smaller scale
plot_AbanicoPlot(data = ExampleData.DeValues,
legend = "Sample 1",
col = "tomato4",
bar.col = "peachpuff",
pch = "R",
cex = 0.8)
## now without 2-sigma bar, polygon, grid lines and central value line
plot_AbanicoPlot(data = ExampleData.DeValues,
bar.col = FALSE,

195

196

plot_AbanicoPlot
polygon.col = FALSE,
grid.col = FALSE,
y.axis = FALSE,
lwd = 0)
## now with direct display of De errors, without 2-sigma bar
plot_AbanicoPlot(data = ExampleData.DeValues,
bar.col = FALSE,
ylab = "",
y.axis = FALSE,
error.bars = TRUE)
## now with user-defined axes labels
plot_AbanicoPlot(data = ExampleData.DeValues,
xlab = c("Data error (%)",
"Data precision"),
ylab = "Scatter",
zlab = "Equivalent dose [Gy]")
## now with minimum, maximum and median value indicated
plot_AbanicoPlot(data = ExampleData.DeValues,
stats = c("min", "max", "median"))
## now with a brief statistical summary as subheader
plot_AbanicoPlot(data = ExampleData.DeValues,
summary = c("n", "in.2s"))
## now with another statistical summary
plot_AbanicoPlot(data = ExampleData.DeValues,
summary = c("mean.weighted", "median"),
summary.pos = "topleft")
## now a plot with two 2-sigma bars for one data set
plot_AbanicoPlot(data = ExampleData.DeValues,
bar = c(30, 100))
## now the data set is split into sub-groups, one is manipulated
data.1 <- ExampleData.DeValues[1:30,]
data.2 <- ExampleData.DeValues[31:62,] * 1.3
## now a common dataset is created from the two subgroups
data.3 <- list(data.1, data.2)
## now the two data sets are plotted in one plot
plot_AbanicoPlot(data = data.3)
## now with some graphical modification
plot_AbanicoPlot(data = data.3,
z.0 = "median",
col = c("steelblue4", "orange4"),
bar.col = c("steelblue3", "orange3"),
polygon.col = c("steelblue1", "orange1"),
pch = c(2, 6),
angle = c(30, 50),
summary = c("n", "in.2s", "median"))
## create Abanico plot with predefined layout definition

plot_DetPlot

197

plot_AbanicoPlot(data = ExampleData.DeValues,
layout = "journal")
## now with predefined layout definition and further modifications
plot_AbanicoPlot(data = data.3,
z.0 = "median",
layout = "journal",
col = c("steelblue4", "orange4"),
bar.col = adjustcolor(c("steelblue3", "orange3"),
alpha.f = 0.5),
polygon.col = c("steelblue3", "orange3"))
## for further information on layout definitions see documentation
## of function get_Layout()
## now with manually added plot content
## create empty plot with numeric output
AP <- plot_AbanicoPlot(data = ExampleData.DeValues,
pch = NA,
output = TRUE)
## identify data in 2 sigma range
in_2sigma <- AP$data[[1]]$data.in.2s
## restore function-internal plot parameters
par(AP$par)
## add points inside 2-sigma range
points(x = AP$data[[1]]$precision[in_2sigma],
y = AP$data[[1]]$std.estimate.plot[in_2sigma],
pch = 16)
## add points outside 2-sigma range
points(x = AP$data[[1]]$precision[!in_2sigma],
y = AP$data[[1]]$std.estimate.plot[!in_2sigma],
pch = 1)

plot_DetPlot

Create De(t) plot

Description
Plots the equivalent dose (De) in dependency of the chosen signal integral (cf. Bailey et al., 2003).
The function is simply passing several arguments to the function plot and the used analysis functions
and runs it in a loop. Example: legend.pos for legend position, legend for legend text.
Usage
plot_DetPlot(object, signal.integral.min, signal.integral.max,
background.integral.min, background.integral.max, method = "shift",
signal_integral.seq = NULL, analyse_function = "analyse_SAR.CWOSL",
analyse_function.control = list(), n.channels = NULL,
show_ShineDownCurve = TRUE, respect_RC.Status = FALSE,
verbose = TRUE, ...)

198

plot_DetPlot

Arguments
object
RLum.Analysis (required): input object containing data for analysis
signal.integral.min
integer (required): lower bound of the signal integral.
signal.integral.max
integer (required): upper bound of the signal integral.
background.integral.min
integer (required): lower bound of the background integral.
background.integral.max
integer (required): upper bound of the background integral.
method
character (with default): method applied for constructing the De(t) plot.
• shift (the default): the chosen signal integral is shifted the shine down
curve,
• expansion: the chosen signal integral is expanded each time by its length
signal_integral.seq
numeric (optional): argument to provide an own signal integral sequence for
constructing the De(t) plot
analyse_function
character (with default): name of the analyse function to be called. Supported
functions are: 'analyse_SAR.CWOSL', 'analyse_pIRIRSequence'
analyse_function.control
list (optional): arguments to be passed to the supported analyse functions ('analyse_SAR.CWOSL',
'analyse_pIRIRSequence')
n.channels
integer (optional): number of channels used for the De(t) plot. If nothing is provided all De-values are calculated and plotted until the start of the background
integral.
show_ShineDownCurve
logical (with default): enables or disables shine down curve in the plot output
respect_RC.Status
logical (with default): remove De-values with ’FAILED’ RC.Status from the
plot (cf. analyse_SAR.CWOSL and analyse_pIRIRSequence)
verbose
logical (with default): enables or disables terminal feedback
...
further arguments and graphical parameters passed to plot.default, analyse_SAR.CWOSL
and analyse_pIRIRSequence. See details for further information.
Details
method
The original method presented by Baiely et al., 2003 shifted the signal integrals and slightly extended them accounting for changes in the counting statistics. Example: c(1:3,3:5,5:7). However, here also another method is provided allowing to expand the signal integral by consectutively
expaning the integral by its chosen length. Example: c(1:3,1:5,1:7)
Note that in both cases the integral limits are overlap. The finally applied limits are part of the
function output.
Value
A plot and an RLum.Results object with the produced De values
@data:

plot_DetPlot

199

Object
De.values
signal_integral.seq

Type
data.frame
numeric

Description
table with De values
integral sequence used for the calculation

@info:
Object
call

Type
call

Description
the original function call

Function version
0.1.2 (2018-08-27 10:58:24)
How to cite
Kreutzer, S. (2019). plot_DetPlot(): Create De(t) plot. Function version 0.1.2. In: Kreutzer, S.,
Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence:
Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence
Note
The entire analysis is based on the used analysis functions, namely analyse_SAR.CWOSL and
analyse_pIRIRSequence. However, the integrity checks of this function are not that thoughtful as
in these functions itself. It means, that every sequence should be checked carefully before running
long calculations using serveral hundreds of channels.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France)
R Luminescence Package Team
References
Bailey, R.M., Singarayer, J.S., Ward, S., Stokes, S., 2003. Identification of partial resetting using
De as a function of illumination time. Radiation Measurements 37, 511-518. doi:10.1016/S13504487(03)00063-5
See Also
plot, analyse_SAR.CWOSL, analyse_pIRIRSequence
Examples
## Not run:
##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)

200

plot_DRCSummary
plot_DetPlot(object,
signal.integral.min = 1,
signal.integral.max = 3,
background.integral.min = 900,
background.integral.max = 1000,
n.channels = 5,
)
## End(Not run)

plot_DRCSummary

Create a Dose-Response Curve Summary Plot

Description
While analysing OSL SAR or pIRIR data the view on the data is limited usually to one doseresponse curve (DRC) at the time for one aliquot. This function overcomes this limitation by plotting all DRC from an RLum.Results object created by the function analyse_SAR.CWOSL in one
single plot.
Usage
plot_DRCSummary(object, source_dose_rate = NULL, sel_curves = NULL,
show_dose_points = FALSE, show_natural = FALSE, n = 51L, ...)
Arguments
object

RLum.Results object (required): input object created by the function analyse_SAR.CWOSL. The input object can be provided as list.

source_dose_rate
numeric (optional): allows to modify the axis and show values in Gy, instead
seconds. Only a single numerical values is allowed.
sel_curves

numeric (optional): id of the curves to be plotting in its occuring order. A sequence can be provided for selecting, e.g., only every 2nd curve from the input
object

show_dose_points
logical (with default): enable or disable plot of dose points in the graph
show_natural

logical (with default): enable or disable the plot of the natural Lx/Tx values

n

integer (with default): the number of x-values used to evaluate one curve object.
Large numbers slow down the plotting process and are usually not needed

...

Further arguments and graphical parameters to be passed.

Details
If you want plot your DRC on an energy scale (dose in Gy), you can either use the option source_dose_rate
provided below or your can SAR analysis with the dose points in Gy (better axis scaling).

plot_DRCSummary
Value
An RLum.Results object is returned:
Slot: @data

201

202

plot_DRCSummary
OBJECT
results
data

TYPE
data.frame
RLum.Results

COMMENT
with dose and LxTx values
original input data

Slot: @info
OBJECT
call
args

TYPE
call
list

COMMENT
the original function call
arguments of the original function call

Note: If the input object is a list a list of RLum.Results objects is returned.
Function version
0.2.1 (2019-03-05 11:53:10)
How to cite
Kreutzer, S., Burow, C. (2019). plot_DRCSummary(): Create a Dose-Response Curve Summary
Plot. Function version 0.2.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt,
C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data
Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Université Bordeaux Montaigne (France)
Christoph Burow, University of Cologne
R Luminescence Package Team
See Also
RLum.Results, analyse_SAR.CWOSL
Examples
#load data example 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)
results <- analyse_SAR.CWOSL(
object = object,
signal.integral.min = 1,
signal.integral.max = 2,
background.integral.min = 900,
background.integral.max = 1000,
plot = FALSE
)

plot_DRTResults

203

##plot only DRC
plot_DRCSummary(results)

plot_DRTResults

Visualise dose recovery test results

Description
The function provides a standardised plot output for dose recovery test measurements.
Usage
plot_DRTResults(values, given.dose = NULL, error.range = 10, preheat,
boxplot = FALSE, mtext, summary, summary.pos, legend, legend.pos,
par.local = TRUE, na.rm = FALSE, ...)
Arguments
values

RLum.Results or data.frame (required): input values containing at least De and
De error. To plot more than one data set in one figure, a list of the individual
data sets must be provided (e.g. list(dataset.1,dataset.2)).

given.dose

numeric (optional): given dose used for the dose recovery test to normalise data.
If only one given dose is provided this given dose is valid for all input data sets
(i.e., values is a list). Oherwise a given dose for each input data set has to be
provided (e.g., given.dose = c(100,200)). If given.dose in NULL the values
are plotted without normalisation (might be useful for preheat plateau tests).
Note: Unit has to be the same as from the input values (e.g., Seconds or Gray).

error.range

numeric: symmetric error range in percent will be shown as dashed lines in the
plot. Set error.range to 0 to void plotting of error ranges.

preheat

numeric: optional vector of preheat temperatures to be used for grouping the De
values. If specified, the temperatures are assigned to the x-axis.

boxplot

logical: optionally plot values, that are grouped by preheat temperature as boxplots. Only possible when preheat vector is specified.

mtext

character: additional text below the plot title.

summary

character (optional): adds numerical output to the plot. Can be one or more out
of:
•
•
•
•
•
•
•
•

"n" (number of samples),
"mean" (mean De value),
"weighted$mean" (error-weighted mean),
"median" (median of the De values),
"sd.rel" (relative standard deviation in percent),
"sd.abs" (absolute standard deviation),
"se.rel" (relative standard error) and
"se.abs" (absolute standard error)

and all other measures returned by the function calc_Statistics.

204

plot_DRTResults
summary.pos

numeric or character (with default): optional position coordinates or keyword
(e.g. "topright") for the statistical summary. Alternatively, the keyword "sub"
may be specified to place the summary below the plot header. However, this
latter option in only possible if mtext is not used.

legend

character vector (optional): legend content to be added to the plot.

legend.pos

numeric or character (with default): optional position coordinates or keyword
(e.g. "topright") for the legend to be plotted.

par.local

logical (with default): use local graphical parameters for plotting, e.g. the plot
is shown in one column and one row. If par.local = FALSE, global parameters
are inherited, i.e. parameters provided via par() work

na.rm

logical: indicating wether NA values are removed before plotting from the input
data set

...

further arguments and graphical parameters passed to plot.

Details
Procedure to test the accuracy of a measurement protocol to reliably determine the dose of a specific
sample. Here, the natural signal is erased and a known laboratory dose administered which is
treated as unknown. Then the De measurement is carried out and the degree of congruence between
administered and recovered dose is a measure of the protocol’s accuracy for this sample.
In the plot the normalised De is shown on the y-axis, i.e. obtained De/Given Dose.
Value
A plot is returned.
Function version
0.1.12 (2018-02-23 22:32:54)
How to cite
Kreutzer, S., Dietze, M. (2019). plot_DRTResults(): Visualise dose recovery test results. Function version 0.1.12. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
Further data and plot arguments can be added by using the appropriate R commands.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Université Bordeaux Montaigne (France)
Michael Dietze, GFZ Potsdam (Germany)
R Luminescence Package Team
References
Wintle, A.G., Murray, A.S., 2006. A review of quartz optically stimulated luminescence characteristics and their relevance in single-aliquot regeneration dating protocols. Radiation Measurements,
41, 369-391.

plot_DRTResults
See Also
plot
Examples
## read example data set and misapply them for this plot type
data(ExampleData.DeValues, envir = environment())
## plot values
plot_DRTResults(values = ExampleData.DeValues$BT998[7:11,],
given.dose = 2800, mtext = "Example data")
## plot values with legend
plot_DRTResults(values = ExampleData.DeValues$BT998[7:11,],
given.dose = 2800,
legend = "Test data set")
## create and plot two subsets with randomised values
x.1 <- ExampleData.DeValues$BT998[7:11,]
x.2 <- ExampleData.DeValues$BT998[7:11,] * c(runif(5, 0.9, 1.1), 1)
plot_DRTResults(values = list(x.1, x.2),
given.dose = 2800)
## some more user-defined plot parameters
plot_DRTResults(values = list(x.1, x.2),
given.dose = 2800,
pch = c(2, 5),
col = c("orange", "blue"),
xlim = c(0, 8),
ylim = c(0.85, 1.15),
xlab = "Sample aliquot")
## plot the data with user-defined statistical measures as legend
plot_DRTResults(values = list(x.1, x.2),
given.dose = 2800,
summary = c("n", "mean.weighted", "sd"))
## plot the data with user-defined statistical measures as sub-header
plot_DRTResults(values = list(x.1, x.2),
given.dose = 2800,
summary = c("n", "mean.weighted", "sd"),
summary.pos = "sub")
## plot the data grouped by preheat temperatures
plot_DRTResults(values = ExampleData.DeValues$BT998[7:11,],
given.dose = 2800,
preheat = c(200, 200, 200, 240, 240))
## read example data set and misapply them for this plot type
data(ExampleData.DeValues, envir = environment())
## plot values
plot_DRTResults(values = ExampleData.DeValues$BT998[7:11,],
given.dose = 2800, mtext = "Example data")
## plot two data sets grouped by preheat temperatures

205

206

plot_FilterCombinations
plot_DRTResults(values = list(x.1, x.2),
given.dose = 2800,
preheat = c(200, 200, 200, 240, 240))
## plot the data grouped by preheat temperatures as boxplots
plot_DRTResults(values = ExampleData.DeValues$BT998[7:11,],
given.dose = 2800,
preheat = c(200, 200, 200, 240, 240),
boxplot = TRUE)

plot_FilterCombinations
Plot filter combinations along with the (optional) net transmission
window

Description
The function allows to plot transmission windows for different filters. Missing data for specific
wavelenghts are automatically interpolated for the given filter data using the function approx. With
that a standardised output is reached and a net transmission window can be shown.
Usage
plot_FilterCombinations(filters, wavelength_range = 200:1000,
show_net_transmission = TRUE, interactive = FALSE, plot = TRUE,
...)
Arguments
filters

list (required): a named list of filter data for each filter to be shown. The filter
data itself should be either provided as data.frame or matrix. (for more options
s. Details)
wavelength_range
numeric (with default): wavelength range used for the interpolation
show_net_transmission
logical (with default): show net transmission window as polygon.
interactive

logical (with default): enable/disable interactive plot

plot

logical (with default): enables or disables the plot output

...

further arguments that can be passed to control the plot output. Suppored are
main, xlab, ylab, xlim, ylim, type, lty, lwd. For non common plotting parameters see the details section.

Details
Calculations
Net transmission window
The net transmission window of two filters is approximated by
Tf inal = T1 ∗ T2

plot_FilterCombinations

207

Optical density
OD = −log(T )
Total optical density
ODtotal = OD1 + OD2
Please consider using own calculations for more precise values.
How to provide input data?
CASE 1
The function expects that all filter values are either of type matrix or data.frame with two
columns. The first columens contains the wavelength, the second the relative transmission (but
not in percentage, i.e. the maximum transmission can be only become 1).
In this case only the transmission window is show as provided. Changes in filter thickness and
relection factor are not considered.
CASE 2
The filter data itself are provided as list element containing a matrix or data.frame and additional
information on the thickness of the filter, e.g., list(filter1 = list(filter_matrix,d = 2)).
The given filter data are always considered as standard input and the filter thickness value is taken
into account by
T ransmission = T ransmission( d)
with d given in the same dimension as the original filter data.
CASE 3
Same as CASE 2 but additionally a reflection factor P is provided, e.g., list(filter1 = list(filter_matrix,d
= 2,P = 0.9)). The final transmission becomes:
T ransmission = T ransmission( d) ∗ P
Advanced plotting parameters
The following further non-common plotting parameters can be passed to the function:
Argument
legend
legend.pos
legend.text
net_transmission.col
net_transmission.col_lines
net_transmission.density
grid

Datatype
logical
character
character
col
col
numeric
list

Description
enable/disable legend
change legend position (graphics::legend)
same as the argument legend in (graphics::legend)
colour of net transmission window polygon
colour of net transmission window polygon lines
specify line density in the transmission polygon
full list of arguments that can be passd to the function graphics::grid

For further modifications standard additional R plot functions are recommend, e.g., the legend can
be fully customised by disabling the standard legend and use the function graphics::legend instead.

208

plot_FilterCombinations

Value
Returns an S4 object of type RLum.Results.
@data
Object
net_transmission_window
OD_total
filter_matrix

Type Description
matrix
matrix
matrix

the resulting net transmission window
the total optical density
the filter matrix used for plotting

@info
Object
call

Type Description
call

the original function call

Function version
0.3.1 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). plot_FilterCombinations(): Plot filter combinations along with the (optional)
net transmission window. Function version 0.3.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs,
M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence
Dating Data Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montagine (France)
R Luminescence Package Team
See Also
RLum.Results, approx
Examples
## (For legal reasons no real filter data are provided)
## Create filter sets
filter1 <- density(rnorm(100, mean = 450, sd = 20))
filter1 <- matrix(c(filter1$x, filter1$y/max(filter1$y)), ncol = 2)
filter2 <- matrix(c(200:799,rep(c(0,0.8,0),each = 200)), ncol = 2)
## Example 1 (standard)
plot_FilterCombinations(filters = list(filter1, filter2))
## Example 2 (with d and P value and name for filter 2)
results <- plot_FilterCombinations(
filters = list(filter_1 = filter1, Rectangle = list(filter2, d = 2, P = 0.6)))
results
## Example 3 show optical density
plot(results$OD_total)

plot_GrowthCurve

209

## Not run:
##Example 4
##show the filters using the interactive mode
plot_FilterCombinations(filters = list(filter1, filter2), interactive = TRUE)
## End(Not run)

plot_GrowthCurve

Fit and plot a growth curve for luminescence data (Lx/Tx against dose)

Description
A dose response curve is produced for luminescence measurements using a regenerative or additive
protocol. The function supports interpolation and extraxpolation to calculate the equivalent dose.
Usage
plot_GrowthCurve(sample, na.rm = TRUE, mode = "interpolation",
fit.method = "EXP", fit.force_through_origin = FALSE,
fit.weights = TRUE, fit.includingRepeatedRegPoints = TRUE,
fit.NumberRegPoints = NULL, fit.NumberRegPointsReal = NULL,
fit.bounds = TRUE, NumberIterations.MC = 100, output.plot = TRUE,
output.plotExtended = TRUE, output.plotExtended.single = FALSE,
cex.global = 1, txtProgressBar = TRUE, verbose = TRUE, ...)
Arguments
sample

data.frame (required): data frame with three columns for x=Dose,y=LxTx,z=LxTx.Error,
y1=TnTx. The column for the test dose response is optional, but requires ’TnTx’
as column name if used. For exponential fits at least three dose points (including
the natural) should be provided.

na.rm

logical (with default): excludes NA values from the data set prior to any further
operations.

mode

character (with default): selects calculation mode of the function.
• "interpolation" (default) calculates the De by interpolation,
• "extrapolation" calculates the De by extrapolation and
• "alternate" calculates no De and just fits the data points.
Please note that for option "regenrative" the first point is considered as natural
dose

fit.method

character (with default): function used for fitting. Possible options are:
•
•
•
•
•

LIN,
QDR,
EXP,
EXP OR LIN,
EXP+LIN,

210

plot_GrowthCurve
• EXP+EXP or
• GOK.
See details.
fit.force_through_origin
logical (with default) allow to force the fitted function through the origin. For
method = "EXP+EXP" and method = "GOK" the function will go through the origin in either case, so this option will have no effect.
fit.weights

logical (with default): option whether the fitting is done with or without weights.
See details.
fit.includingRepeatedRegPoints
logical (with default): includes repeated points for fitting (TRUE/FALSE).
fit.NumberRegPoints
integer (optional): set number of regeneration points manually. By default the
number of all (!) regeneration points is used automatically.
fit.NumberRegPointsReal
integer (optional): if the number of regeneration points is provided manually,
the value of the real, regeneration points = all points (repeated points) including
reg 0, has to be inserted.
fit.bounds

logical (with default): set lower fit bounds for all fitting parameters to 0. Limited
for the use with the fit methods EXP, EXP+LIN, EXP OR LIN and GOK. Argument
to be inserted for experimental application only!
NumberIterations.MC
integer (with default): number of Monte Carlo simulations for error estimation.
See details.
output.plot
logical (with default): plot output (TRUE/FALSE).
output.plotExtended
logical (with default): If’ TRUE, 3 plots on one plot area are provided:
1. growth curve,
2. histogram from Monte Carlo error simulation and
3. a test dose response plot.
If FALSE, just the growth curve will be plotted. Requires: output.plot = TRUE.
output.plotExtended.single
logical (with default): single plot output (TRUE/FALSE) to allow for plotting the
results in single plot windows. Requires output.plot = TRUE and output.plotExtended
= TRUE.
cex.global

numeric (with default): global scaling factor.

txtProgressBar logical (with default): enables or disables txtProgressBar. If verbose = FALSE
also no txtProgressBar is shown.
verbose

logical (with default): enables or disables terminal feedback.

...

Further arguments and graphical parameters to be passed. Note: Standard arguments will only be passed to the growth curve plot. Supported: xlim, ylim,
main, xlab, ylab

Details
Fitting methods
For all options (except for the LIN, QDR and the EXP OR LIN), the minpack.lm::nlsLM function with
the LM (Levenberg-Marquardt algorithm) algorithm is used. Note: For historical reasons for the
Monte Carlo simulations partly the function nls using the port algorithm.

plot_GrowthCurve

211

The solution is found by transforming the function or using uniroot.
LIN: fits a linear function to the data using lm:
y =m∗x+n
QDR: fits a linear function to the data using lm:
y = a + b ∗ x + c ∗ x2
EXP: try to fit a function of the form
y = a ∗ (1 − exp(−(x + c)/b))
Parameters b and c are approximated by a linear fit using lm. Note: b = D0
EXP OR LIN: works for some cases where an EXP fit fails. If the EXP fit fails, a LIN fit is done instead.
EXP+LIN: tries to fit an exponential plus linear function of the form:
y = a ∗ (1 − exp(−(x + c)/b) + (g ∗ x))
The De is calculated by iteration.
Note: In the context of luminescence dating, this function has no physical meaning. Therefore, no
D0 value is returned.
EXP+EXP: tries to fit a double exponential function of the form
y = (a1 ∗ (1 − exp(−(x)/b1))) + (a2 ∗ (1 − exp(−(x)/b2)))
This fitting procedure is not robust against wrong start parameters and should be further improved.
GOK: tries to fit the general-order kinetics function after Guralnik et al. (2015) of the form of
y = a ∗ (1 − (1 + (1/b) ∗ x ∗ c)( − 1/c))
where c > 0 is a kinetic order modifier (not to be confused with c in EXP or EXP+LIN!).
Fit weighting
If the option fit.weights = TRUE is chosen, weights are calculated using provided signal errors
(Lx/Tx error):
f it.weights = 1/error/(sum(1/error))
Error estimation using Monte Carlo simulation
Error estimation is done using a Monte Carlo (MC) simulation approach. A set of Lx/Tx values is
constructed by randomly drawing curve data from samled from normal distributions. The normal
distribution is defined by the input values (mean = value, sd = value.error). Then, a growth curve
fit is attempted for each dataset resulting in a new distribution of single De values. The sd of this
distribution is becomes then the error of the De. With increasing iterations, the error value becomes
more stable. Note: It may take some calculation time with increasing MC runs, especially for the
composed functions (EXP+LIN and EXP+EXP).
Each error estimation is done with the function of the chosen fitting method.
Subtitle information
To avoid plotting the subtitle information, provide an empty user mtext mtext = "". To plot any
other subtitle text, use mtext.
Value
Along with a plot (so far wanted) an RLum.Results object is returned containing, the slot data
contains the following elements:

212

plot_GrowthCurve

DATA.OBJECT
..$De :
..$De.MC :
..$Fit :
..$Formula :
..$call :

TYPE
data.frame
numeric
nls or lm
expression
call

DESCRIPTION
Table with De values
Table with De values from MC runs
object from the fitting for EXP, EXP+LIN and EXP+EXP. In case of a resulting linear fit wh
Fitting formula as R expression
The original function call

Function version
1.10.6 (2019-01-28 15:51:51)
How to cite
Kreutzer, S., Dietze, M. (2019). plot_GrowthCurve(): Fit and plot a growth curve for luminescence data (Lx/Tx against dose). Function version 1.10.6. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France)
Michael Dietze, GFZ Potsdam (Germany)
R Luminescence Package Team
References
Berger, G.W., Huntley, D.J., 1989. Test data for exponential fits. Ancient TL 7, 43-46.
Guralnik, B., Li, B., Jain, M., Chen, R., Paris, R.B., Murray, A.S., Li, S.-H., Pagonis, P., Herman,
F., 2015. Radiation-induced growth and isothermal decay of infrared-stimulated luminescence from
feldspar. Radiation Measurements 81, 224-231.
See Also
nls, RLum.Results, get_RLum, minpack.lm::nlsLM, lm, uniroot
Examples
##(1) plot growth curve for a dummy data.set and show De value
data(ExampleData.LxTxData, envir = environment())
temp <- plot_GrowthCurve(LxTxData)
get_RLum(temp)
##(1a) to access the fitting value try
get_RLum(temp, data.object = "Fit")
##(2) plot the growth curve only - uncomment to use
##pdf(file = "~/Desktop/Growth_Curve_Dummy.pdf", paper = "special")
plot_GrowthCurve(LxTxData)
##dev.off()
##(3) plot growth curve with pdf output - uncomment to use, single output
##pdf(file = "~/Desktop/Growth_Curve_Dummy.pdf", paper = "special")

plot_GrowthCurve
plot_GrowthCurve(LxTxData, output.plotExtended.single = TRUE)
##dev.off()
##(4) plot resulting function for given intervall x
x <- seq(1,10000, by = 100)
plot(
x = x,
y = eval(temp$Formula),
type = "l"
)
##(5) plot using the 'extrapolation' mode
LxTxData[1,2:3] <- c(0.5, 0.001)
print(plot_GrowthCurve(LxTxData,mode = "extrapolation"))
##(6) plot using the 'alternate' mode
LxTxData[1,2:3] <- c(0.5, 0.001)
print(plot_GrowthCurve(LxTxData,mode = "alternate"))
##(7) import and fit test data set by Berger & Huntley 1989
QNL84_2_unbleached  ca. 200 MByte
and thus plotting of such data is extremely slow.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
RLum.Data.Image, plot, plot_RLum, raster::raster
Examples
##load data
data(ExampleData.RLum.Data.Image, envir = environment())
##plot data
plot_RLum.Data.Image(ExampleData.RLum.Data.Image)

plot_RLum.Data.Spectrum
Plot function for an RLum.Data.Spectrum S4 class object

Description
The function provides a standardised plot output for spectrum data of an RLum.Data.Spectrum S4
class object

236

plot_RLum.Data.Spectrum

Usage
plot_RLum.Data.Spectrum(object, par.local = TRUE,
plot.type = "contour", optical.wavelength.colours = TRUE,
bg.spectrum = NULL, bg.channels = NULL, bin.rows = 1,
bin.cols = 1, norm = NULL, rug = TRUE, limit_counts = NULL,
xaxis.energy = FALSE, legend.text, ...)
Arguments
object

RLum.Data.Spectrum or matrix (required): S4 object of class RLum.Data.Spectrum
or a matrix containing count values of the spectrum.
Please note that in case of a matrix rownames and colnames are set automatically
if not provided.

par.local

logical (with default): use local graphical parameters for plotting, e.g. the plot
is shown in one column and one row. If par.local = FALSE global parameters
are inherited.

plot.type

character (with default): plot type, for 3D-plot use persp, or interactive, for
a 2D-plot contour, single or multiple.lines (along the time or temperature
axis) or transect (along the wavelength axis)

optical.wavelength.colours
logical (with default): use optical wavelength colour palette. Note: For this,
the spectrum range is limited: c(350,750). Own colours can be set with the
argument col. If you provide already binned spectra, the colour assignment
is likely to be wrong, since the colour gradients are calculated using the bin
number.
bg.spectrum

RLum.Data.Spectrum or matrix (optional): Spectrum used for the background
subtraction. By definition, the background spectrum should have been measured
with the same setting as the signal spectrum. If a spectrum is provided, the
argument bg.channels works only on the provided background spectrum.

bg.channels

vector (optional): defines channel for background subtraction If a vector is provided the mean of the channels is used for subtraction. If a spectrum is provided
via bg.spectrum, this argument only works on the bg.spectrum.
Note: Background subtraction is applied prior to channel binning

bin.rows

integer (with default): allow summing-up wavelength channels (horizontal binning), e.g. bin.rows = 2 two channels are summed up. Binning is applied after
the background subtraction.

bin.cols

integer (with default): allow summing-up channel counts (vertical binning) for
plotting, e.g. bin.cols = 2 two channels are summed up. Binning is applied
after the background subtraction.

norm

character (optional): Normalise data to the maximum (norm = "max") or minimum (norm = "min") count values. The normalisation is applied after the binning.

rug

logical (with default): enables or disables colour rug. Currently only implemented for plot type multiple.lines and single

limit_counts

numeric (optional): value to limit all count values to this value, i.e. all count
values above this threshold will be replaced by this threshold. This is helpful
especially in case of TL-spectra.

plot_RLum.Data.Spectrum
xaxis.energy

legend.text
...

237

logical (with default): enables or disables energy instead of wavelength axis.
For the conversion the function convert_Wavelength2Energy is used.
Note: This option means not only simnply redrawing the axis, instead the spectrum in terms of intensity is recalculated, s. details.
character (with default): possiblity to provide own legend text. This argument is
only considered for plot types providing a legend, e.g. plot.type="transect"
further arguments and graphical parameters that will be passed to the plot function.

Details
Matrix structure
(cf. RLum.Data.Spectrum)
• rows (x-values): wavelengths/channels (xlim, xlab)
• columns (y-values): time/temperature (ylim, ylab)
• cells (z-values): count values (zlim, zlab)
Note: This nomenclature is valid for all plot types of this function!
Nomenclature for value limiting
• xlim: Limits values along the wavelength axis
• ylim: Limits values along the time/temperature axis
• zlim: Limits values along the count value axis
Details on the plot functions
Spectrum is visualised as 3D or 2D plot. Both plot types are based on internal R plot functions.
plot.type = "persp"
Arguments that will be passed to persp:
•
•
•
•
•

shade: default is 0.4
phi: default is 15
theta: default is -30
expand: default is 1
ticktype: default is detailed, r: default is 10

Note: Further parameters can be adjusted via par. For example to set the background transparent
and reduce the thickness of the lines use: par(bg = NA,lwd = 0.7) previous the function call.
plot.type = "single"
Per frame a single curve is returned. Frames are time or temperature steps.
plot.type = "multiple.lines"
All frames plotted in one frame.
plot.type = "transect"
Depending on the selected wavelength/channel range a transect over the time/temperature (y-axis)
will be plotted along the wavelength/channels (x-axis). If the range contains more than one channel, values (z-values) are summed up. To select a transect use the xlim argument, e.g. xlim =
c(300,310) plot along the summed up count values of channel 300 to 310.
Further arguments that will be passed (depending on the plot type)
xlab, ylab, zlab, xlim, ylim, zlim, main, mtext, pch, type ("single", "multiple.lines", "interactive"), col, border, box lwd, bty, showscale ("interactive")

238

plot_RLum.Data.Spectrum

Value
Returns a plot.
Function version
0.6.2 (2019-01-28 23:38:34)
How to cite
Kreutzer, S. (2019). plot_RLum.Data.Spectrum(): Plot function for an RLum.Data.Spectrum S4
class object. Function version 0.6.2. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt,
C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data
Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
Not all additional arguments (...) will be passed similarly!
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
RLum.Data.Spectrum, convert_Wavelength2Energy, plot, plot_RLum, persp, plotly::plot_ly, contour
Examples
##load example data
data(ExampleData.XSYG, envir = environment())
##(1)plot simple spectrum (2D) - contour
plot_RLum.Data.Spectrum(TL.Spectrum,
plot.type="contour",
xlim = c(310,750),
ylim = c(0,300),
bin.rows=10,
bin.cols = 1)
##(2) plot spectrum (3D)
plot_RLum.Data.Spectrum(
TL.Spectrum,
plot.type="persp",
xlim = c(310,750),
ylim = c(0,100),
bin.rows=10,
bin.cols = 1)
##(3) plot spectrum on energy axis
##please note the background subtraction
plot_RLum.Data.Spectrum(TL.Spectrum,
plot.type="persp",

plot_RLum.Results

239

ylim = c(0,200),
bin.rows=10,
bg.channels = 10,
bin.cols = 1,
xaxis.energy = TRUE)
##(4) plot multiple lines (2D) - multiple.lines (with ylim)
plot_RLum.Data.Spectrum(
TL.Spectrum,
plot.type="multiple.lines",
xlim = c(310,750),
ylim = c(0,100),
bin.rows=10,
bin.cols = 1)
## Not run:
##(4) interactive plot using the package plotly ("surface")
plot_RLum.Data.Spectrum(TL.Spectrum, plot.type="interactive",
xlim = c(310,750), ylim = c(0,300), bin.rows=10,
bin.cols = 1)
##(5) interactive plot using the package plotly ("contour")
plot_RLum.Data.Spectrum(TL.Spectrum, plot.type="interactive",
xlim = c(310,750), ylim = c(0,300), bin.rows=10,
bin.cols = 1,
type = "contour",
showscale = TRUE)
##(6) interactive plot using the package plotly ("heatmap")
plot_RLum.Data.Spectrum(TL.Spectrum, plot.type="interactive",
xlim = c(310,750), ylim = c(0,300), bin.rows=10,
bin.cols = 1,
type = "heatmap",
showscale = TRUE)
##(7) alternative using the package fields
fields::image.plot(get_RLum(TL.Spectrum))
contour(get_RLum(TL.Spectrum), add = TRUE)
## End(Not run)

plot_RLum.Results

Plot function for an RLum.Results S4 class object

Description
The function provides a standardised plot output for data of an RLum.Results S4 class object
Usage
plot_RLum.Results(object, single = TRUE, ...)

240

plot_RLum.Results

Arguments
object

RLum.Results (required): S4 object of class RLum.Results

single

logical (with default): single plot output (TRUE/FALSE) to allow for plotting the
results in as few plot windows as possible.

...

further arguments and graphical parameters will be passed to the plot function.

Details
The function produces a multiple plot output. A file output is recommended (e.g., pdf).
Value
Returns multiple plots.
Function version
0.2.1 (2018-02-19 17:43:40)
How to cite
Burow, C., Kreutzer, S. (2019). plot_RLum.Results(): Plot function for an RLum.Results S4 class
object. Function version 0.2.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt,
C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data
Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
Not all arguments available for plot will be passed! Only plotting of RLum.Results objects are
supported.
Author(s)
Christoph Burow, University of Cologne (Germany)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
plot, plot_RLum
Examples

###load data
data(ExampleData.DeValues, envir = environment())
# apply the un-logged minimum age model
mam <- calc_MinDose(data = ExampleData.DeValues$CA1, sigmab = 0.2, log = TRUE, plot = FALSE)
##plot
plot_RLum.Results(mam)
# estimate the number of grains on an aliquot

plot_ViolinPlot

241

grains<- calc_AliquotSize(grain.size = c(100,150), sample.diameter = 1, plot = FALSE, MC.iter = 100)
##plot
plot_RLum.Results(grains)

plot_ViolinPlot

Create a violin plot

Description
Draws a kernal densiy plot in combination with a boxplot in its middle. The shape of the violin
is constructed using a mirrored density curve. This plot is especially designed for cases where the
individual errors are zero or to small to be visualised. The idea for this plot is based on the the
’volcano plot’ in the ggplot2 package by Hadely Wickham and Winston Chang. The general idea
for the Violin Plot seems to be introduced by Hintze and Nelson (1998).
Usage
plot_ViolinPlot(data, boxplot = TRUE, rug = TRUE, summary = NULL,
summary.pos = "sub", na.rm = TRUE, ...)
Arguments
data

numeric or RLum.Results (required): input data for plotting. Alternatively a
data.frame or a matrix can be provided, but only the first column will be considered by the function

boxplot

logical (with default): enable or disable boxplot

rug

logical (with default): enable or disable rug

summary

character (optional): add statistic measures of centrality and dispersion to the
plot. Can be one or more of several keywords. See details for available keywords.

summary.pos

numeric or character (with default): optional position keywords (cf., legend) for
the statistical summary. Alternatively, the keyword "sub" may be specified to
place the summary below the plot header. However, this latter option in only
possible if mtext is not used.

na.rm

logical (with default): exclude NA values from the data set prior to any further
operations.

...

further arguments and graphical parameters passed to plot.default, stats::density
and boxplot. See details for further information

Details
The function is passing several arguments to the function plot, stats::density, graphics::boxplot:
Supported arguments are: xlim, main, xlab, ylab, col.violin, col.boxplot, mtext, cex, mtext
Valid summary keywords
'n', 'mean', 'median', 'sd.abs', 'sd.rel', 'se.abs', 'se.rel'. 'skewness', 'kurtosis'

242

plot_ViolinPlot

Function version
0.1.4 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). plot_ViolinPlot(): Create a violin plot. Function version 0.1.4. In: Kreutzer, S.,
Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence:
Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence
Note
Although the code for this function was developed independently and just the idea for the plot was
based on the ’ggplot2’ package plot type ’volcano’, it should be mentioned that, beyond this, two
other R packages exist providing a possibility to produces this kind of plot, namely: ’vioplot’ and
’violinmplot’ (see References for details).
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
References
Daniel Adler (2005). vioplot: A violin plot is a combination of a box plot and a kernel density plot.
R package version 0.2 http://CRAN.R-project.org/package=violplot
Hintze, J.L., Nelson, R.D., 1998. A Box Plot-Density Trace Synergism. The American Statistician
52, 181-184.
Raphael W. Majeed (2012). violinmplot: Combination of violin plot with mean and standard deviation. R package version 0.2.1. http://CRAN.R-project.org/package=violinmplot
Wickham. H (2009). ggplot2: elegant graphics for data analysis. Springer New York.
See Also
stats::density, plot, boxplot, rug, calc_Statistics
Examples
## read example data set
data(ExampleData.DeValues, envir = environment())
ExampleData.DeValues <- Second2Gray(ExampleData.DeValues$BT998, c(0.0438,0.0019))
## create plot straightforward
plot_ViolinPlot(data = ExampleData.DeValues)

PSL2Risoe.BINfileData

243

PSL2Risoe.BINfileData Convert portable OSL data to an Risoe.BINfileData object

Description
Converts an RLum.Analysis object produced by the function read_PSL2R() to an Risoe.BINfileData
object (BETA).
Usage
PSL2Risoe.BINfileData(object, ...)
Arguments
object

RLum.Analysis (required): RLum.Analysis object produced by read_PSL2R

...

currently not used.

Details
This function converts an RLum.Analysis object that was produced by the read_PSL2R function
to an Risoe.BINfileData. The Risoe.BINfileData can be used to write a Risoe BIN file via
write_R2BIN.
Value
Returns an S4 Risoe.BINfileData object that can be used to write a BIN file using write_R2BIN.
Function version
0.0.1 (2018-01-21 17:22:38)
How to cite
Burow, C. (2019). PSL2Risoe.BINfileData(): Convert portable OSL data to an Risoe.BINfileData
object. Function version 0.0.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt,
C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data
Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Christoph Burow, University of Cologne (Germany)
R Luminescence Package Team
See Also
RLum.Analysis, RLum.Data.Curve, Risoe.BINfileData

244

read_BIN2R

Examples
# (1) load and plot example data set
data("ExampleData.portableOSL", envir = environment())
plot_RLum(ExampleData.portableOSL)
# (2) merge all RLum.Analysis objects into one
merged <- merge_RLum(ExampleData.portableOSL)
merged
# (3) convert to RisoeBINfile object
bin <- PSL2Risoe.BINfileData(merged)
bin
# (4) write Risoe BIN file
## Not run:
write_R2BIN(bin, "~/portableOSL.binx")
## End(Not run)

read_BIN2R

Import Risø BIN/BINX-files into R

Description
Import a *.bin or a *.binx file produced by a Risoe DA15 and DA20 TL/OSL reader into R.
Usage
read_BIN2R(file, show.raw.values = FALSE, position = NULL,
n.records = NULL, zero_data.rm = TRUE, duplicated.rm = FALSE,
fastForward = FALSE, show.record.number = FALSE,
txtProgressBar = TRUE, forced.VersionNumber = NULL,
ignore.RECTYPE = FALSE, pattern = NULL, verbose = TRUE, ...)
Arguments
file

show.raw.values

position

character or list (required): path and file name of the BIN/BINX file (URLs are
supported). If input is a list it should comprise only characters representing
each valid path and BIN/BINX-file names. Alternatively the input character can
be just a directory (path), in this case the the function tries to detect and import
all BIN/BINX files found in the directory.
logical (with default): shows raw values from BIN file for LTYPE, DTYPE and
LIGHTSOURCE without translation in characters. Can be provided as list if file
is a list.
numeric (optional): imports only the selected position. Note: the import performance will not benefit by any selection made here. Can be provided as list if
file is a list.

read_BIN2R

245

n.records

raw (optional): limits the number of imported records. Can be used in combination with show.record.number for debugging purposes, e.g. corrupt BIN-files.
Can be provided as list if file is a list.

zero_data.rm

logical (with default): remove erroneous data with no count values. As such
data are usally not needed for the subsequent data analysis they will be removed
by default. Can be provided as list if file is a list.

duplicated.rm

logical (with default): remove duplicated entries if TRUE. This may happen due
to an erroneous produced BIN/BINX-file. This option compares only predeccessor and successor. Can be provided as list if file is a list.

fastForward

logical (with default): if TRUE for a more efficient data processing only a list of
RLum.Analysis objects is returned instead of a Risoe.BINfileData object. Can
be provided as list if file is a list.
show.record.number
logical (with default): shows record number of the imported record, for debugging usage only. Can be provided as list if file is a list.

txtProgressBar logical (with default): enables or disables txtProgressBar.
forced.VersionNumber
integer (optional): allows to cheat the version number check in the function
by own values for cases where the BIN-file version is not supported. Can be
provided as list if file is a list.
Note: The usage is at own risk, only supported BIN-file versions have been
tested.
ignore.RECTYPE logical (with default): this argument allows to ignore values in the byte ’RECTYPE’ (BIN-file version 08), in case there are not documented or faulty set. In
this case the corrupted records are skipped.
pattern

character (optional): argument that is used if only a path is provided. The argument will than be passed to the function list.files used internally to construct a
list of wanted files

verbose

logical (with default): enables or disables verbose mode

...

further arguments that will be passed to the function Risoe.BINfileData2RLum.Analysis.
Please note that any matching argument automatically sets fastForward = TRUE

Details
The binary data file is parsed byte by byte following the data structure published in the Appendices
of the Analyst manual p. 42.
For the general BIN/BINX-file structure, the reader is referred to the Risoe website: http://www.
nutech.dtu.dk/
Value
Returns an S4 Risoe.BINfileData object containing two slots:
METADATA

A data.frame containing all variables stored in the bin-file.

DATA

A list containing a numeric vector of the measured data. The ID corresponds to
the record ID in METADATA.

If fastForward = TRUE a list of RLum.Analysis object is returned. The internal coercing is done
using the function Risoe.BINfileData2RLum.Analysis

246

read_Daybreak2R

Function version
0.16.1 (2019-03-07 12:59:03)
How to cite
Kreutzer, S., Fuchs, M.C. (2019). read_BIN2R(): Import Risø BIN/BINX-files into R. Function
version 0.16.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M.,
Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
The function works for BIN/BINX-format versions 03, 04, 05, 06, 07 and 08. The version number
depends on the used Sequence Editor.
ROI data sets introduced with BIN-file version 8 are not supported and skipped durint import.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France)
Margret C. Fuchs, HZDR Freiberg, (Germany)
based on information provided by Torben Lapp and Karsten Bracht Nielsen (Risø DTU, Denmark)
R Luminescence Package Team
References
DTU Nutech, 2016. The Squence Editor, Users Manual, February, 2016. http://www.nutech.
dtu.dk/english/products-and-services/radiation-instruments/tl_osl_reader/manuals
See Also
write_R2BIN, Risoe.BINfileData, base::readBin, merge_Risoe.BINfileData, RLum.Analysis utils::txtProgressBar,
list.files
Examples
##(1) import Risoe BIN-file to R (uncomment for usage)
#FILE <- file.choose()
#temp <- read_BIN2R(FILE)
#temp

read_Daybreak2R

Import measurement data produced by a Daybreak TL/OSL reader
into R

Description
Import a TXT-file (ASCII file) or a DAT-file (binary file) produced by a Daybreak reader into R.
The import of the DAT-files is limited to the file format described for the software TLAPLLIC v.3.2
used for a Daybreak, model 1100.

read_Daybreak2R

247

Usage
read_Daybreak2R(file, raw = FALSE, verbose = TRUE,
txtProgressBar = TRUE)
Arguments
file

character or list (required): path and file name of the file to be imported. Alternatively a list of file names can be provided or just the path a folder containing
measurement data. Please note that the specific, common, file extension (txt) is
likely leading to function failures during import when just a path is provided.

raw

logical (with default): if the input is a DAT-file (binary) a data.table::data.table
instead of the RLum.Analysis object can be returned for debugging purposes.

verbose

logical (with default): enables or disables terminal feedback

txtProgressBar logical (with default): enables or disables txtProgressBar.
Value
A list of RLum.Analysis objects (each per position) is provided.
Function version
0.3.1 (2018-01-21 17:22:38)
How to cite
Kreutzer, S., Zink, A. (2019). read_Daybreak2R(): Import measurement data produced by a Daybreak TL/OSL reader into R. Function version 0.3.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs,
M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence
Dating Data Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
[BETA VERSION] This function still needs to be tested properly. In particular the function has underwent only very rough rests using a few files.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
Anotine Zink, C2RMF, Palais du Louvre, Paris (France)
The ASCII-file import is based on a suggestion by Willian Amidon and Andrew Louis Gorin
R Luminescence Package Team
See Also
RLum.Analysis, RLum.Data.Curve, data.table::data.table
Examples
## Not run:
file <- file.choose()
temp <- read_Daybreak2R(file)

248

read_PSL2R
## End(Not run)

read_PSL2R

Import PSL files to R

Description
Imports PSL files produced by a SUERC portable OSL reader into R (BETA).
Usage
read_PSL2R(file, drop_bg = FALSE, as_decay_curve = TRUE,
smooth = FALSE, merge = FALSE, ...)
Arguments
file

character (required): path and file name of the PSL file. If input is a vector it
should comprise only characters representing valid paths and PSL file names.
Alternatively the input character can be just a directory (path). In this case the
the function tries to detect and import all PSL files found in the directory.

drop_bg

logical (with default): TRUE to automatically remove all non-OSL/IRSL curves.

as_decay_curve logical (with default): Portable OSL Reader curves are often given as cumulative
light sum curves. Use TRUE (default) to convert the curves to the more usual
decay form.
smooth

logical (with default): TRUE to apply Tukey’s Running Median Smoothing for
OSL and IRSL decay curves. Smoothing is encouraged if you see random signal
drops within the decay curves related to hardware errors.

merge

logical (with default): TRUE to merge all RLum.Analysis objects. Only applicable if multiple files are imported.

...

currently not used.

Details
This function provides an import routine for the SUERC portable OSL Reader PSL format. PSL
files are just plain text and can be viewed with any text editor. Due to the formatting of PSL files
this import function relies heavily on regular expression to find and extract all relevant information.
See note.
Value
Returns an S4 RLum.Analysis object containing RLum.Data.Curve objects for each curve.
Function version
0.0.1 (2019-01-15 15:04:23)

read_RF2R

249

How to cite
Burow, C. (2019). read_PSL2R(): Import PSL files to R. Function version 0.0.1. In: Kreutzer, S.,
Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence:
Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence
Note
Because this function relies heavily on regular expressions to parse PSL files it is currently only in
beta status. If the routine fails to import a specific PSL file please report to christoph.burow@gmx.net
so the function can be updated.
Author(s)
Christoph Burow, University of Cologne (Germany)
R Luminescence Package Team
See Also
RLum.Analysis, RLum.Data.Curve, RLum.Data.Curve
Examples
# (1) Import PSL file to R
file <- system.file("extdata", "DorNie_0016.psl", package = "Luminescence")
psl <- read_PSL2R(file, drop_bg = FALSE, as_decay_curve = TRUE, smooth = TRUE, merge = FALSE)
print(str(psl, max.level = 3))
plot(psl, combine = TRUE)

read_RF2R

Import RF-files to R

Description
Import files produced by the IR-RF ’ImageJ’ macro (#TODO ADD REFERENCE) into R and create
a list of RLum.Analysis objects
Usage
read_RF2R(file)
Arguments
file

character (required): path and file name of the RF file. Alternatively a list of
file names can be provided.

250

read_SPE2R

Details
The results of spatially resolved IR-RF data are summarised in so-called RF-files (#TODO ADD
REFERENCE). This functions provides an easy import to process the data seamlessly with the R
package ’Luminescence’. The output of the function can be passed to the function analyse_IRSAR.RF
Value
Returns an S4 RLum.Analysis object containing RLum.Data.Curve objects for each curve.
Function version
0.0.1 (2019-01-15 01:11:37)
How to cite
Kreutzer, S. (2019). read_RF2R(): Import RF-files to R. Function version 0.0.1. In: Kreutzer, S.,
Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence:
Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS-Université Bordeaux Montaigne (France)
R Luminescence Package Team
References
#TODO ADD REFERENCE
See Also
RLum.Analysis, RLum.Data.Curve, analyse_IRSAR.RF
Examples
##Import
file <- system.file("extdata", "RF_file.rf", package = "Luminescence")
temp <- read_RF2R(file)

read_SPE2R

Import Princeton Intruments (TM) SPE-file into R

Description
Function imports Princeton Instruments (TM) SPE-files into R environment and provides RLum
objects as output.
Usage
read_SPE2R(file, output.object = "RLum.Data.Image", frame.range,
txtProgressBar = TRUE, verbose = TRUE)

read_SPE2R

251

Arguments
file

character (required): spe-file name (including path), e.g.
• [WIN]: read_SPE2R("C:/Desktop/test.spe")
• [MAC/LINUX]: readSPER("/User/test/Desktop/test.spe"). Additionally internet connections are supported.

output.object

character (with default): set RLum output object. Allowed types are "RLum.Data.Spectrum",
"RLum.Data.Image" or "matrix"

frame.range

vector (optional): limit frame range, e.g. select first 100 frames by frame.range
= c(1,100)

txtProgressBar logical (with default): enables or disables txtProgressBar.
verbose

logical (with default): enables or disables verbose mode

Details
Function provides an import routine for the Princton Instruments SPE format. Import functionality
is based on the file format description provided by Princton Instruments and a MatLab script written
by Carl Hall (s. references).
Value
Depending on the chosen option the functions returns three different type of objects:
output.object
RLum.Data.Spectrum
An object of type RLum.Data.Spectrum is returned. Row sums are used to integrate all counts over
one channel.
RLum.Data.Image
An object of type RLum.Data.Image is returned. Due to performace reasons the import is aborted
for files containing more than 100 frames. This limitation can be overwritten manually by using the
argument frame.frange.
matrix
Returns a matrix of the form: Rows = Channels, columns = Frames. For the transformation the
function get_RLum is used, meaning that the same results can be obtained by using the function
get_RLum on an RLum.Data.Spectrum or RLum.Data.Image object.
Function version
0.1.2 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). read_SPE2R(): Import Princeton Intruments (TM) SPE-file into R. Function
version 0.1.2. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M.,
Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence

252

read_SPE2R

Note
The function does not test whether the input data are spectra or pictures for spatial resolved
analysis!
The function has been successfully tested for SPE format versions 2.x.
Currently not all information provided by the SPE format are supported.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Université Bordeaux Montaigne (France)
R Luminescence Package Team
References
Princeton Instruments, 2014. Princeton Instruments SPE 3.0 File Format Specification, Version 1.A
(for document URL please use an internet search machine)
Hall, C., 2012: readSPE.m. http://www.mathworks.com/matlabcentral/fileexchange/35940-readspe/
content/readSPE.m
See Also
readBin, RLum.Data.Spectrum, raster::raster
Examples
## to run examples uncomment lines and run the code
##(1) Import data as RLum.Data.Spectrum object
#file <- file.choose()
#temp <- read_SPE2R(file)
#temp
##(2) Import data as RLum.Data.Image object
#file <- file.choose()
#temp <- read_SPE2R(file, output.object = "RLum.Data.Image")
#temp
##(3) Import data as matrix object
#file <- file.choose()
#temp <- read_SPE2R(file, output.object = "matrix")
#temp
##(4) Export raw data to csv, if temp is a RLum.Data.Spectrum object
# write.table(x = get_RLum(temp),
#
file = "[your path and filename]",
#
sep = ";", row.names = FALSE)

read_XSYG2R

read_XSYG2R

253

Import XSYG files to R

Description
Imports XSYG files produced by a Freiberg Instrument lexsyg reader into R.
Usage
read_XSYG2R(file, recalculate.TL.curves = TRUE, fastForward = FALSE,
import = TRUE, pattern = ".xsyg", verbose = TRUE,
txtProgressBar = TRUE)
Arguments
file

character or list (required): path and file name of the XSYG file. If input is
a list it should comprise only characters representing each valid path and
xsyg-file names. Alternatively the input character can be just a directory (path),
in this case the the function tries to detect and import all xsyg files found in the
directory.
recalculate.TL.curves
logical (with default): if set to TRUE, TL curves are returned as temperature
against count values (see details for more information) Note: The option overwrites the time vs. count TL curve. Select FALSE to import the raw data delivered
by the lexsyg. Works for TL curves and spectra.
fastForward

logical (with default): if TRUE for a more efficient data processing only a list of
RLum.Analysis objects is returned.

import

logical (with default): if set to FALSE, only the XSYG file structure is shown.

pattern

regex (with default): optional regular expression if file is a link to a folder, to
select just specific XSYG-files

verbose

logical (with default): enable or disable verbose mode. If verbose is FALSE the
txtProgressBar is also switched off

txtProgressBar logical (with default): enables TRUE or disables FALSE the progression bar during
import
Details
How does the import function work?
The function uses the xml package to parse the file structure. Each sequence is subsequently translated into an RLum.Analysis object.
General structure XSYG format





x0 , y0 ; x1 , y1 ; x2 , y2 ; x3 , y3


254

read_XSYG2R


So far, each XSYG file can only contain one , but multiple sequences.
Each record may comprise several curves.
TL curve recalculation
On the FI lexsyg device TL curves are recorded as time against count values. Temperature values
are monitored on the heating plate and stored in a separate curve (time vs. temperature). If the
option recalculate.TL.curves = TRUE is chosen, the time values for each TL curve are replaced
by temperature values.
Practically, this means combining two matrices (Time vs. Counts and Time vs. Temperature) with
different row numbers by their time values. Three cases are considered:
1. HE: Heating element
2. PMT: Photomultiplier tube
3. Interpolation is done using the function approx
CASE (1): nrow(matrix(PMT)) > nrow(matrix(HE))
Missing temperature values from the heating element are calculated using time values from the
PMT measurement.
CASE (2): nrow(matrix(PMT)) < nrow(matrix(HE))
Missing count values from the PMT are calculated using time values from the heating element
measurement.
CASE (3): nrow(matrix(PMT)) == nrow(matrix(HE))
A new matrix is produced using temperature values from the heating element and count values from
the PMT.
Note: Please note that due to the recalculation of the temperature values based on values delivered
by the heating element, it may happen that mutiple count values exists for each temperature value
and temperature values may also decrease during heating, not only increase.
Advanced file import
To allow for a more efficient usage of the function, instead of single path to a file just a directory
can be passed as input. In this particular case the function tries to extract all XSYG-files found in
the directory and import them all. Using this option internally the function constructs as list of the
XSYG-files found in the directory. Please note no recursive detection is supported as this may lead
to endless loops.

Value
Using the option import = FALSE
A list consisting of two elements is shown:
• data.frame with information on file.
• data.frame with information on the sequences stored in the XSYG file.
Using the option import = TRUE (default)
A list is provided, the list elements contain:
Sequence.Header
data.frame with information on the sequence.
Sequence.Object
RLum.Analysis containing the curves.

read_XSYG2R

255

Function version
0.6.7 (2019-01-15 15:20:34)
How to cite
Kreutzer, S. (2019). read_XSYG2R(): Import XSYG files to R. Function version 0.6.7. In:
Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019).
Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6.
https://CRAN.R-project.org/package=Luminescence
Note
This function is a beta version as the XSYG file format is not yet fully specified. Thus, further
file operations (merge, export, write) should be done using the functions provided with the package
xml.
So far, no image data import is provided!
Corresponding values in the XSXG file are skipped.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France)
R Luminescence Package Team
References
Grehl, S., Kreutzer, S., Hoehne, M., 2013. Documentation of the XSYG file format. Unpublished
Technical Note. Freiberg, Germany
Further reading
XML: http://en.wikipedia.org/wiki/XML
See Also
xml, RLum.Analysis, RLum.Data.Curve, approx
Examples
##(1) import XSYG file to R (uncomment for usage)
#FILE <- file.choose()
#temp <- read_XSYG2R(FILE)
##(2) additional examples for pure XML import using the package XML
##
(uncomment for usage)
##import entire XML file
#FILE <- file.choose()
#temp <- XML::xmlRoot(XML::xmlTreeParse(FILE))
##search for specific subnodes with curves containing 'OSL'
#getNodeSet(temp, "//Sample/Sequence/Record[@recordType = 'OSL']/Curve")
##(2) How to extract single curves ... after import
data(ExampleData.XSYG, envir = environment())

256

replicate_RLum

##grep one OSL curves and plot the first curve
OSLcurve <- get_RLum(OSL.SARMeasurement$Sequence.Object, recordType="OSL")[[1]]
##(3) How to see the structure of an object?
structure_RLum(OSL.SARMeasurement$Sequence.Object)

replicate_RLum

General replication function for RLum S4 class objects

Description
Function replicates RLum S4 class objects and returns a list for this objects
Usage
replicate_RLum(object, times = NULL)
Arguments
object

RLum (required): an RLum object

times

integer (optional): number for times each element is repeated element

Value
Returns a list of the object to be repeated
Function version
0.1.0 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). replicate_RLum(): General replication function for RLum S4 class objects.
Function version 0.1.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
RLum

report_RLum

report_RLum

257

Create a HTML report for (RLum) objects

Description
This function creates a HTML report for a given object, listing its complete structure and content.
The object itself is saved as a serialised .Rds file. The report file serves both as a convenient way of
browsing through objects with complex data structures as well as a mean of properly documenting
and saving objects.
Usage
report_RLum(object, file = tempfile(), title = "RLum.Report",
compact = TRUE, timestamp = TRUE, show_report = TRUE,
launch.browser = FALSE, css.file = NULL, quiet = TRUE,
clean = TRUE, ...)
Arguments
object

(required): The object to be reported on, preferably of any RLum-class.

file

character (with default): A character string naming the output file. If no filename
is provided a temporary file is created.

title

character (with default): A character string specifying the title of the document.

compact

logical (with default): When TRUE the following report components are hidden:
@.pid, @.uid, 'Object structure', 'Session Info' and only the first and
last 5 rows of long matrices and data frames are shown. See details.

timestamp

logical (with default): TRUE to add a timestamp to the filename (suffix).

show_report

logical (with default): If set to TRUE the function tries to display the report output
in the local viewer, e.g., within RStudio after rendering.

launch.browser logical (with default): TRUE to open the HTML file in the system’s default web
browser after it has been rendered.
css.file

character (optional): Path to a CSS file to change the default styling of the
HTML document.

quiet

logical (with default): TRUE to supress printing of the pandoc command line.

clean

logical (with default): TRUE to clean intermediate files created during rendering.

...

further arguments passed to or from other methods and to control the document’s
structure (see details).

Details
The HTML report is created with rmarkdown::render and has the following structure:
Section
Header
Object content
Object structure
File
Session Info
Plots

Description
A summary of general characteristics of the object
A comprehensive list of the complete structure and content of the provided object.
Summary of the objects structure given as a table
Information on the saved RDS file
Captured output from sessionInfo()
(optional) For RLum-class objects a variable number of plots

258

report_RLum
The structure of the report can be controlled individually by providing one or more of the following
arguments (all logical):
Argument
header
main
structure
rds
session
plot

Description
Hide or show general information on the object
Hide or show the object’s content
Hide or show object’s structure
Hide or show information on the saved RDS file
Hide or show the session info
Hide or show the plots (depending on object)

Note that these arguments have higher precedence than compact.
Further options that can be provided via the ... argument:
Argument
short_table
theme
highlight
css

Description
If TRUE only show the first and last 5 rows of lang tables.
Specifies the Bootstrap theme to use for the report. Valid themes include "default", "cerulean", "journal",
Specifies the syntax highlighting style. Supported styles include "default", "tango", "pygments", "kate", "m
TRUE or FALSE to enable/disable custom CSS styling

The following arguments can be used to customise the report via CSS (Cascading Style Sheets):
Argument
font_family
headings_size
content_color

Description
Define the font family of the HTML document (default: arial)
Size of the 
 to 
 tags used to define HTML headings (default: 166%).
Color of the object’s content (default: #a72925).

Note that these arguments must all be of class character and follow standard CSS syntax. For
exhaustive CSS styling you can provide a custom CSS file for argument css.file. CSS styling can
be turned of using css = FALSE.
Value
Writes a HTML and .Rds file.
Function version
0.1.1 (2018-06-10 16:57:37)
How to cite
Burow, C., Kreutzer, S. (2019). report_RLum(): Create a HTML report for (RLum) objects. Function version 0.1.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
This function requires the R packages ’rmarkdown’, ’pander’ and ’rstudioapi’.

report_RLum

259

Author(s)
Christoph Burow, University of Cologne (Germany), Sebastian Kreutzer, IRAMAT-CRP2A, Université Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
rmarkdown::render, pander::pander_return, pander::openFileInOS, rstudioapi::viewer, browseURL
Examples
## Not run:
## Example: RLum.Results ---# load example data
data("ExampleData.DeValues")
# apply the MAM-3 age model and save results
mam <- calc_MinDose(ExampleData.DeValues$CA1, sigmab = 0.2)
# create the HTML report
report_RLum(object = mam, file = "~/CA1_MAM.Rmd",
timestamp = FALSE,
title = "MAM-3 for sample CA1")
# when creating a report the input file is automatically saved to a
# .Rds file (see saveRDS()).
mam_report <- readRDS("~/CA1_MAM.Rds")
all.equal(mam, mam_report)
## Example: Temporary file & Viewer/Browser ---# (a)
# Specifying a filename is not necessarily required. If no filename is provided,
# the report is rendered in a temporary file. If you use the RStudio IDE, the
# temporary report is shown in the interactive Viewer pane.
report_RLum(object = mam)
# (b)
# Additionally, you can view the HTML report in your system's default web browser.
report_RLum(object = mam, launch.browser = TRUE)
## Example: RLum.Analysis ---data("ExampleData.RLum.Analysis")
# create the HTML report (note that specifying a file
# extension is not necessary)
report_RLum(object = IRSAR.RF.Data, file = "~/IRSAR_RF")
## Example: RLum.Data.Curve ----

260

Risoe.BINfileData2RLum.Analysis

data.curve <- get_RLum(IRSAR.RF.Data)[[1]]
# create the HTML report
report_RLum(object = data.curve, file = "~/Data_Curve")
## Example: Any other object ---x <- list(x = 1:10,
y = runif(10, -5, 5),
z = data.frame(a = LETTERS[1:20], b = dnorm(0:9)),
NA)
report_RLum(object = x, file = "~/arbitray_list")
## End(Not run)

Risoe.BINfileData2RLum.Analysis
Convert Risoe.BINfileData object to an RLum.Analysis object

Description
Converts values from one specific position of a Risoe.BINfileData S4-class object to an RLum.Analysis
object.
Usage
Risoe.BINfileData2RLum.Analysis(object, pos = NULL, grain = NULL,
run = NULL, set = NULL, ltype = NULL, dtype = NULL,
protocol = "unknown", keep.empty = TRUE, txtProgressBar = FALSE)
Arguments
object

Risoe.BINfileData (required): Risoe.BINfileData object

pos

numeric (optional): position number of the Risoe.BINfileData object for which
the curves are stored in the RLum.Analysis object. If length(position)>1 a
list of RLum.Analysis objects is returned. If nothing is provided every position
will be converted. If the position is not valid NA is returned.

grain

vector, numeric (optional): grain number from the measurement to limit the
converted data set (e.g., grain = c(1:48)). Please be aware that this option
may lead to unwanted effects, as the output is strictly limited to the choosen
grain number for all position numbers

run

vector, numeric (optional): run number from the measurement to limit the converted data set (e.g., run = c(1:48)).

set

vector, numeric (optional): set number from the measurement to limit the converted data set (e.g., set = c(1:48)).

ltype

vector, character (optional): curve type to limit the converted data. Commonly
allowed values are: IRSL, OSL, TL, RIR, RBR and USER (see also Risoe.BINfileData)

dtype

vector, character (optional): data type to limit the converted data. Commonly
allowed values are listed in Risoe.BINfileData

Risoe.BINfileData2RLum.Analysis

261

protocol

character (optional): sets protocol type for analysis object. Value may be used
by subsequent analysis functions.

keep.empty

logical (with default): If TRUE (default) an RLum.Analysis object is returned
even if it does not contain any records. Set to FALSE to discard all empty objects.

txtProgressBar logical (with default): enables or disables txtProgressBar.
Details
The RLum.Analysis object requires a set of curves for specific further protocol analyses. However,
the Risoe.BINfileData usually contains a set of curves for different aliquots and different protocol
types that may be mixed up. Therefore, a conversion is needed.
Value
Returns an RLum.Analysis object.
Function version
0.4.2 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). Risoe.BINfileData2RLum.Analysis(): Convert Risoe.BINfileData object to
an RLum.Analysis object. Function version 0.4.2. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs,
M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence
Dating Data Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
The protocol argument of the RLum.Analysis object is set to ’unknown’ if not stated otherwise.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
Risoe.BINfileData, RLum.Analysis, read_BIN2R
Examples
##load data
data(ExampleData.BINfileData, envir = environment())
##convert values for position 1
Risoe.BINfileData2RLum.Analysis(CWOSL.SAR.Data, pos = 1)

262

RLum-class

RLum-class

Class "RLum"

Description
Abstract class for data in the package Luminescence Sublasses are:
Usage
## S4 method for signature 'RLum'
replicate_RLum(object, times = NULL)
Arguments
object

RLum (required): an object of class RLum

times

integer (optional): number for times each element is repeated element

Details
RLum-class
|
|—-RLum.Data
|—-|– RLum.Data.Curve
|—-|– RLum.Data.Spectrum
|—-|– RLum.Data.Image
|—-RLum.Analysis
|—-RLum.Results
Methods (by generic)
• replicate_RLum: Replication method RLum-objects
Slots
originator Object of class character containing the name of the producing function for the object.
Set automatically by using the function set_RLum.
info Object of class list for additional information on the object itself
.uid Object of class character for a unique object identifier. This id is usually calculated using the
internal function create_UID() if the funtion set_RLum is called.
.pid Object of class character for a parent id. This allows nesting RLum-objects at will. The
parent id can be the uid of another object.
Objects from the Class
A virtual Class: No objects can be created from it.
Class version
0.4.0

scale_GammaDose

263

How to cite
Kreutzer, S. (2019). RLum-class(): Class ’RLum’. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs,
M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence
Dating Data Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
RLum is a virtual class.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Université Bordeaux Montaigne (France)
See Also
RLum.Data, RLum.Data.Curve, RLum.Data.Spectrum, RLum.Data.Image, RLum.Analysis, RLum.Results,
methods_RLum
Examples
showClass("RLum")

scale_GammaDose

Calculate the gamma dose deposited within a sample taking layerto-layer variations in radioactivity into account (according to Aitken,
1985)

Description
This function calculates the gamma dose deposited in a luminescence sample taking into account
layer-to-layer variations in sediment radioactivity . The function scales user inputs of Uranium,
Thorium and Potassium based on input parameters for sediment density, water content and given
layer thicknesses and distances to the sample.
Usage
scale_GammaDose(data, conversion_factors = c("Cresswelletal2019",
"Guerinetal2011", "AdamiecAitken1998", "Liritzisetal2013")[1],
fractional_gamma_dose = c("Aitken1985")[1], verbose = TRUE,
plot = TRUE, plot_single = TRUE, ...)
Arguments
data

data.frame (required): A table containing all relevant information for each individual layer. The table must have the following named columns:
• id (character): an arbitrary id or name of each layer
• thickness (numeric): vertical extent of each layer in cm
• sample_offset (logical): distance of the sample in cm, measured from
the BOTTOM OF THE TARGET LAYER. Except for the target layer all
values must be NA.

264

scale_GammaDose
• K (numeric): K nuclide content in
• K_se (numeric): error on the K content
• Th (numeric): Th nuclide content in ppm
• Th_se (numeric): error on the Th content
• U (numeric): U nuclide content in ppm
• U_se (numeric): error on the U content
• water_content (numeric): water content of each layer in
• water_content_se (numeric): error on the water content
• density (numeric): bulk density of each layer in g/cm^-3
conversion_factors
character (optional): The conversion factors used to calculate the dose rate from
sediument nuclide contents. Valid options are:
• "Cresswelletal2019" (default)
• "Liritzisetal2013"
• "Guerinetal2011"
• "AdamiecAitken1998"
fractional_gamma_dose
character (optional): Factors to scale gamma dose rate values. Valid options are:
• "Aitken1985" (default): Table H1 in the appendix
verbose

logical (optional): Show or hide console output (defaults to TRUE).

plot

logical (optional): Show or hide the plot (defaults to TRUE).

plot_single

logical (optional): Show all plots in one panel (defaults to TRUE).

...

Further parameters passed to barplot.

Details
User Input
To calculate the gamma dose which is deposited in a sample, the user needs to provide information
on those samples influencing the luminescence sample. As a rule of thumb, all sediment layers
within at least 30 cm radius from the luminescence sample taken should be taken into account when
calculating the gamma dose rate. However, the actual range of gamma radiation might be different,
depending on the emitting radioelement, the water content and the sediment density of each layer
(Aitken, 1985). Therefore the user is advised to provide as much detail as possible and physically
sensible.
The function requires a data.frame that is to be structured in columns and rows, with samples listed
in rows. The first column contains information on the layer/sample ID, the second on the thickness
(in cm) of each layer, whilst column 3 should contain NA for all layers that are not sampled for
OSL/TL. For the layer the OSL/TL sample was taken from a numerical value must be provided,
which is the distance (in cm) measured from bottom of the layer of interest. If the whole layer was
sampled insert 0. If the sample was taken from within the layer, insert a numerical value >0, which
describes the distance from the middle of the sample to the bottom of the layer in cm. Columns 4 to 9
should contain radionuclide concentrations and their standard errors for Potassium (in give information on the water content and its uncertainty (standard error) in should be left blank. Please ensure to
keep the column titles as given in the example dataset (data('ExampleData.ScaleGammaDose'),
see examples).
The user can decide which dose rate conversion factors should be used to calculate the gamma dose
rates. The options are:
• "Cresswelletal2019" (Cresswell et al., in press; the default)

scale_GammaDose

265

• "Liritzisetal2013" (Liritzis et al., 2013)
• "Guerinetal2011" (Guerin et al., 2011)
• "AdamiecAitken1998" (Adamiec and Aitken, 1998)
Water content
The water content provided by the user should be calculated according to:
(W etweight[g] − Dryweight[g])/Dryweight[g] ∗ 100
Calculations
After converting the radionuclide concentrations into dose rates, the function will scale the dose
rates based on the thickness of the layers, the distances to the sample, the water content and the
density of the sediment. The calculations are based on Aitken (1985, Appendix H). As an example
(equivalent to Aitken, 1985), assuming three layers of sediment, where L is inert and positioned in
between the infinite thick and equally active layers A and B, the dose in L and B due to A is given
by
1 − f (x)DA
Where x is the distance into the inert medium, so f(x) is the weighted average fractional dose at
x and D_A denotes that the dose is delivered by A. f(x) is derived from table H1 (Aitken, 1985),
when setting z = x. Consequently, the dose in A and L due to B is given by
1 − f (t − x)DB
Here t is the thickness of L and the other parameters are denoted as above, just for the dose being
delivered by B. f(t-x) is derived from table H1 (Aitken, 1985), when setting z equal to t-x.
Following this, the dose in L delivered by A and B is given by
2 − f (x) − f (t − x)DAB
Since A and B are equally active D_{AB} = D_A = D_B.
The function uses the value of the fractional dose rate at the layer boundary to start the calculation
for the next layer. This way, the function is able to scale the gamma dose rate accurately for distant
layers when the density and water content is not constant for the entire section.
Value
After performing the calculations the user is provided with different outputs.
1. The total gamma dose rate received by the sample (+/- uncertainties) as a print in the console.
2. A plot showing the sediment sequence, the user input sample information and the contribution
to total gamma dose rate.
3. RLum Results. If the user wishes to save these results, writing a script to run the function and
to save the results would look like this:
mydata <- read.table("c:/path/to/input/file.txt")
results <- scale_GammaDose(mydata)
table <- get_RLum(results)
write.csv(table, "c:/path/to/results.csv")

266

scale_GammaDose
———————————–
[ NUMERICAL OUTPUT ]
———————————–
RLum.Results-object
slot: @data
Element
$summary
$data
$dose_rates
$tables
$args
$call

Type
data.frame
data.frame
list
list
character
call

Description
summary of the model results
the original input data
two data.frames for the scaled and infinite matrix dose rates
several data.frames containing intermediate results
arguments of the call
the original function call

slot: @info
Currently unused.
————————
[ PLOT OUTPUT ]
————————
Three plots are produced:
• A visualisation of the provided sediment layer structure to quickly assess whether the data was
provided and interpreted correctly.
• A scatter plot of the nuclide contents per layer (K, Th, U) as well as the water content. This
may help to correlate the dose rate contribution of specific layers to the layer of interest.
• A barplot visualising the contribution of each layer to the total dose rate received by the sample
in the target layer.
Function version
0.1.1 (2019-03-05 11:51:39)
Acknowledgements
We thank Dr Ian Bailiff for the provision of an excel spreadsheet, which has been very helpful when
writing this function.
How to cite
Riedesel, S., Autzen, M., Burow, C. (2019). scale_GammaDose(): Calculate the gamma dose deposited within a sample taking layer-to-layer variations in radioactivity into account (according to
Aitken, 1985). Function version 0.1.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C.,
Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
This function has BETA status. If possible, results should be cross-checked.

Second2Gray

267

Author(s)
Svenja Riedesel, Aberystwyth University (United Kingdom)
Martin Autzen, DTU NUTECH Center for Nuclear Technologies (Denmark)
Christoph Burow, University of Cologne (Germany)
Based on an excel spreadsheet and accompanying macro written by Ian Bailiff.
R Luminescence Package Team
References
Aitken, M.J., 1985. Thermoluminescence Dating. Academic Press, London.
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., in press. Dose rate conversion parameters: Assessment of nuclear data. Radiation Measurements.
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.
See Also
ExampleData.ScaleGammaDose, approx, barplot
Examples
# Load example data
data("ExampleData.ScaleGammaDose", envir = environment())
x <- ExampleData.ScaleGammaDose
# Scale gamma dose rate
results <- scale_GammaDose(data = x,
conversion_factors = "Cresswelletal2019",
fractional_gamma_dose = "Aitken1985",
verbose = TRUE,
plot = TRUE)
get_RLum(results)

Second2Gray

Converting equivalent dose values from seconds (s) to gray (Gy)

Description
Conversion of absorbed radiation dose in seconds (s) to the SI unit gray (Gy) including error propagation. Normally used for equivalent dose data.
Usage
Second2Gray(data, dose.rate, error.propagation = "omit")

268

Second2Gray

Arguments
data

data.frame (required): input values, structure: data (values[,1]) and data error
(values [,2]) are required
dose.rate
RLum.Results, data.frame or numeric (required): RLum.Results needs to be
orginated from the function calc_SourceDoseRate, for vector dose rate in Gy/s
and dose rate error in Gy/s
error.propagation
character (with default): error propagation method used for error calculation
(omit, gaussian or absolute), see details for further information
Details
Calculation of De values from seconds (s) to gray (Gy)
De[Gy] = De[s] ∗ DoseRate[Gy/s])
Provided calculation error propagation methods for error calculation (with ’se’ as the standard error
and ’DR’ of the dose rate of the beta-source):
(1) omit (default)
se(De)[Gy] = se(De)[s] ∗ DR[Gy/s]
In this case the standard error of the dose rate of the beta-source is treated as systematic (i.e. nonrandom), it error propagation is omitted. However, the error must be considered during calculation
of the final age. (cf. Aitken, 1985, pp. 242). This approach can be seen as method (2) (gaussian) for
the case the (random) standard error of the beta-source calibration is 0. Which particular method is
requested depends on the situation and cannot be prescriptive.
(2) gaussian error propagation
p
se(De)[Gy] = ((DR[Gy/s] ∗ se(De)[s])2 + (De[s] ∗ se(DR)[Gy/s])2 )
Applicable under the assumption that errors of De and se are uncorrelated.
(3) absolute error propagation
se(De)[Gy] = abs(DR[Gy/s] ∗ se(De)[s]) + abs(De[s] ∗ se(DR)[Gy/s])
Applicable under the assumption that errors of De and se are not uncorrelated.
Value
Returns a data.frame with converted values.
Function version
0.6.0 (2018-01-21 17:22:38)
How to cite
Kreutzer, S., Dietze, M., Fuchs, M.C. (2019). Second2Gray(): Converting equivalent dose values from seconds (s) to gray (Gy). Function version 0.6.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence

set_Risoe.BINfileData

269

Note
If no or a wrong error propagation method is given, the execution of the function is stopped. Furthermore, if a data.frame is provided for the dose rate values is has to be of the same length as the
data frame provided with the argument data
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
Michael Dietze, GFZ Potsdam (Germany)
Margret C. Fuchs, HZDR, Helmholtz-Institute Freiberg for Resource Technology (Germany)
R Luminescence Package Team
References
Aitken, M.J., 1985. Thermoluminescence dating. Academic Press.
See Also
calc_SourceDoseRate
Examples
##(A) for known source dose rate at date of measurement
## - load De data from the example data help file
data(ExampleData.DeValues, envir = environment())
## - convert De(s) to De(Gy)
Second2Gray(ExampleData.DeValues$BT998, c(0.0438,0.0019))

##(B) for source dose rate calibration data
## - calculate source dose rate first
dose.rate <- calc_SourceDoseRate(measurement.date = "2012-01-27",
calib.date = "2014-12-19",
calib.dose.rate = 0.0438,
calib.error = 0.0019)
# read example data
data(ExampleData.DeValues, envir = environment())
# apply dose.rate to convert De(s) to De(Gy)
Second2Gray(ExampleData.DeValues$BT998, dose.rate)

set_Risoe.BINfileData General accessor function for RLum S4 class objects

Description
Function calls object-specific get functions for RisoeBINfileData S4 class objects.

270

set_RLum

Usage
set_Risoe.BINfileData(METADATA = data.frame(), DATA = list(),
.RESERVED = list())
Arguments
METADATA

x

DATA

x

.RESERVED

x

Details
The function provides a generalised access point for specific Risoe.BINfileData objects.
Depending on the input object, the corresponding get function will be selected. Allowed arguments
can be found in the documentations of the corresponding Risoe.BINfileData class.
Value
Return is the same as input objects as provided in the list.
Function version
0.1 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). set_Risoe.BINfileData(): General accessor function for RLum S4 class objects.
Function version 0.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
Risoe.BINfileData

set_RLum

General set function for RLum S4 class objects

Description
Function calls object-specific set functions for RLum S4 class objects.
Usage
set_RLum(class, originator, .uid = create_UID(), .pid = NA_character_,
...)

set_RLum

271

Arguments
class

RLum (required): name of the S4 class to create

originator

character (automatic): contains the name of the calling function (the function
that produces this object); can be set manually.

.uid

character (automatic): sets an unique ID for this object using the internal C++
function create_UID.

.pid

character (with default): option to provide a parent id for nesting at will.

...

further arguments that one might want to pass to the specific set method

Details
The function provides a generalised access point for specific RLum objects.
Depending on the given class, the corresponding method to create an object from this class will be
selected. Allowed additional arguments can be found in the documentations of the corresponding
RLum class:
• RLum.Data.Curve,
• RLum.Data.Image,
• RLum.Data.Spectrum,
• RLum.Analysis,
• RLum.Results
Value
Returns an object of the specified class.
Function version
0.3.0 (2018-01-21 17:22:38)
How to cite
Kreutzer, S. (2019). set_RLum(): General set function for RLum S4 class objects. Function version
0.3.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J.
(2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version
0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
RLum.Data.Curve, RLum.Data.Image, RLum.Data.Spectrum, RLum.Analysis, RLum.Results

272

smooth_RLum

Examples
##produce empty objects from each class
set_RLum(class = "RLum.Data.Curve")
set_RLum(class = "RLum.Data.Spectrum")
set_RLum(class = "RLum.Data.Spectrum")
set_RLum(class = "RLum.Analysis")
set_RLum(class = "RLum.Results")
##produce a curve object with arbitrary curve values
object <- set_RLum(
class = "RLum.Data.Curve",
curveType = "arbitrary",
recordType = "OSL",
data = matrix(c(1:100,exp(-c(1:100))),ncol = 2))
##plot this curve object
plot_RLum(object)

smooth_RLum

Smoothing of data

Description
Function calls the object-specific smooth functions for provided RLum S4-class objects.
Usage
smooth_RLum(object, ...)
## S4 method for signature 'list'
smooth_RLum(object, ...)
Arguments
object

RLum (required): S4 object of class RLum

...

further arguments passed to the specifc class method

Details
The function provides a generalised access point for specific RLum objects.
Depending on the input object, the corresponding function will be selected. Allowed arguments can
be found in the documentations of the corresponding RLum class. The smoothing is based on an
internal function called .smoothing.
Value
An object of the same type as the input object is provided
Methods (by class)
• list: Returns a list of RLum objects that had been passed to smooth_RLum

sTeve

273

Function version
0.1.0 (2018-01-30 16:13:33)
How to cite
Kreutzer, S. (2019). smooth_RLum(): Smoothing of data. Function version 0.1.0. In: Kreutzer, S.,
Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence:
Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence
Note
Currenlty only RLum objects of class RLum.Data.Curve and RLum.Analysis (with curve data) are
supported!
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
RLum.Data.Curve, RLum.Analysis
Examples
##load example data
data(ExampleData.CW_OSL_Curve, envir = environment())
##create RLum.Data.Curve object from this example
curve = Θ
With Θ an arbitray, user defined, threshold. Values above the threshold indicating curves comprising
a signal.
Note: the absolute difference of E(X) and V ar(x) instead of the ratio was chosen as both terms
can become 0 which would result in 0 or Inf, if the ratio is calculated.
Value
The function returns
———————————–
[ NUMERICAL OUTPUT ]
———————————–
RLum.Results-object
slot:****@data
Element
$unique_pairs
$selection_id
$selection_full

Type
data.frame
numeric
data.frame

Description
the unique position and grain pairs
the selection as record ID
implemented models used in the baSAR-model core

slot:****@info
The original function call
Output variation
For cleanup = TRUE the same object as the input is returned, but cleaned up (invalid curves were
removed). This means: Either an Risoe.BINfileData or an RLum.Analysis object is returned in

verify_SingleGrainData

283

such cases. An Risoe.BINfileData object can be exported to a BIN-file by using the function
write_R2BIN.
Function version
0.2.1 (2019-02-15 02:31:16)
How to cite
Kreutzer, S. (2019). verify_SingleGrainData(): Verify single grain data sets and check for invalid grains, i.e. zero-light level grains. Function version 0.2.1. In: Kreutzer, S., Burow, C.,
Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6. https://CRAN.Rproject.org/package=Luminescence
Note
This function can work with Risoe.BINfileData objects or RLum.Analysis objects (or a list of it).
However, the function is highly optimised for Risoe.BINfileData objects as it make sense to remove
identify invalid grains before the conversion to an RLum.Analysis object.
The function checking for invalid curves works rather robust and it is likely that Reg0 curves within
a SAR cycle are removed as well. Therefore it is strongly recommended to use the argument
cleanup = TRUE carefully.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
Risoe.BINfileData, RLum.Analysis, write_R2BIN, read_BIN2R
Examples
##01 - basic example I
##just show how to apply the function
data(ExampleData.XSYG, envir = environment())
##verify and get data.frame out of it
verify_SingleGrainData(OSL.SARMeasurement$Sequence.Object)$selection_full
##02 - basic example II
data(ExampleData.BINfileData, envir = environment())
id <- verify_SingleGrainData(object = CWOSL.SAR.Data,
cleanup_level = "aliquot")$selection_id
## Not run:
##03 - advanced example I
##importing and exporting a BIN-file
##select and import file
file <- file.choose()
object <- read_BIN2R(file)

284

write_R2BIN

##remove invalid aliquots(!)
object <- verify_SingleGrainData(object, cleanup = TRUE)
##export to new BIN-file
write_R2BIN(object, paste0(dirname(file),"/", basename(file), "_CLEANED.BIN"))
## End(Not run)

write_R2BIN

Export Risoe.BINfileData into Risø BIN/BINX-file

Description
Exports a Risoe.BINfileData object in a *.bin or *.binx file that can be opened by the Analyst
software or other Risoe software.
Usage
write_R2BIN(object, file, version, compatibility.mode = FALSE,
txtProgressBar = TRUE)
Arguments
object

Risoe.BINfileData (required): input object to be stored in a bin file.

file

character (required): file name and path of the output file
• [WIN]: write_R2BIN(object,"C:/Desktop/test.bin")
• [MAC/LINUX]: write_R2BIN("/User/test/Desktop/test.bin")

version

character (optional): version number for the output file. If no value is provided
the highest version number from the Risoe.BINfileData is taken automatically.
Note: This argument can be used to convert BIN-file versions.
compatibility.mode
logical (with default): this option recalculates the position values if necessary
and set the max. value to 48. The old position number is appended as comment
(e.g., ’OP: 70). This option accounts for potential compatibility problems with
the Analyst software. It further limits the maximum number of points per curve
to 9,999. If a curve contains more data the curve data got binned using the
smallest possible bin width.

txtProgressBar logical (with default): enables or disables txtProgressBar.
Details
The structure of the exported binary data follows the data structure published in the Appendices of
the Analyst manual p. 42.
If LTYPE, DTYPE and LIGHTSOURCE are not of type character, no transformation into numeric values
is done.
Value
Write a binary file.

write_R2BIN

285

Function version
0.5.1 (2019-03-07 12:45:56)
How to cite
Kreutzer, S. (2019). write_R2BIN(): Export Risoe.BINfileData into Risø BIN/BINX-file. Function version 0.5.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer,
M., Friedrich, J. (2019). Luminescence: Comprehensive Luminescence Dating Data Analysis. R
package version 0.9.1.6. https://CRAN.R-project.org/package=Luminescence
Note
The function just roughly checks the data structures. The validity of the output data depends on the
user.
The validity of the file path is not further checked. BIN-file conversions using the argument version
may be a lossy conversion, depending on the chosen input andoutput data (e.g., conversion from
version 08 to 07 to 06 to 05 to 04 or 03).
Warning
Although the coding was done carefully it seems that the BIN/BINX-files produced by Risø DA
15/20 TL/OSL readers slightly differ on the byte level. No obvious differences are observed in the
METADATA, however, the BIN/BINX-file may not fully compatible, at least not similar to the once
directly produced by the Risoe readers!
ROI definitions (introduced in BIN-file version 8) are not supported! There are furthermore ignored
by the function read_BIN2R.
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France)
R Luminescence Package Team
References
DTU Nutech, 2016. The Squence Editor, Users Manual, February, 2016. http://www.nutech.
dtu.dk/english/products-and-services/radiation-instruments/tl_osl_reader/manuals
See Also
read_BIN2R, Risoe.BINfileData, writeBin
Examples
## Not run:
##load exampled dataset
data(ExampleData.BINfileData, envir = environment())
##create temporary filepath
##(for usage replace by own path)
temp_file <- temp_file <- tempfile(pattern = "output", fileext = ".bin")
##export to temporary file path
write_R2BIN(CWOSL.SAR.Data, file = temp_file)

286

write_RLum2CSV

## End(Not run)

write_RLum2CSV

Export RLum-objects to CSV

Description
This function exports RLum-objects to CSV-files using the R function utils::write.table. All RLumobjects are supported, but the export is lossy, i.e. the pure numerical values are exported only.
Information that cannot be coerced to a data.frame or a matrix are discarded as well as metadata.
Usage
write_RLum2CSV(object, path = NULL, prefix = "", export = TRUE,
compact = TRUE, ...)
Arguments
object

RLum or a list of RLum objects (required): objects to be written

path

character (optional): character string naming folder for the output to be written.
If nothing is provided path will be set to the working directory. Note: this
argument is ignored if the the argument export is set to FALSE.

prefix

character (with default): optional prefix to name the files. This prefix is valid for
all written files

export

logical (with default): enable or disable the file export. If set to FALSE nothing
is written to the file connection, but a list comprising objects of type data.frame
and matrix is returned instead

compact

logical (with default): if TRUE (the default) the output will be more simple but
less comprehensive, means not all elements in the objects will be fully broken
down. This is in particular useful for writing RLum.Results objects to CSVfiles, such objects can be rather complex and not all information are needed in a
CSV-file or can be meaningful translated to it.

...

further arguments that will be passed to the function utils::write.table. All arguments except the argument file are supported

Details
However, in combination with the implemented import functions, nearly every supported import
data format can be exported to CSV-files, this gives a great deal of freedom in terms of compatibility
with other tools.
Input is a list of objects
If the input is a list of objects all explicit function arguments can be provided as list.
Value
The function returns either a CSV-file (or many of them) or for the option export == FALSE a list
comprising objects of type data.frame and matrix

write_RLum2CSV

287

Function version
0.2.0 (2019-02-13 19:55:51)
How to cite
Kreutzer, S. (2019). write_RLum2CSV(): Export RLum-objects to CSV. Function version 0.2.0.
In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2019).
Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.1.6.
https://CRAN.R-project.org/package=Luminescence
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, UMR 5060, CNRS - Université Bordeaux Montaigne (France)
R Luminescence Package Team
See Also
RLum.Analysis, RLum.Data, RLum.Results, utils::write.table
Examples
##transform values to a list (and do not write)
data(ExampleData.BINfileData, envir = environment())
object <- Risoe.BINfileData2RLum.Analysis(CWOSL.SAR.Data)[[1]]
write_RLum2CSV(object, export = FALSE)
## Not run:
##create temporary filepath
##(for usage replace by own path)
temp_file <- tempfile(pattern = "output", fileext = ".csv")
##write CSV-file to working directory
write_RLum2CSV(temp_file)
## End(Not run)

Index
calc_FadingCorr, 67
calc_gSGC, 78
calc_Huntley2006, 81
calc_Kars2008, 88
calc_Lamothe2003, 90
calc_OSLLxTxRatio, 100
calc_Statistics, 106
calc_ThermalLifetime, 108
calc_TLLxTxRatio, 111
fit_EmissionSpectra, 159
fit_SurfaceExposure, 169
plot_FilterCombinations, 206
scale_GammaDose, 263
verify_SingleGrainData, 281
∗Topic datasets
BaseDataSet.ConversionFactors, 49
BaseDataSet.CosmicDoseRate, 50
BaseDataSet.FractionalGammaDose,
52
ExampleData.Al2O3C, 135
ExampleData.BINfileData, 136
ExampleData.CW_OSL_Curve, 137
ExampleData.DeValues, 138
ExampleData.Fading, 139
ExampleData.portableOSL, 144
ExampleData.RLum.Analysis, 144
ExampleData.RLum.Data.Image, 145
ExampleData.ScaleGammaDose, 146
ExampleData.SurfaceExposure, 146
ExampleData.TR_OSL, 149
ExampleData.XSYG, 150
extdata, 152
∗Topic dplot
Analyse_SAR.OSLdata, 39
calc_FuchsLang2001, 76
fit_CWCurve, 155
fit_LMCurve, 162
plot_DRTResults, 203
plot_Risoe.BINfileData, 226
plot_RLum, 229
∗Topic manip
apply_CosmicRayRemoval, 44
apply_EfficiencyCorrection, 46

∗Topic IO
convert_Activity2Concentration,
114
convert_BIN2CSV, 116
convert_Daybreak2CSV, 117
convert_PSL2CSV, 118
convert_RLum2Risoe.BINfileData,
119
convert_Wavelength2Energy, 120
convert_XSYG2CSV, 123
extract_IrradiationTimes, 153
merge_Risoe.BINfileData, 184
PSL2Risoe.BINfileData, 243
read_BIN2R, 244
read_Daybreak2R, 246
read_PSL2R, 248
read_RF2R, 249
read_SPE2R, 250
read_XSYG2R, 253
write_R2BIN, 284
write_RLum2CSV, 286
∗Topic aplot
plot_FilterCombinations, 206
plot_RLum.Analysis, 230
plot_RLum.Data.Curve, 232
plot_RLum.Data.Image, 234
plot_RLum.Data.Spectrum, 235
plot_RLum.Results, 239
∗Topic classes
RLum-class, 262
∗Topic datagen
analyse_Al2O3C_CrossTalk, 7
analyse_Al2O3C_ITC, 9
analyse_Al2O3C_Measurement, 12
analyse_baSAR, 14
analyse_FadingMeasurement, 21
analyse_IRSAR.RF, 24
analyse_pIRIRSequence, 31
analyse_portableOSL, 34
analyse_SAR.CWOSL, 35
Analyse_SAR.OSLdata, 39
analyse_SAR.TL, 42
calc_AverageDose, 56
288

INDEX
calc_SourceDoseRate, 104
CW2pHMi, 124
CW2pLM, 128
CW2pLMi, 129
CW2pPMi, 132
extract_IrradiationTimes, 153
merge_Risoe.BINfileData, 184
Risoe.BINfileData2RLum.Analysis,
260
Second2Gray, 267
sTeve, 273
tune_Data, 278
verify_SingleGrainData, 281
∗Topic models
fit_CWCurve, 155
fit_LMCurve, 162
∗Topic package
Luminescence-package, 5
∗Topic plot
analyse_pIRIRSequence, 31
analyse_portableOSL, 34
analyse_SAR.CWOSL, 35
analyse_SAR.TL, 42
∗Topic utilities
bin_RLum.Data, 53
get_Risoe.BINfileData, 178
get_RLum, 179
length_RLum, 183
merge_RLum, 186
names_RLum, 189
replicate_RLum, 256
set_Risoe.BINfileData, 269
set_RLum, 270
smooth_RLum, 272
structure_RLum, 274
abline, 231
analyse_Al2O3C_CrossTalk, 7, 135, 136
analyse_Al2O3C_ITC, 9, 9, 14, 135, 136
analyse_Al2O3C_Measurement, 12, 135, 136
analyse_baSAR, 14
analyse_FadingMeasurement, 21, 23, 68, 83,
88
analyse_IRSAR.RF, 24, 250
analyse_pIRIRSequence, 31, 41, 90, 91, 198,
199
analyse_portableOSL, 34
analyse_SAR.CWOSL, 31–33, 35, 41, 90, 91,
103, 198–200, 202
Analyse_SAR.OSLdata, 38, 39, 103
analyse_SAR.TL, 42, 112
app_RLum, 47
apply_CosmicRayRemoval, 44, 46

289
apply_EfficiencyCorrection, 46
approx, 126, 206, 208, 254, 255, 267
array, 109
as, 48
as.data.frame, 277
barplot, 264, 267
base::readBin, 246
BaseDataSet.ConversionFactors, 49
BaseDataSet.CosmicDoseRate, 50, 66
BaseDataSet.FractionalGammaDose, 52
bibentry, 279
bin_RLum.Data, 53
boxplot, 241, 242
boxplot.default, 20
browseURL, 259
calc_AliquotSize, 54
calc_AverageDose, 56
calc_CentralDose, 59, 63, 76, 78, 87, 94, 98,
114
calc_CommonDose, 61, 61, 76, 78, 87, 94, 98
calc_CosmicDoseRate, 63
calc_FadingCorr, 22, 67, 90, 91
calc_FastRatio, 71
calc_FiniteMixture, 61, 63, 73, 78, 87, 94,
98
calc_FuchsLang2001, 61, 63, 76, 76, 87, 94,
98, 114
calc_gSGC, 78
calc_HomogeneityTest, 80
calc_Huntley2006, 81, 88
calc_Huntley2006(), 89
calc_IEU, 86
calc_Kars2008, 88
calc_Lamothe2003, 90
calc_MaxDose, 92, 98
calc_MinDose, 61, 63, 76, 78, 87, 92–94, 95
calc_OSLLxTxRatio, 16, 17, 19, 20, 24, 33,
37, 38, 40, 41, 100
calc_SourceDoseRate, 104, 268, 269
calc_Statistics, 106, 191, 203, 217, 242
calc_ThermalLifetime, 108
calc_TLLxTxRatio, 43, 44, 111
calc_WodaFuchs2008, 113
call, 32, 55, 60, 62, 65, 74, 77, 79, 80, 87, 97,
164, 208, 280
character, 8, 10, 12, 15, 16, 18, 22, 25, 26,
31, 36, 40, 42, 44, 48, 57, 58, 69, 73,
74, 78, 83, 88, 101, 104, 107, 108,
114, 116–118, 123, 153, 156, 159,
162, 163, 175, 177, 179, 181, 184,
188–192, 198, 203, 204, 209, 214,

290
217, 220, 222, 223, 227, 231, 234,
236, 237, 241, 244, 245, 247–249,
251, 253, 257, 258, 260–264, 268,
271, 276, 279, 280, 282, 284, 286
coda::mcmc.list, 19
confint, 156, 157, 163, 164
contour, 238
convert_Activity2Concentration, 114
convert_BIN2CSV, 116
convert_Daybreak2CSV, 117
convert_PSL2CSV, 118
convert_RLum2Risoe.BINfileData, 119
convert_Wavelength2Energy, 120, 161, 237,
238
convert_XSYG2CSV, 123
CW2pHMi, 124, 129, 131, 134, 228
CW2pLM, 126, 128, 131, 134, 162, 228
CW2pLMi, 126, 129, 129, 134, 228
CW2pPMi, 126, 129, 131, 132, 228
data.frame, 22, 32, 37, 38, 40, 43, 46, 48, 55,
57, 59, 60, 62, 65, 69, 71–80, 82, 84,
86, 87, 90, 92, 95, 97, 101, 107, 111,
113, 114, 116–118, 120, 121, 123,
124, 128, 130, 132, 136, 138, 139,
141, 143, 146, 147, 150, 156, 157,
162, 164, 166, 169, 170, 173, 181,
190, 202, 203, 206, 209, 214, 217,
219, 222, 241, 245, 254, 263, 264,
268, 275, 278, 279, 286
data.table::data.table, 247
Date, 104
density, 217, 218
DEoptim::DEoptim, 169
DEoptim::DEoptim.control, 167
devtools::install_github, 183
ExampleData.Al2O3C, 135
ExampleData.BINfileData, 136
ExampleData.CW_OSL_Curve, 137
ExampleData.DeValues, 138
ExampleData.Fading, 139
ExampleData.FittingLM, 141
ExampleData.LxTxData, 141
ExampleData.LxTxOSLData, 143
ExampleData.portableOSL, 144
ExampleData.RLum.Analysis, 144
ExampleData.RLum.Data.Image, 145
ExampleData.ScaleGammaDose, 146, 267
ExampleData.SurfaceExposure, 146, 172
ExampleData.TR_OSL, 149
ExampleData.XSYG, 150
expression, 212

INDEX
extdata, 152
extract_IrradiationTimes, 24, 153
fit_CWCurve, 71, 72, 155, 165
fit_EmissionSpectra, 159
fit_LMCurve, 126, 129, 131, 134, 158, 162
fit_OSLLifeTimes, 150, 166
fit_SurfaceExposure, 146, 169
fit_ThermalQuenching, 172
formula, 38
get_Layout, 175
get_Quote, 176
get_rightAnswer, 177
get_Risoe.BINfileData, 178
get_RLum, 8, 10, 12, 29, 30, 32, 33, 38, 43, 44,
55, 60, 62, 65, 70, 72, 75, 79, 80, 87,
97, 103, 105, 110, 153, 158, 165,
179, 180, 212, 230, 251, 280
get_RLum,list-method (get_RLum), 179
get_RLum,NULL-method (get_RLum), 179
GitHub-API, 180
github_branches (GitHub-API), 180
github_commits (GitHub-API), 180
github_issues (GitHub-API), 180
glm, 163
graphics::boxplot, 241
graphics::grid, 207
graphics::hist, 57, 59
graphics::legend, 25, 207
graphics::matplot, 110
hist, 215, 216
install_DevelopmentVersion, 182
integer, 16, 18, 22, 26, 31, 36, 42, 44, 45, 57,
58, 68, 78, 101, 104, 107, 111, 121,
160, 162, 181, 184, 192, 198, 200,
210, 220, 230, 236, 245, 256, 262,
274, 276
legend, 220, 241
length_RLum, 183
list, 8–10, 12, 13, 15, 16, 18, 22, 25, 28, 31,
32, 36, 37, 40, 42, 44, 48, 49, 52, 55,
57, 60, 62, 65, 72, 74, 77–80, 87, 97,
102, 105, 108, 111, 119, 120, 138,
139, 147, 153, 159, 164, 166, 169,
170, 173, 175, 179, 181, 186, 188,
198, 200, 202, 206, 219, 229–231,
244, 245, 247, 253, 256, 262, 277,
279, 280, 286
list.files, 245, 246

INDEX
lm, 125, 126, 129, 130, 133, 211, 212
logical, 8, 10, 12, 13, 16, 22, 25, 26, 31, 34,
36, 40, 45, 54, 57, 60, 62, 64, 68, 71,
73, 74, 77, 78, 80, 82, 83, 87, 90, 92,
93, 95, 101, 107–109, 113, 114, 119,
121, 153, 156, 159, 160, 162, 163,
166, 167, 170, 173, 174, 177, 179,
181, 183, 184, 188, 190–192, 198,
200, 203, 204, 206, 209, 210, 214,
217, 220, 222, 223, 231, 233, 234,
236, 237, 240, 241, 244, 245, 247,
248, 251, 253, 257, 261, 263, 264,
276, 279, 281, 282, 284, 286
Luminescence (Luminescence-package), 5
Luminescence-package, 5
Luminescence::github_branches, 183
Luminescence::plot_GrowthCurve, 83
matrix, 48, 75, 109, 116–118, 120, 121, 123,
157, 159, 166, 206, 219, 236, 241,
286
max.col, 160
merge_Risoe.BINfileData, 184, 246
merge_RLum, 186
methods::as, 49
methods::language-class, 29
methods_RLum, 263
minpack.lm::nls.lm, 160, 161, 167, 169
minpack.lm::nlsLM, 27, 30, 83, 84, 158, 165,
167, 170–172, 174, 175, 210, 212
mle2, 97
model_LuminescenceSignals, 187
mtext, 214
names_RLum, 189, 189
names_RLum,list-method (names_RLum), 189
nlminb, 96
nls, 26, 28, 30, 155–158, 162, 164, 165, 210,
212
numeric, 8, 10, 12, 13, 15, 16, 18, 25–27, 31,
36, 40, 42, 45, 54, 57, 60, 62, 64, 68,
69, 71, 73, 74, 76, 82–84, 86, 90, 92,
93, 95, 97, 101, 104, 107–109, 113,
156, 159, 162, 166, 167, 170, 173,
174, 188, 190–192, 198, 200, 203,
204, 206, 210, 214, 217, 222, 223,
227, 236, 241, 244, 260, 263, 264,
268, 278, 281
pander::openFileInOS, 259
pander::pander_return, 259
par, 220
pchisq, 81

291
pdf, 231, 240
persp, 237, 238
plot, 61, 77, 78, 83, 87, 156, 158, 165, 170,
197, 199, 204, 205, 215–218, 220,
225, 231–233, 235, 238, 240–242
plot.default, 42, 109, 166, 188, 198, 241
plot_AbanicoPlot, 107, 190
plot_DetPlot, 197
plot_DRCSummary, 200
plot_DRTResults, 203
plot_FilterCombinations, 206
plot_GrowthCurve, 10, 11, 16, 17, 19, 20, 31,
33, 37, 38, 41, 42, 44, 83, 84, 90, 91,
103, 209
plot_Histogram, 194, 214, 225
plot_KDE, 194, 216, 225, 274
plot_NRt, 219
plot_RadialPlot, 194, 222
plot_Risoe.BINfileData, 226
plot_RLum, 105, 122, 151, 161, 229, 232, 233,
235, 238, 240
plot_RLum.Analysis, 151, 229, 230, 230
plot_RLum.Data.Curve, 229, 230, 232, 232
plot_RLum.Data.Image, 229, 230, 234
plot_RLum.Data.Spectrum, 151, 229, 230,
235
plot_RLum.Results, 229, 230, 239
plot_ViolinPlot, 241
plotly::plot_ly, 238
profile, 157
profile.mle2, 97
PSL2Risoe.BINfileData, 243
raster, 234
raster::contour, 234
raster::plot, 234
raster::plotRGB, 234
raster::raster, 234, 235, 252
raw, 245
read.table, 59
read_BIN2R, 16, 17, 19, 20, 24, 39, 41, 116,
117, 154, 155, 185, 226–228, 244,
261, 283, 285
read_Daybreak2R, 117, 118, 246
read_PSL2R, 34, 118, 119, 243, 248
read_RF2R, 249
read_SPE2R, 145, 235, 250
read_XSYG2R, 24, 123, 124, 135, 149–151,
153–155, 253
readBin, 252
readxl::read_excel, 16, 18–20
regex, 253
replicate_RLum, 256

292
replicate_RLum,RLum-method
(RLum-class), 262
report_RLum, 257
Risoe.BINfileData, 15, 17, 38–41, 119, 120,
136, 155, 178, 179, 184, 185, 227,
228, 243, 245, 246, 260, 261, 270,
281–285
Risoe.BINfileData2RLum.Analysis, 245,
260
rjags::coda.samples, 20
rjags::jags.model, 18, 20
RLum, 48, 179, 180, 183, 186, 189, 229, 256,
262, 271, 272, 275, 286
RLum-class, 262
RLum.Analysis, 8, 9, 12, 15, 22, 25, 30, 31,
33–38, 42, 44, 46, 48, 71, 72,
117–120, 124, 135, 144, 150, 151,
153–155, 166, 179, 180, 184, 186,
187, 190, 198, 219, 220, 229, 230,
243, 245–250, 253–255, 261–263,
271, 273, 275, 281–283, 287
RLum.Data, 53, 117–119, 124, 262, 263, 287
RLum.Data.Curve, 35, 48, 53, 71, 72, 101,
103, 111, 119, 120, 124, 126,
128–132, 134, 144, 149, 156, 158,
162, 166, 179, 180, 184, 186, 187,
190, 220, 229–231, 233, 243,
247–250, 255, 262, 263, 271, 273,
275
RLum.Data.Image, 49, 145, 179, 180, 184,
187, 190, 229, 230, 234, 235, 251,
262, 263, 271, 275
RLum.Data.Spectrum, 44, 46, 47, 49, 53,
120–122, 150, 151, 159, 161, 179,
180, 184, 187, 190, 229, 230,
236–238, 251, 252, 262, 263, 271,
275
RLum.Results, 8, 12, 15, 17, 23, 30, 32, 33,
35, 37, 38, 43, 44, 49, 55, 57, 59, 60,
62, 65, 68–70, 72–74, 76–80, 84,
86–88, 90–92, 95, 97, 102, 105, 107,
109, 111–113, 117–119, 124, 154,
155, 157, 158, 161, 179, 180, 184,
186, 187, 190, 198, 200–203, 208,
212, 214, 217, 222, 229, 230, 240,
241, 262, 263, 268, 271, 275, 279,
287
RLumModel::model_LuminescenceSignals,
187
RLumModel::RLumModel-package, 187
RLumShiny::app_RLum, 47
RLumShiny::RLumShiny-package, 47

INDEX
rmarkdown::render, 257, 259
rollmean, 220
rstudioapi::viewer, 259
rug, 242
scale_GammaDose, 263
sd, 211
Second2Gray, 104, 105, 267
set.seed, 68, 69
set_Risoe.BINfileData, 269
set_RLum, 262, 270
shiny::runApp, 48
smooth, 44–46
smooth.spline, 44–46, 220
smooth_RLum, 272, 272
smooth_RLum,list-method (smooth_RLum),
272
stats::approx, 46
stats::density, 241, 242
stats::embed, 160
stats::lm, 23
stats::nls, 23, 174
stats::qf, 167
stats::rnorm, 110
stats::uniroot, 68
sTeve, 273
structure_RLum, 274, 275
structure_RLum,list-method
(structure_RLum), 274
summary, 157, 164
template_DRAC, 276
tune_Data, 278
txtProgressBar, 68, 245, 247, 251, 261, 284
uniroot, 68, 70, 79, 211, 212
use_DRAC, 114, 279
utils::txtProgressBar, 246
utils::write.table, 117–119, 124, 286,
287
vector, 15, 22, 25, 31, 34, 39, 40, 42, 68, 101,
124, 130, 132, 156, 174, 227, 236,
245, 251, 260
verify_SingleGrainData, 17, 18, 20, 281
write_R2BIN, 119, 120, 153–155, 185, 243,
246, 283, 284
write_RLum2CSV, 116–119, 123, 124, 286
writeBin, 285
xml, 253, 255
zoo::rollmean, 233



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 292
Page Mode                       : UseOutlines
Author                          : 
Title                           : 
Subject                         : 
Creator                         : LaTeX with hyperref package
Producer                        : pdfTeX-1.40.19
Create Date                     : 2019:04:27 16:35:47+02:00
Modify Date                     : 2019:04:27 16:35:47+02:00
Trapped                         : False
PTEX Fullbanner                 : This is pdfTeX, Version 3.14159265-2.6-1.40.19 (TeX Live 2018) kpathsea version 6.3.0

EXIF Metadata provided by EXIF.tools