Changes in version 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).

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

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

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