With the release of roxygen2, the package documentation can be created using markdown tags.
The documentation should be updated accordingly to account for this new development.

• calc_Fun()
• analyse_Fun()
• plot_Fun()
• convert_Fun()
• ... everything else

• Change distribution assumption for MC runs of the parameter s from normal to uniform.
• Use the log() values for s

Allow for converting values from ppm to Bq/kg and vice versa for K-40, U-238 and Th-232, based on an internal excel spreadsheet.

When doing:
AD <- calc_AverageDose(X, 0.1)
X <- get_RLumResults(AD, "dstar")

X is a matrix without col-names. Actually it would be more appropriate to have it as a data frame with names. Would make it easier for further plotting but also the data set is a collection of samples, each described by De and error, i.e., the ideal format for a data frame.

Summary

The additional argument breaks, passed via ... to the function graphics::hist is erroneously treated and if used leading to a wrong plot output. In particular, the argument breaks fails if a single numeric value is provided. However, according to the manual (?hist) the argument breaks allows for

one of:
a vector giving the breakpoints between histogram cells,
a function to compute the vector of breakpoints,
a single number giving the number of cells for the histogram,
a character string naming an algorithm to compute the number of cells (see ‘Details’),
a function to compute the number of cells.

Example

## load data
data(ExampleData.DeValues, envir = environment())
ExampleData.DeValues <-
  Second2Gray(ExampleData.DeValues$BT998, dose.rate = c(0.0438,0.0019))

## plot histogram the easiest way
plot_Histogram(ExampleData.DeValues, breaks = 5)

Traceback

Please check, amongst others, line 236:

    xlim.plot <- range(breaks.plot)

Possible solution

The automatic xlim values should not set using the manually set breaks, but the real one created by
hist.

The documentation of each function should contain a Citation section with a reference that can be used for more granular citation. The reference will follow the following style.

<author1>, <author2> (<year>). "<function>: <title>". In: <RpackageAuthors>, (<year>): Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version <version>. https://CRAN.R-project.org/package=Luminescence.

According to Murray and Wintle (2000) for particular cases it might be necessary to use the background of the Lx curve to correct the Tx curve (use previous background). To account for this the function should be modified as follows:

Implement new logical parameter use_previousBG to use the BG of the Lx curve for the getting the net signal of the Tx curve.

• Check if the time domain AND the number of channels are similar for both curves, otherwise the option use_previousBGhas to be reset automatically to FALSE
• Check for differences in the signal integral limits in both curves (this is already allowed by the function) to make sure that the background subtraction will not bias the results (...>> parameter k)

Some functions test if the provided object is of class RLum.Results and retrieve the DE and DE.ERROR data via get_RLum. The problem: while most RLum.Results objects store raw DE values in slot @data$data, the analyse_*-functions have these values in @data$De.values.

Most or all functions that try to obtain these data check for the data, but not the De.values slot. Hence, e.g. passing an object from analyse_SAR.CWOSL to plot_KDE does not work, even though it would make perfect sense.

Possible solutions:

• have all non-analyse functions have additional checks for special originators (analyse_SAR.CWOSL, analyse_SAR.OSLdata, analyse_IRSAR, analyse_pIRIRsequence,
• or add a @data$data slot to the RLum.Results objects created by the analyse_* functions.

For bug report see message board.

In line 127: setdiff(grain, grain.valid) but grain.valid was not declared before. So if a user is in the else-command (line 126, argument grain is given a value) you will, of course, always get an error:

Risoe.BINfileData2RLum.Analysis(
    object = CWOSL.SAR.Data,
    pos = 1, 
    grain = 0)

Error in as.vector(y) : object 'grain.valid' not found

Why using RcppExport SEXP instead of List (or Rcpp::List), because the function returns a List? I think it's an artefact from older versions from Rcpp package and not necessary with the command in line 14.
With List analyse_IRSARRF_SRS(....) all works fine too and it's much clearer what is the return type of this function.

https://github.com/R-Lum/Luminescence/blob/master/src/analyse_IRSARRF_SRS.cpp#L15

When using the arguments ylim = ... and legend.pos = "outside" the plot is shown in a strange way, because the boarders of the plot area are exceeded.

Example (simplified from the manual example of plot_Rlum.Analysis()):

data(ExampleData.BINfileData, envir = environment())

temp <- Risoe.BINfileData2RLum.Analysis(CWOSL.SAR.Data, pos=1)

plot_RLum.Analysis(
  temp,
  subset = list(recordType = "TL"),
  combine = TRUE,
  ylim = c(100, 200),
  legend.pos = "outside"
)

When using either ylim = ... or legend.pos = "outside" all works well, but not when using both. When using legend.pos = "topleft" all works well, too.

[write_R2BIN()] The number of columns in your slot 'METADATA' does not fit to the latest definition. What you are probably trying to do is to export a Risoe.BINfileData object you generated by your own or you imported with an old package version some time ago. Please re-import the BIN-file using the function read_BIN2R().

CC: @coffeemuggler

The NAMESPACE import is not correct as the package cannot be built after bbmle is removed from
the global import, this makes no sense.

Should be done using the internal function .create_StatisticalSummaryText().
The following functions need to be modified:

• plot_AbanicoPlot() @coffeemuggler
• plot_Histogram() @coffeemuggler
• plot_KDE() @coffeemuggler
• plot_RadialPlot() @coffeemuggler
• plot_ViolinPlot() @RLumSK (DONE)
• plot_DRTResults() @RLumSK (DONE)

https://github.com/R-Lum/Luminescence/blob/dev_0.8.0/R/analyse_SAR.CWOSL.R#L328

In my opinion the command should be:

signal.integral.max <- 2

instead of signal.integral.min <- 2. This would match the warning message and makes much more sense and the function is running even when there was no value given by the user for signal.integral.max.

The argument method.control = list(cores = 'auto') has not effect on Windows machines. Unfortunately, I could implement, but not test it. Could you plese help out here?

Running example to test

##load data
data(ExampleData.RLum.Analysis, envir = environment())

##(1) perform analysis using the method 'FIT'
results <- analyse_IRSAR.RF(object = IRSAR.RF.Data, method = "SLIDE", method.control = list(cores = 'auto'))

The following code leads to an unwanted error, because the argument "verbose" is not handled
appropriately.

fading_data <- ExampleData.Fading$fading.data$IR50
data <- ExampleData.Fading$equivalentDose.data$IR50
ddot <- c(7.00, 0.004)
readerDdot <- c(0.134, 0.0067)

rhop <-
  analyse_FadingMeasurement(fading_data,
                            plot = FALSE,
                            verbose = FALSE,
                            n.MC = 10)
kars <- calc_Kars2008(
  data = data,
  rhop = rhop,
  ddot = ddot,
  readerDdot = readerDdot,
  n.MC = 50,
  plot = FALSE,
  verbose = FALSE
)

Furthermore:

• please correct typo "unable for fit"

Other calc_... functions like calc_CentralDose() already have a verbose option to show output on the terminal.

This function fails to work if called from behind a proxy which requires a username and password combination. In such cases the call

devtools::install_github("R-Lum/Luminescence@master")

fails as well. An option (further arguments) would be needed to deal with this challenge.

The function plot_AbanicoPlot returns an incorrect mean if the parameter summary is used.
Example:

df <- data.frame(x = c(216.386185039012, 209.697109762851, 195.609128179155, 200.447792155275, 201.574999360227), y = c(2.21668575178517, 2.03173425290263, 
1.9352060325474, 1.97970741384171, 2.08338086512403))

mean(df$x)

This results in a mean of 204.743. However, using calling

plot_AbanicoPlot(data = df, summary = c("mean"))`

The mean is 204.61 and NOT 204.743. I guess this comes from the transformation from the log-space and back, since plot_AbanicoPlot(data = df, summary = c("mean"), log.z = FALSE) returns the correct value. However, there is no reason why the mean should be different.

This function currently uses an invalid way of error calculation for the Lx/Tx ratio. For instance, when the integrated background counts are the same for Lx and Tx, the value for Tx will be zero.

The function documentation contains no entry for the function value, which is also not defined in the Roxygen2 part of the source code.

Suppose we have a SAR measurement with 2 aliquots.

Currently, the output table <obj>@data$rejection.criteria has the following structure:

This means that there a 6 rows for each aliquot. Collating/merging the rejection criteria results with the corresponding aliquot in the <obj>@data$data is a major pain as the former table must be transformed to the (much more reasonable) "1-row-1-aliquot" structure first. I suggest re-structuring the rejection.criteria-table as follows (rj = rejection criterion, th = threshold, val = value) ...

... which would make merging the tables much more straightforward and intuitive.

Drawback:

Since I would suggest to conform to standard naming conventions for column names the table would not be as descriptive as before and we would need to find concise and distinct column names.

It appears that the numerical values returned from DRAC are by definition of type 'factor', but
they should be of type 'numeric' is this a feature or a bug?

Argument data assumes the first row of the data.frame to be the value for Ln/Tn. Add a new argument to allow the user to provide multiple LnTn-values from which a mean(?) LnTn-value is calculated.

In some cases it would be nice to place the legend of the abanico, kde, etc. plot outside of the plotting area. For some data sets and having activated several statistical parameters to show in the legend it becomes cumbersome to fit the legend within the plotting area (overlapping of legend with data).

Idea: add 'outside' parameter to 'sum.pos' argument and plot legend on the outer (right|left) margin of the plot. This obviously requires some readjustment of when setting the general layout ('layout','mfrow', 'mfcol').

Adjusting the global scale (cex < 1) is not a good option, as it becomes unreadibly small for publication and again requires rescaling in external tools.

The documentation should answer why the loglikelihood profile plots produced by bbmle look different from the "usual" llik plots, i.e., why are they V-shaped? Refer to official documentation of the package:

https://cran.r-project.org/web/packages/bbmle/vignettes/mle2.pdf

Tasks:

• Cross-check/validate function
• Update (argument) documentation

Please add a return value to the plot function, as in plot_KDE() and plot_AbanicoPlot(). @coffeemuggler @tzerk

• add argument 'output' (default TRUE, return as invisible())
• add argument 'plot' (default TRUE)

Function does not work for files imported from XSYG files, due to differently stored irradiation time.

Function should be enhanced.

Tasks:

• Split function into separate functions, e.g. plot_DoseResponseCurve() and fit_DoseResponseCurve()
• Return plots as separate output object element ,e.g. if plot=FALSE then no plot is shown, but an object containing the plot is returned like a <- plot(test)

Function that implements the decision tree after Bailey & Arnold 2006 and Arnold et al. 2007, proposed by Kathleen Rodrigues (University of Nevada, Reno).

... more meaningful with regard to the data.
The current default (0.01 and 1000) is not sufficient if the user works in seconds.

Extend method to allow for selecting elements by their info element existence and specific value.

Problems:

• Test for existence of any info element is needed (slot info might be empty)
• Test for existence of such element is needed (no element, no return)
• Unsolved issue: How the user get information on allowed elements?

BE CAREFUL. Any change in this method affects a lot of other functions

For some reason when a call to subset.RLum.Analysis() is surrounded by a function get_RLum.Analysis() searches x (see example below) in the global environment rather than in the environment of the calling function. This, of course, results in an error as x is not found within the global environment; this is unless we assign it before calling foo().

Minimal reproducible example:

library(Luminescence)

# An RLum.Analysis object
data("ExampleData.RLum.Analysis")
rlum <- IRSAR.RF.Data

# Enclosing function to subset()
foo <- function(obj) {
  x <- "RF"
  rlum_sub <- subset(obj, recordType == x)
}

# Fails (enclosing function):
foo(rlum)

# Works (interactive):
subset(rlum, recordType == "RF")

# Works (define 'x' in the global environment before calling foo())
x <- "RF"
foo(rlum)

In the function plot_RLum.Data.Spectrum() the argument plot.type = "interactive" gives an error. This is related to an update of the package plotly. With version 3.6.0 all works fine, but not with the recent one (4.5.2).

Example (from the manual):

##load example data
data(ExampleData.XSYG, envir = environment())

 ##(4) interactive plot using the package plotly
 plot_RLum.Data.Spectrum(TL.Spectrum, plot.type="interactive",
      xlim = c(310,750), ylim = c(0,300), bin.rows=10,
      bin.cols = 1)

Error: Variables must be length 1 or 85.
Problem variables: 'x'

As far as I can see the rejection criteria in analyse_SAR.CW.OSL() are calculated as a ratio before comparing them to the provided list of threshold values. But it is unclear whether the user should provide a ratio or a percentage as threshold value.

For recycling.ratio, testdose.error and palaeodose.error the user is required to provide a percentage, but for recuperation.rate it is a ratio.

My suggestion are as follows:

1. have the user also specify a percentage for recuperation.rate
2. Update the documentation for the argument rejection.criteria and in the details, clearly stating that percentage values are assumed
3. check and make sure that in the output table the calculated values and thresholds have the same unit

At the moment, the examples are "wrong" in the sense that it provides a recuperation.rate of 10. In code line 855

if(Recuperation[x] > rejection.criteria$recuperation.rate){

this value is compared against a ratio.

Reported by Karsten Bracht Nielsen via e-mail:

temp <- read_BIN2R("C:\\Users\\karb\\Downloads\\bin.BIN", fastForward = TRUE)
temp.sel <- temp[[332]]
results <- analyse_SAR.CWOSL(
  object = temp.sel,
  signal.integral.min = 1,
  signal.integral.max = 5,
  background.integral.min = 96,
  background.integral.max = 100,
  fit.method = "EXP",
  rejection.criteria = list(
    recycling.ratio = 10,
    recuperation.rate = 10,
    testdose.error = 10,
    palaeodose.error = 20,
    exceed.max.regpoint = TRUE
  )
)

The return value from calc_OSLLxTxRatio is:

This will later cause plot_GrowthCurve() to return NULL on this check:

  ##2.1 check for inf data in the data.frame
  if(any(is.infinite(unlist(sample)))){
    warning("[plot_GrowthCurve()] The input data contain at least one Inf value. NULL returned!")
    return(NULL)
  }

Which in turn gives this error in analyse_SAR.CWOSL():

Error in (function (classes, fdef, mtable)  :
  unable to find an inherited method for function ‘get_RLum’ for signature ‘"NULL"’

on this line:

   ##grep informaton on the fit object
   temp.GC.fit.Formula  <- get_RLum(temp.GC, "Formula")

Situation:
When creating an RLum-Object without specifying the @orginator the latter will automatically be set by

originator <- as.character(sys.call(which = -1)[[1]])

Problem:
When a function in the package is called explicitly (i.e., package::function) the originator becomes NA.

Reproducible example:

library(Luminescence)
data(ExampleData.DeValues, envir = environment())
res <- Luminescence::calc_CentralDose(ExampleData.DeValues$CA1)
print(res@originator)

Proposed fix:
Check if as.character(sys.call(which = -1)[[1]]) contains double colons (::) and only take anything following it.

If the extrapolation intersects the x-axis with positive value (for y = 0), the graphical presentation is not correct.

Actually the production of the De(t) plot is limited for OSL data, but I can make also sense
for TL data. Internally: use the function calc_TLLxTxRatio()

A wrong wavelength scale appears within the Luminescence 0.7.3 package when executing example nr. 4 from the documentation of plot_RLum.Data.Spectrum:

data(ExampleData.XSYG, envir = environment())

plot_RLum.Data.Spectrum(TL.Spectrum, plot.type="interactive",
 xlim = c(310,750), ylim = c(0,300), bin.rows=10,
 bin.cols = 1) 

xlim works, but has wrong labels.
In contrast to issue #23 the bug is within the Luminescence package, because with changing to older versions of plotly the error remains, but disappears when changing the Lumi-package to 0.6.4.

Title says it all. Will probably require adding a new example data set to the package.

Currently, the user is only allowed to specify the channel for L1, while L2 and L3 are calculated from the input data. In certain situations it may be useful to manually provide a value for L2 and L3, however.

template$`ExternalU (ppm)` should become
template$`External U (ppm)`

(add one space more)

Under some circumstances re-scaling of the y-axis causes to have negative "normalised" signal intensities.

##CWOSL.SAR.Data and TL.SAR.Data
data(ExampleData.BINfileData, envir = environment())

##transform the values from the first position in a RLum.Analysis object
object <- Risoe.BINfileData2RLum.Analysis(CWOSL.SAR.Data, pos=1)

plot_DetPlot(object,
             signal.integral.min = 1,
             signal.integral.max = 3,
             background.integral.min = 900,
             background.integral.max = 1000,
             n.channels = 5)

The import from a folder seems to end up in an endless loop; check.

The unsupported argument 'plot' produced an unexpected error message if provided. Example:

data(ExampleData.DeValues, envir = environment())
ExampleData.DeValues <- ExampleData.DeValues$CA1
 plot_AbanicoPlot(ExampleData.DeValues, plot = FALSE)

Desired solution: The argument plot should cause no crash and should be simply ignored.