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):
Internals:
• Package size significantly reduced by excluding the
XSYG-file used for buildung the vignette.
Changes in version 0.8.1 (March 9th, 2018):
New functions:
• ‘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.
Internals:
• 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):
New functions:
• ‘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.
Internals:
• Add new vignette 'Analyse Al2O3:C Measurements'
• Add new vignette 'Analyse post-IR IRSL Measurements'
Internals:
• 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.