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.
NEWS for the R Package Luminescence
Changes in version 0.8.6 (October 5th, 2018):
Bugfixes and changes:
• ‘analyse_Al2O3C_Measurement()’ • The argument ‘signal_integral’ was not treated correctly; fixed, • Set threshold for wrong stimulation power detection from 0.01 to 0.05, otherwise it fires to oftern in false positive cases. • ‘analyse_SAR.CWOSL())’ • The function crashed for only noise like data yielding negative Lx/Tx values (reported by Dirk Mittelstraß); fixed, • In the output ‘data.frame’ containg the De values, the column 'RC.Status' was of type ‘factor’, but should have been of type ‘character’; fixed. • ‘analyse_pIRIRMeasurement()’ • If measurements did not contain TL curves, the function showed a confusing warnings message; fixed. • ‘plot_DetPlot()’ • Function does not break anymore if ‘signal.integral.min == signal.integral.max’ (reported by Andrea Junge). • ‘plot_KDE()’ • The function could not handle ‘Inf’ values (#71) as reported by Dirk Mittelstraß; fixed. • The function could not handle ‘data.frames’ with more than 2 columns and ‘NA’ values in the unused columns (reported by Dirk Mittelstraß). Now the function takes only the first two columns. • ‘plot_GrowthCurve()’ • The function crashed due to problems with the start parameter estimation for negative Lx/Tx values (reported by Dirk Mittelstaß); fixed. • ‘plot_RadialPlot()’ • The function now uses only the first two columns from a ‘data.frame’, regardless its size. • ‘report_RLum()’ • Add new argument ‘show_report’ to allow file creation only without getting the RStudio viewer involved.
Changes in version 0.8.5 (June 8th, 2018):
Bugfixes and changes:
• ‘analyse_Al2O3C_Measurement()’ • The cross-talk value was erroneously substracted the dose point values instead from the final De, the effect is small, but still, it was not correct; fixed, • add new argument ‘calculate_TL_dose’ which allows to experimentally calculate the apparent dose based on the TL curves. This feature may help in certain cases to cross-check the results obtained with the GSL, • the manual was not complete and the reference wrong, fixed. • ‘analyse_baSAR()’ • Add support for ‘RLum.Analysis’-objects as input, • correct odd message informing about removed aliquots that had been never removed, • add new argument ‘distribution_plot’ to allow a manual selection of the frequentist distribution plot output. • ‘analyse_SAR.CWOSL()’ • A newly introduced typo caused a function crash; fixed. • ‘bin.RLum.Data.Curve()’ • The method was not passing the argument ‘bin_size’ properly; fixed.
Changes in version 0.8.4 (April 20th, 2018):
Bugfixes and changes:
• The previous package versions did not pass the CRAN tests on the Solaris platform; fixed.
Changes in version 0.8.3 (April 20th, 2018):
Bugfixes and changes:
• ‘analyse_SAR.CWOSL()’ • The function crashed if the ‘plot_GrowthCurve()’ returned ‘NULL’; fixed, • ff the dose-response curve was not fitted, but ‘plot’ was set to ‘TRUE’ no plot was returned (even no empty plot); fixed, • if all curves were IRSL curves, the function crashed while trying to plot the IRSL curve for the IRSL test. Now only the last IRSL curve is plotted. This does not make really sense since probably the user did not measure quartz, however, this solution fixes the problem and does not break other users code. • ‘analyse_FiniteMixture()’ • For wrong user input and not well understood assumptions, the function crashed uncontrolled; fixed. • ‘analyse_pIRIRSequence()’ • Fixed unwanted functions crashes for very odd datasets (e.g., ‘Inf’ values). • ‘convert_RLum2Risoe.BINfileData()’ • The record type was not correclty extracted, fixed, • the conversion now keeps the original position numbers instead of assigning new. • ‘plot_GrowthCurve()’ • If number of regeneration points was reduced for plotting and fitting, an unwanted warning message appeared due to a coding error, • if the D0 values is precisely 0.0000, the fit probably went wrong, in such cases now another attempt is made, • if a value for Lx/Tx is 0 now the value is set to ‘.Machine$double.eps’, instead of 0.001, • the formula output for ‘EXP+EXP’ was not correct, fixed. • ‘src_create_RLumDataCurve_matrix()’ • Until today, you probably did not know that this function exists at all. This function is written in C++, working in the back and helps to create ‘RLum.Data.Curve’-objects out of BIN/BINX-files. Recently we became aware of non-conform BIN/BINX-files, circulating in the wild. For such files the TL curves were not created correctly, more important, the user did not know why. Now the function throws out a message, at least.
Changes in version 0.8.2 (March 10th, 2018):
• Package size significantly reduced by excluding the XSYG-file used for buildung the vignette.
Changes in version 0.8.1 (March 9th, 2018):
• ‘calc_Huntley2006()’ • A function to calculate the expected sample specific fraction of saturation based on the model of Huntley (2006) using the approach as implemented in Kars et al. (2008) or Guralnik et al. (2015). This function supersedes the formerly released function 'calc_Kars2008()'. The new function is identical to 'calc_Kars2008()' when 'fit.method = "EXP"' (the default) is used, but also allows fitting a general-order kinetic function after Guralnik et al. (2015) ('fit.method = "GOK"').
Bugfixes and changes:
• ‘calc_Kars2008()’ • This function is now deprecated and will eventually be removed in an upcoming version of the 'Luminescence' package. Older scripts using this function will still work, but it is highly recommended to use the newly introduced function 'calc_Huntley2006()'. • ‘calc_MinDose()’ • Previously, the function globally disabled warning messages via 'options(warn = -1)' due to the overly verbose output of functions in the 'bbmle' package. Globally disabling warning messages may prevent the display of unexpected warnings, however, and in rmarkdown files it wouldn't work anyway. This behaviour was replaced with explicit calls to 'suppressWarnings()' for particular functions. (#66) • Fixed a bug where the function tried to calculate the log of infinite (Inf, -Inf) values, which produced 'NaN' warnings. • ‘get_RLum()’ • The argument ‘subset’ was broken and not working anymore, similar to the S3-method ‘subset’ dispatching to ‘get_RLum’ for ‘RLum.Analysis’-objects. Both issues have been fixed. • ‘plot_DRTResults()’ • If ‘boxplot = TRUE’ and ‘give.dose = NULL’ the plot still showed the abline at 1 including the +/- 10 % error range. Now, the abline is only showed if a numeric value is provided for ‘give.dose’, ‘NULL’ plots no abline. • ‘plot_GrowthCurve()’ • Now allows fitting of the general-order kinetics function after Guralnik et al. (2015). Use ‘"GOK"’ as input for argument ‘fit.method’. • ‘template_DRAC()’ • New argument ‘preset’ to allow the selection of pre-defined templates for various configurations (e.g., ‘'quartz_coarse'’) for quartz coarse grain data. The templates bring pre-filled values to speed up the workflow, however, they do not free the researcher from cross-checking these values.
• Lower required dependent package versions to get the package passed on CRAN. • Further compress example data ... it was not yet the optimum. • Further compress 'vignettes'.
Changes in version 0.8.0 (Feburary 9th, 2018):
• ‘analyse_Al2O3C_ITC()’: Function to analyse data determined to correct irradiation times as suggested by Kreutzer et al., 2018 • ‘analyse_Al2O3C_CrossTalk()’: Function to analyse data to analyse crosstalk measurements as shown in Kreutzer et al., 2018 • ‘analyse_Al2O3C_Measurement()’: Function to analyse Al2O3:C data as shown by Kreutzer et al., 2018 • ‘convert_Activity2Concentration()’: converts nuclide activity data (Bq/kg) to concentrations (ppm or %) and vice versa • ‘convert_RLum2Risoe.BINfileData()’: Function to convert ‘RLum.Analysis’ and ‘RLum.Data.Curve’ objects to ‘Risoe.BINfileData’, which can be exported to BIN/BINX-files using the function ‘write_R2BIN()’. • ‘calc_WodaFuchs2008()’: Function to obtain the equivalent dose using the approach proposed by Woda and Fuchs, 2008. • ‘fit_SurfaceExposure()’: Function to fit eq. 1 in Sohbati et al. (2012a) to OSL surface exposure data and derive estimates of its parameters (i.a., the age). Alternatively, eq. 12 in Sohbati et al. (2012b) can be fitted, which also considers the dose rate. • ‘calc_Lamothe2003()’: Function to support the fading correction suggested by Lamothe et al., 2003. As input the function accepts ‘data.frame’ output from the functions ‘analyse_SAR.CWOSL()’ and ‘analyse_pIRIRSequence)’.
New example data:
• ‘ExampleData.SurfaceExposure’: A set of synthetic OSL surface exposure dating data to demonstrate the fit_SurfaceExposure() functionality. See ?ExampleData.SurfaceExposure for details. • ‘ExampleData.Al2O3C’: Al2O3:C chips measurement data to supplement the newly implemented functions to analyse Al2O3:C data.
S4-classes and methods:
• The ‘RLum.Analysis’ show method failed for ‘RLum.Data.Spectrum’ objects; fixed. • Method for ‘get_RLum’ with signature ‘NULL’ added. Now it returns ‘NULL’. • The coercion from ‘list’ to ‘RLum.Results’ using ‘as()’ did not work; fixed. • Method ‘get_RLum’ for ‘RLum.Analysis’ returned a confusing error if what was provided via 'subset' was not a logical expression; fixed. • ‘structure_RLum()’ and ‘names_RLum()’ each got a method to deal with a list of ‘RLum’ objects.
Bugfixes and changes:
• ‘analyse_SAR.CWOSL()’ • The function gained a new argument ‘'onlyLxTxTable'’. If set to ‘TRUE’ only the Lx/Tx table is returned (including regeneration point sorting). • ‘analyse_IRSAR.RF()’ • Multicore processing now also supports Windows (#47) • Fixed a bug where manually specifying the number of CPU cores via 'method.control = list(cores = x)' was not respected, • mixing of curves (e.g., regenerated first, natural second) led to a crash of the function, even the structure was correctly specified; fixed (#61), • the function will not break anymore uncontrolled of both RF curves are of similar extension on the x-axis. • ‘analyse_pIRIRSequence()’ • If the number of records did not match the sequence structure the function crashed with a confusing error message. Now it shows an error and returns ‘NULL’, • make the argument ‘main’ more powerful if the input is a list, • add missing items to the manual. • ‘calc_HomogeneityTest()’ • The calculation was wrong for the option ‘log = TRUE’ (the default); fixed (#63). • ‘calc_Kars2008()’ • In some cases the calculated LxTx values of the simulated natural dose-response curve were slightly underestimated and its maximum value differed from the individually calculated nN(ss) value. The approach to calculate the natural DRC was changed and now yields a maximum LxTx value indistinguishable from nN(ss). • Numeric output in the plot should now always be inside the plotting frame. • The number of digits for the numeric output in the plot was slightly adjusted. • ‘plot_FilterCombinations()’ • Add interactive mode (‘interactive = TRUE’), • correct wrong visualisation of transmission windows for long or short pass filters, • fix legend error if only one filter was provided (due to a recent matrix behaviour change). • ‘plot_GrowthCurve()’ • The function now turns ‘Inf’ into ‘NA’, • the argument ‘na.rm’ is defunct and should not be used anymore, • minor code modifications to handle special cases such as input values with a ‘data.frame’ with no error column, • extent examples by for test data set by Berger & Huntley (1989), • remove one more confusion warning if the fit did not work. • ‘plot_Historgram()’ • The forwarded argument ‘breaks’ was not treated correctly (#54); fixed. • ‘plot_RLum()’ • The function now supports plotting even of highly nested lists of `RLum-objects`. • ‘plot_RLum.Analysis()’ • The option `col` was not working as expected if `black` was provided; fixed, • setting ‘ylim’ caused a function break (#65); fixed. • ‘read_BIN2R()’ • The function unexpectedly dropped are warning for an unused connection; fixed, • if a file link was provided and the argument ‘pattern’ was set and error was shown; fixed. • ‘read_Daybreak2R()’ • The functions did not work anymore on ASCII files; fixed! • ‘read_XSYG2R()’ • Argument ‘verbose’ added for more consistency with other functions, • the functions now supports the import form files via the internet, • minor modifications to support minimal examples without 'recordType', • give the XSYG-file import a 50% performance boost, • set option `XML_PARSE_HUGE` to allow parsing of larger nodes within the XSYG-file, • the metadata entries ‘curveType’ and ‘parentID’ appeared duplicated, fixed. • ‘read_SPE2R()’ • Add support for internet connections, • fix unclear file extension recognition. • ‘write_R2BIN()’ • The BIN-file export to version 04 failed in very rare cases for ‘NA’ values in the byte position ‘SEQUENCE’; fixed, • the compatibility mode was extended, now limiting the maxmium number of points for one curve to 9,999 (if the option is chosen). This improves the compatibility with older versions of the Analyst.
• Add new vignette 'Analyse Al2O3:C Measurements' • Add new vignette 'Analyse post-IR IRSL Measurements'
• Start supporting RStudio add-ins for more advanced users. • Add fitting test data set by Berger & Huntley (1989) as external data. • The internal documentation now uses 'markdown'. • Internal function `.unlist_RLum()` allows to get rid of nested lists. • Required R version increased to 3.4.0 (patchlevel 0). • Cleanup help index and hide internal functions and methods.