NEWS

---

Luminescence 1.2.1.9000-5

Breaking changes

• In function fit_DoseReponseCurve() we modified how weights are handled. Up to v1.2.1, the default for fit.weights used a normalised inverse standard error approach, under the assumption that uncertainties scale with the dose. In hindsight, this appears to be short-sighted and not very well justified: individual relative uncertainties typically do not scale with the dose, but are independent except in exceptional cases. In consequence, we modified what values fit.weights accepts to accommodate the old and new approach. This has three immediate consequences:
  • The allowed input for fit.weights is no longer logical, but either character, numeric, or NULL (no weights);
  • The numerical output of fit_DoseReponseCurve() will differ, as the new default use inverse variance instead;
  • Users may provide their own weights.

These changes affect the numerical output of the following functions: fit_DoseResponseCurve(), analyse_SAR.CWOSL(), analyse_SAR.TL(), analyse_baSAR(), analyse_pIRIRSequence(), calc_Lamothe2003(), calc_Huntley2006(), plot_DRCSummary(), plot_DetPlot().

Although the changes in the numerical output may be inconvenient, we strongly advise updating regardless. The old results can still be reproduced using option fit.weights = "norm_inverse_std" in the affected functions.

• In function calc_MinDose() we changed how the sigmab argument should be expressed in the log = FALSE case. Up to v1.2.1, it was required to be specified in the same absolute units used for the De values. From now on, it must be expressed in relative units as a ratio (e.g. 0.2 for 20 %). This makes the interpretation of the argument consistent between logged and unlogged models (#1548).

• Plotting an object generated by analyse_SAR.CWOSL() via plot_RLum() (or just plot()) will no longer produce an abanico plot, but will redraw the plots originally created by analyse_SAR.CWOSL(). This will work only for objects generated by the current package version, while the previous behaviour is maintained for objects generated by version up to 1.2.1. In any case, abanico plots can still be created by calling plot_AbanicoPlot() directly (#1589).

New functions

Removed functions and deprecations

Bugfixes and changes

analyse_baSAR()

• The function no longer crashes if a list containing multiple empty objects is provided (#1598).

analyse_SAR.CWOSL()

• The default value for the background_integral argument has changed from NA to NULL. In v1.2.0 NA acquired the distinct meaning “do not subtract the background integral”, so using it as the implicit default changed user-facing behaviour. Switching the default to NULL restores the behaviour present up to v1.1.2, where integrals are applied only when both signal and background integrals are provided, and specifying only the signal integral results in no integrals being applied (#1526).

• The plot_singlePanels argument produced no plots when set to 7 or 8 (#1558).

• The dose.points and dose.points.test arguments are now better validated, and a clearer error message will be reported if misspecified (#1583).

apply_EfficiencyCorrection()

• The argument spectral.efficiency now directly supports a CSV-file input.

calc_Huntley2006()

• The function now requires at least 4 dose points (the natural dose, which is removed before fitting, plus at least 3 others). With fewer points, model fitting can fail or crash, as all models have 3 parameters (#1572).

calc_MinDose()

• If init.values is provided and log = TRUE, the sigma parameter is now initialised as sigma / mu instead of log(sigma). The previous approach failed silently when sigma < 1, as the logarithm produced out-of-bounds parameter values, with the effect of leaving all parameters at their initial values (#1527; thanks to @MarijnvanderMeij for reporting and suggesting a fix).

• The confidence intervals stored in the RLum.Results object are now always in the natural units, independently of the log argument (#1533; thanks to @MarijnvanderMeij for reporting).

calc_OSLLxTxRatio()

• The SN_RATIO_TnTx value was wrongly returned as Inf if use_previousBG was set to TRUE and background_integral = NA. Now the function will return NA in this case, as stated in the function documentation (#1554).

• The computation of LxTx has been fixed to compute the contribution of the Tx background correctly when use_previousBG = TRUE. This should result in very minor differences if the background counts for the Lx and Tx curves are similar (#1565).

• The new od_rates argument activates an alternative approach for error estimation of Lx/Tx ratios based on Bluszcz, Adamiec and Herr (2015). This argument is also supported by analyse_SAR.CWOSL(), analyse_pIRIRSequence(), and analyse_FadingMeasurement() (#1390; thanks to @andrzejbluszcz for providing the mathematical description, contributing code and checking the implementation).

convert_Second2Gray()

• Input validation was strengthened to avoid two possible crashes (#1537).

fit_DoseResponseCurve()

• For fit.method = "OTORX" parameter a was renamed to Di for consistency.

• The argument fit.weights now supports a numeric vector as input. This gives more control over the fitting process and enables better comparison with other software, such as Python’s SciPy. The numeric vector must be of the same length as the number of data points to be fit. This is typical the number of LxTx points (#1536)

• Re-implement the argument fit.weights, now supporting keywords as input, selecting different approaches for fit weights. NULL disables weights and numeric input enables the definition of own weights. The new standard approach is 1/sigma^2 (#1539).

• The "QDR" fit method is now less likely to fail due to an invalid choice of the starting point for the uniroot() function (#1541).

• The starting value of one of the parameters of the EXP model has been tweaked to remove a dependency of the results from the random values used during the Monte Carlo steps. This should make the results more stable, in particular for mode = "extrapolation". This change may introduce some minor differences to the result of this function and of other functions that depend on it (#1550).

• Vectors containing the starting values for some fitting parameters used during the Monte Carlo runs are no longer generated for fit.method = "QDR" and "GOK", as they were unused in those models. This affects the state of the random number generator, so very minor numerical differences in the results are to be expected (#1568).

• The models used to generate sensible starting points for "EXP", “EXP+EXP”,“EXP+LIN”,“GOK”,“OTOR”and“OTORX”models now consider theLxTx` errors as weights, which may improve the fitting in cases when the data to fit is highly irregular due to very large errors (#1570).

• From the documentation, it was not always clear that the function expects columns with values in a particular order and does not look up column names (at least not all). Now the function is a little bit more flexible and automatically orders columns in the required order if column names that would somewhat match the expectations are used. As a positive side effect, the LxTx table produced by analyse_SAR.CWOSL() can be now inserted as input without further modification. (#1591 reported by @DirkMittelstrass).

fit_EmissionSpectra()

• The function no longer crashes if a frame argument of length 0 is used (#1602).

get_RLum()

• It is now possible to disable a potentially very long information message reported when the subset argument returns an empty list by setting verbose = FALSE. The verbose argument is also exposed in the subset() method for RLum.Analysis objects (#1587; thanks to @DirkMittelstrass for highlighting the problem).

merge_RLum.Results()

• The function gained the flatten argument, which allows to control whether list elements should be flattened into a single list when merging (#1593).

plot_AbanicoPlot()

• The summary text is no longer overprinted when multiple datasets are given as input and summary.pos is one of "left", "center" or "right" (#1575).

• The function no longer crashes when z.0 is misspecified (#1579).

plot_DetPlot()

• The function now allows passing the dose_rate_source argument to the analysis function via the analyse_function.control argument, as in analyse_function.control = list(dose_rate_source = 4.07) (#1561).

plot_DoseResponseCurve()

• The error bars had been missing for extrapolation and alternate mode since v1.1.0. This error was introduced with commit cf299831 and remained unnoticed due to lack of graphical snapshots (a3ed7744).

• Add ... support for arguments lwd_drc, lty_drc, and col_drc to enable further customisation of the dose-response curve.

• The function can now print the dose-response curves from an RLum.Results' object created byanalyse_SAR.CWOSL()` (#1592; thanks to @DirkMittelstrass for reporting).

plot_KDE()

• The default background colour was incorrectly set to NA, which in some cases, such as when plotting to a png file or in RStudio (at least on MacOS), corresponds to a transparent background. This could cause the KDE plot to appear to be drawn over an existing plot (#1556).

• The summary text is no longer overprinted when multiple datasets are given as input and summary.pos is one of "left", "center" or "right" (#1575).

plot_RadialPlot()

• The summary text is no longer overprinted when multiple datasets are given as input and summary.pos is one of "left", "center" or "right" (#1575).

• The function no longer crashes if centrality is set to a numerical value of length shorter than the number of input datasets (#1577).

plot_RLum.Results()

• The function can now plot objects generated by fit_DoseResponseCurve() instead of returning silently. This also allows using plot() on those objects to obtain the same output of plot_DoseResponseCurve() (#1550).

• Plotting an object produced by calc_AliquotSize() now supports that function’s full range of plot customisation arguments via ... (#1585).

• Plotting an object generated by analyse_SAR.CWOSL() will no longer call plot_AbanicoPlot() but will redraw the plots originally created by analyse_SAR.CWOSL() (#1589).

plot_RLum.Data.Spectrum()

• If the function was called with plot.type = "interactive", the error plot.new has not been called yet appeared in the terminal. This did not flag as an error before, because the plotly object was returned regardless of the error message; fixed.

• If the column names are replaced by the index, the default y-axis label is now preset accordingly to “Channel index”; it can be overwritten manually using ylab as a function argument. This should avoid cases where the user overlooks the warning and struggles to understand the axis values.

• The plot.type = "transect" now scales the y-axis automatically (can be overwritten with zlim)

• The plot.type = "transect" gained support for a couple of arguments: add (to add additional transects to an existing plot), smooth (basic curve smoothing), transect_mode to control the integration method (sum the default, mean, median, min, max)

plot_ViolinPlot()

• Numeric coordinates for summary.pos are now respected (#1596).

read_Daybreak2R()

• Information about irradiation doses are now more easily retrievable from the info element (#1563; thanks to @andrzejbluszcz for the code contribution).

remove_RLum()

• The function no longer accepts unnamed arguments (#1529).

Other changes