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

New functions

Removed functions and deprecations

Bugfixes and changes

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

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

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

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.

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

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

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.

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