NEWS for the R Package Luminescence

Changes in version 0.4.1 (January 29th, 2015):

  New functions:

         • ‘merge_RLum.Data.Curve()’: Function allows merging of
           ‘RLum.Data.Curve’ objects in different ways (#128).

  Changes S4-objects, methods, classes:

         • ‘RLum.Analysis-class’:

             • Show warnings messages when empty object are produced by
               a ‘get_RLum.Analysis()’ request (implemented in get
               method and show method).

  Bugfixes and changes:

         • ‘analyse_SAR.CWOSL()’

             • rename argument ‘output.plot’ to ‘plot’,

             • rename argument ‘output.plot.single’ to ‘plot.single’,

             • rejection criteria added 'De > max. dose point'. These
               avoids that values are accepted even the De from the
               fitting should be considered as invalid.

         • ‘analyse_IRSAR.RF()’

             • Add enhanced support for ‘...’, e.g. ‘log’, ‘xlim’,
               ‘ylim’,

             • rename argument ‘output.plot’ to ‘plot’.

         • ‘analyse_pIRIRSequence()’

             • Fix an error that causes problems during plotting (Error
               in plot.new(): figure margins too large),

             • rename argument ‘output.plot’ to ‘plot’,

             • rename argument ‘output.plot.single’ to ‘plot.single’.

         • ‘merge_RLum()’: Function extended accordingly with the newly
           implemented function ‘merge_RLum.Data.Curve()’ (#128).

         • ‘plot_AbanicoPlot()’:

             • ticks removed from error bars,

             • line value output removed,

             • placement of y- and z-labels set to center of plot,

             • weights-option for KDE integrated,

             • warning for linear z-scale removed,

             • fixed an error that occured in Abanico Plot for a large
               data range (#188),

             • function output extended by data points in/out of
               confidence interval,

             • histogram option added,

             • dot plot option added,

             • KDE bandwidth added to plot output,

             • KDE bandwidth default changed to "SJ",

             • rugs coloured according to subsets,

             • examples section extended.

         • ‘plot_GrowthCurve()’:

             • Thanks to a querry from Rachel Smedly (#194) the De
               error calculation method has been updated.  So far only
               the Lx/Tx values have been re-sampled using a Monte
               Carlo simlation approach to estimate the error. In
               contrast to the Analyst the Ln/Tn value was just
               considered without any error. This has been changed for
               all fitting methods and the final De error is calculated
               now also using the Ln/Tn error.  Note: Usually this
               change results in a larger De error, however this
               approach is much more realistic,

             • consequently to the changes made in the error
               calculation the corresponding De resulting from the MC
               simulation is now added to the output object
               (‘$De$De.MC’),

             • Ln/Tn point including the error is now added on the plot
               output as red circle,

             • fix a bug occasionally occurred for ‘fit.method =
               "EXP+EXP"’ and the function broke subsequently (#159).

         • ‘readBIN2R()’:

             • critical bug fixed: ‘GRAIN’ and ‘GRAINNUMBER’ were not
               imported properely (thanks to Norber Mercier),

             • import speed has been improved by at least an order of
               magnitude, due to a different internal data handling
               (using of ‘data.table’ instead of ‘data.frame’). This
               may become relevant for hugh BIN-files like they are
               produced by single grain measurements (#191).  Note: The
               ‘Risoe.BINfileData-class’ remained untouched.

         • ‘writeR2BIN()’:

             • minor changes due to the changes in the function
               ‘readBIN2R()’,

             • confusing warnings during writing are suppressed.

  Internals:

         • Add new dependency for package ‘data.table’ (used in the
           function ‘readBIN2R()’).

Changes in version 0.4.0 (December 19th, 2014):

  Preface:

         • Amongst a few minor changes with this release we continued
           the homogenisation process to further unify our function
           arguments.  So far meaningful similar function arguments can
           be used over all functions in the package to produce similar
           effects (e.g., na.rm = TRUE/FALSE). For you as package user
           it means that self-written R scripts using package functions
           are likely to break. Please check the list of changes below.

           We apologise for any inconvenience!

  New S4-classes, methods:

         • ‘RLum.Data.Image’: S4-class for handling image data
           including. Image data in slot ‘data’ are stored as
           ‘RasterBrick’

         • ‘RLum.Results’: homogenised structure for containing the
           following base items in the slot data: 'summary', 'args' and
           'call'. Where applicable the 'data' slot contains the
           original input data.  Depending on the function various
           further slots are added containing additional (intermediate)
           data and objects,

         • ‘set_RLum.Data.Image()’: Set method for class
           ‘RLum.Data.Image’

         • ‘get_RLum.Data.Image()’: get method for class
           ‘RLum.Data.Image’

         • further: corresponding show and coercing methods added for
           class ‘RLum.Data.Image’.

  New functions:

         • ‘analyse_pIRIRSequence()’: Function to analyse post-IR IRSL
           sequence measurements (#133),

         • ‘calc_MinDose()’: the previous ‘calc_MinDose3()’ and
           ‘calc_MinDose4()’ functions were merged to the new
           ‘calc_MinDose()’ function, which was rewritten from scratch
           and now contains both the 3- and 4-parametric Minimum Age
           Models (introducing the new argument ‘par’).  Detailed
           changes and bugfixes are listed further below,

         • ‘calc_MaxDose()’: a wrapper function that calls
           ‘calc_MinDose()’, but transforms the data set similar to the
           method described in Olley et al. (2006).  Rather than
           estimating the minimum dose of a De distribution, this
           function estimates the maximum dose.

         • ‘calc_SourceDoseRate()’: calculating the dose rate of the
           irradiation source at the date of measurement based on:
           source calibration date, source dose rate, dose rate error.

         • ‘get_Layout()’: Helper function to return a list with layout
           definitions for more homogenous plotting,

         • ‘get_RLum()’: Wrapper function for various get methods for
           ‘RLum’-objects (#148),

         • ‘merge_RLum.Analysis()’: Function allows merging of
           RLum.Analysis objects and adding of objects an RLum.Analysis
           object consists of (#138),

         • ‘merge_RLum()’: Wrapper function for various merge methods
           for ‘RLum’-objects (#139),

         • ‘plot_RLum.Data.Image()’: Plot function for
           ‘RLum.Data.Image’ object.  Function also added to wrapper
           function ‘plot_RLum’,

         • ‘plot_RLum.Results()’: Plot function for ‘RLum.Results’
           objects.  RLum.Results objects created, e.g. by the age
           model functions may now be passed to ‘plot_RLum.Results()’
           to create specific plots that previously were generated by
           the functions themselves.  Function also added to wrapper
           function ‘plot_RLum’,

         • ‘readSPE2R()’: Add support Princenton Instruments *.SPE
           files (camera and spectrometer measurements). Function
           output is a ‘RLum.Data.Spectrum’ or ‘RLum.Data.Image’
           object.

  New example data sets:

         • ‘ExampleData.RLum.Data.Image’: Example data for
           ‘RLum.Data.Image’ object (part of #135).

  Changes S4-objects, methods, classes:

         • ‘get_RLum.Analysis()’: Add support for inverse ‘record.id’
           selection, e.g. ‘record.id = -1’ selects all objects except
           the first.

         • ‘get_RLum.Results()’:

             • Add support for data objects for objects produced by the
               function ‘calc_OSLLxTxRatio()’,

             • match access behavoir of objects produced by the
               function ‘calc_TLLxTxRatio()’. Now it works similar to
               the function ‘calc_OSLLxTxRatio()’.

         • ‘Risoe.BINfileData-class’: Description updated due to
           established changes made for a better file format support.

         • ‘Risoe.BINfileData2RLum.Analysis()’: If the ‘pos’ value is
           invalid now the function does not return an error any
           longer. Instead ‘NA’ is returned.

  Bugfixes and changes:

         • ‘analyse_IRSAR.RF()’:

             • Add ‘...’ support for ‘mtext’,

             • argument ‘method’ added to allow selection between the
               method ‘"FIT"’ and ‘"SLIDE"’. The latter method has been
               newly implemented (#143).

         • ‘analyse_SAR.CWOSL()’:

             • Allow 'IRSL' curves as input to support rough data
               analysis of the post-IR IRSL protocol (#132, Alice
               Versendaal, #140, Georgina King),

             • support multiple recuperation measurements,

             • correct wrong TL curve figure scaling,

             • argument ‘log’ moved to the ‘...’ argument,

             • correct wrong regeneration point numbering (#144),

             • arguments ‘cex’, ‘main’ now supported via the ‘...’
               argument,

             • argument ‘mtext.outer’ added,

             • output object ‘Formula’ added to return the fromula of
               the growth curve,

             • output object ‘De.values’ extended for D01, D02 and
               information on the applied fittin,

             • numerical output extended for information on the choosen
               signal and background integration limits (#122),

             • enhance argument ‘output.plot.single’ for numerical
               values.  This allows to select each single plot output
               individually,

             • details from the argument ‘rejection.criteria’ were
               removed from the argument list to allow a more flexible
               handling (e.g. changing only one parameter at time) and
               to clean up the argument list. However, the argument
               work still as excpected (#145),

             • reformat of rejection criteria output to allow easier
               further treatment,

             • support graphical output of rejection criteria and IRSL
               curve (if exists),

             • minor bug fixes (e.g., not properly caluculated TL curve
               resolution) and graphical adjustements.

         • ‘Analyse_SAR.OSLdata()’:

             • Error message implemented for non OSL data sets (#130,
               Georgina King),

             • add argument ‘dtype’ to provide further curve limitation
               options,

             • add argument ‘keep.SEL’ to allow a manual curve
               selection (advanced users),

             • minor code polishing.

         • ‘calc_AliquotSize()’:

             • new argument ‘plot’ (logical): option to (dis-)allow
               plotting of the Monte Carlo estimation,

             • argument ‘MC.estimate’ was renamed to ‘MC’,

             • new structure of the returned ‘RLum.Results’ object,
               containing the elements 'summary', 'args', 'call' and
               'MC'.

             • plotting now done by ‘plot_RLum.Results()’.

         • ‘calc_CentralDose()’:

             • removed argument ‘sample.id’,

             • removed argument ‘print.iterations’,

             • renamed argument ‘input.data’ to ‘data’,

             • new argument ‘'...'’, which is checked for arguments
               ‘verbose’ (logical) and ‘trace’ (logical) to (dis-)allow
               (extended) console output,

             • new structure of the returned ‘RLum.Results’ object,
               containing the elemennts 'summary', 'data', 'args',
               'call' and 'profile',

             • fixed a bug that occured for non-dispersed data sets and
               resulted in a virtually infinite loop using up all
               available memory,

             • plotting now done by

             • plot_RLum.Results().

         • ‘calc_CommonDose()’:

             • removed argument ‘sample.id’,

             • renamed argument ‘input.data’ to ‘data’,

             • new argument ‘'...'’ (currently not used),

             • new structure of the returned ‘RLum.Results’ object,
               containing the elements 'summary', 'data', 'args' and
               'call'.

         • ‘calc_CosmicDoseRate()’:

             • new structure of the returned RLum.Results object,
               containing the elements 'summary', 'args' and 'call'

         • ‘calc_FiniteMixture()’:

             • removed argument ‘sample.id’,

             • removed argument ‘n.iterations’,

             • removed argument ‘main’,

             • renamed argument ‘input.data’ to ‘data’,

             • new argument ‘plot’ option to (dis-)allow plotting when
               a vector of length > 1 is provided for ‘n.components’,

             • new argument ‘'...'’, which is checked for arguments
               ‘verbose’ (logical) and ‘trace’ (logical) to (dis-)allow
               (extended) console output. ‘main’ may be used to set the
               title of the plot,

             • new structure of the returned ‘RLum.Results’ object,
               containing the elements 'summary', 'data', 'args',
               'call', 'mle', 'BIC', 'llik', 'grain.probability',
               'components' and 'single.comp',

             • plotting now done by ‘plot_RLum.Results()’.

         • ‘calc_FuchsLang2001()’:

             • removed argument ‘sample.mtext’,

             • removed argument ‘sample.id’,

             • removed argument ‘output.terminal’,

             • renamed argument ‘sample’ to ‘data’,

             • renamed argument ‘output.plot’ to ‘plot’,

             • the argument ‘'...'’ is checked for ‘verbose’ (logical)
               to (dis-)allow console output,

             • new structure of the returned ‘RLum.Results’ object,
               containing the elements 'summary', 'data', 'args',
               'call' and 'usedDeValues',

             • plotting now done by ‘plot_RLum.Results()’.

         • ‘calc_HomogeneityTest()’:

             • removed argument ‘sample.id’,

             • renamed argument ‘input.data’ to ‘data’,

             • the argument ‘'...'’ is checked for ‘verbose’ (logical)
               to (dis-)allow console output,

             • new structure of the returned ‘RLum.Results’ object,
               containing the elements 'summary', 'data', 'args' and
               'call'.

         • ‘calc_MaxDose3()’:

             • Function renamed to ‘calc_MaxDose()’,

             • this is now just a wrapper function that calls the new
               ‘calc_MinDose()’ function, but transforms the data set
               similar to the method described in Olley et al. (2006).
               For further details please see the changes/bugfixes for
               the ‘calc_MinDose3()’ / ‘calc_MinDose4()’ functions,

             • plotting now done by ‘plot_RLum.Results()’.

         • ‘calc_MinDose3()’ and ‘calc_MinDose4()’

             • the functions ‘calc_MinDose3()’ and ‘calc_MinDose4()’
               were merged in the new function ‘calc_MinDose()’,

             • renamed argument ‘input.data’ to ‘data’,

             • renamed argument ‘output.plot’ to ‘plot’,

             • removed arguments ‘sample.id’, ‘gamma.xlb’, ‘gamma.xub’,
               ‘sigma.xlb’, ‘sigma.xub’, ‘mu.xlb’, ‘mu.xub’,
               ‘init.gamma’, ‘init.sigma’, ‘init.p0’, ‘init.mu’,
               ‘ignore.NA’, ‘calc.ProfileLikelihoods’,
               ‘console.ProfileLikelihoods’, ‘console.extendedOutput’,
               ‘output.indices’,

             • new argument ‘par’ that accepts a numeric value (either
               3 or 4) to set whether the 3- or 4-parametric Minimum
               Age Model should be applied,

             • new argument ‘bootstrap’ (logical) to apply the recycled
               bootstrap approach of Cunningham & Wallinga (2012),

             • new argument ‘boundaries’ that accepts a named list
               containing values for the lower and upper boundaries for
               all parameters,

             • new argument ‘init.values’ that accepts a named list
               containing the starting values for all parameters,

             • new argument ‘'...'’ that, amongst others, checks for
               ‘debug’ (logical) and ‘verbose’ (logical) to (dis-)allow
               (extended) console output. Further allowed arguments are
               ‘bs.M’, ‘bs.N’, ‘bs.h’ and ‘sigmab.sd’ to set various
               bootstrap parameters,

             • implemented (recycled) bootstrap method as described in
               Cunningham & Wallinga (2012),

             • function now iteratively adjusts boundaries for sigma
               when the estimator reaches the upper boundary,

             • function now tries to estimate reasonable starting
               values for all parameters,

             • calculation and plotting of the maximum log likelihood
               functions/profiles are now done using the mle2()
               function of the 'bbmle' package

             • the optimisation routine was changed from 'nlminb' to
               'optim' using the 'L-BFGS-B' method,

             • confidence intervals for all parameters are now
               calculated by the 'confint()' method and exclusively on
               the 95% confidence level

             • the asymmetric error on gamma (i.e., the minimum dose)
               is now exclusively determined on the 95% confidence
               interval of the profile log likelihood function for
               gamma

             • a symmetric standard error for gamma is automatically
               derived from the 95% confidence interval of the profile
               log likelihood function by dividing the length of this
               interval by 3.92 (see Galbraith & Roberts, 2012).

             • new structure of the returned ‘RLum.Results’ object,
               containing the elements 'summary', 'data', 'args',
               'call', 'mle', 'BIC', 'confint', 'profile', 'bootstrap',

             • plotting now done by ‘plot_RLum.Results()’.

         • ‘calc_OSLLxTxRatio()’:

             • Correct an error that causes ‘NA’ values within the
               curve errors for rare combinations of signal and
               background integreation limits,

             • provide a name for the output data frame ‘LxTx.table’
               for the ‘RLum.Results’ object,

             • error fixed for the marginal case that k = 2 and exceed
               the maximal curve length. In that case accidentially no
               error was calculated,

             • argument ‘sigmab’ was listed but was so far not
               implement. Fixed (#166)

         • ‘calc_OSLLxTxRatio()’:

             • support of data without given uncertainties.

         • ‘calc_Statistics()’:

             • support of data with ‘NA’ or zero errors

         • ‘calc_TLLxTxRatio()’:

             • Lx/Tx ratio wrongly calculated as due to a coding error
               just the first value of the signal integral was taken
               for summing up the values and not the range of the
               values,

             • Output produced by the function now is a ‘list’ (data
               slot in the RLum object), to equal behavoir of the
               functions.

         • ‘fit_CWCurve()’:

             • Implement ‘...’ argument to replace explicit arguments
               ‘ylab’, ‘xlab’ and ‘main’,

             • Fix an issue that causes an error when input values were
               <= 0 (#123 reported by Johanna Lomax),

             • Correct wrong y-axis labelling (wrong channel resolution
               value).

         • ‘plot_AbanicoPlot()’:

             • numeric values allowed for parameter centrality,

             • KDE label value fixed,

             • layout functionality added,

             • not supported summary keywords fixed,

             • dispersion polygon bug fixed,

             • dispersion type enriched by userdefined confidence
               interval,

             • rug option added,

             • multiple 2-sigma-bars allowed,

             • rotate-Option added to Abanico Plot,

             • minor modifications of layout definitions (#124),

             • ‘grid.col’ bug fixed (#149),

             • error message for data with zero or without errors added
               (#154),

             • age models as input for lines supported (#107),

             • support of ‘par(mfcol())’l,

             • bug in lower z-axis limit eliminated,

             • example list updated (i.e. fast CAM instead of slow MAM)

             • bug for small values fixed, rounding to 0 decimals
               replaced by 3 significant digits,

             • parameter ‘at’ to allow user-defined z-tick positions,

             • individual statistical summary order supported (#184).

         • ‘plot_DRTResults()’:

             • Argument ‘na.exclude’ renamed to ‘na.rm’,

             • by default ylim scaling now is set to the minimum and
               maximum extend of the data set,

             • argument ‘given.dose’ now allows a vector as input,
               e.g., if more then one data set is provided (#156),

             • argument ‘given.dose’ are not required any longer
               (became an optional argument).  With this the plot
               function can be easily re-used, e.g. for preheat plateau
               tests,

             • change behaviour of the argument ‘na.rm’. If a data set
               is provided containing ‘NA’ values also the
               corresponding values in provided by the argument
               ‘preheat’ are cleaned up. This allows a proper usage of
               the function in combination with grouping option (e.g.,
               ‘boxplot = TRUE’,

             • add argument ‘par.local’ to allow to combine output
               plots in broader plot frameworks,

             • minor corrections in error handling and graphical
               appearance.

         • ‘plot_Histogram()’:

             • Change default y-axis labelling from 'Counts' to
               'Frequency',

             • support of ‘par(mfcol())’ (#146),

             • support of data without and ‘NA’-values for error values
               (#152, #162),

             • implementation of ‘calc_Stats()’-call for extended
               statistic summary,

             • support of summary keywords "kurtosis" and "skewness",

             • example y-lim bug removed (#177),

             • individual statistical summary order supported (#184).

         • ‘plot_KDE()’:

             • wrong x-axis and y-axis limit calculation fixed (#158),

             • renaming and extension of summary and ‘summary.pos’
               parameter,

             • plot now longer shows a density error when no error
               exists (#160),

             • De.stats error fixed (#163),

             • support of ‘par(mfcol())’,

             • support of error-free data extended (now also for
               calculation of kde max) (#178),

             • individual statistical summary order supported (#184).

         • ‘plot_GrowthCurve()’:

             • Minor graphical and code polishing,

             • fix wrong regneration point plotting, if sequence
               contains more then one zero dose point,

             • argument ‘na.exclude’ for the sake consistency replaced
               by ‘na.rm’,

             • proper error message provided if nothing is left after
               ‘NA’ value removal,

             • overshoot of normal distribution curve in MC simulation
               plot corrected (#111),

             • argument ‘output.plotExtended.single’ added allowing a
               single window plot output of all plots,

             • formula of the fitted function is now returend as R
               expression instead of a ‘formula’ object. The return
               object remains, however, ‘Formula’,

             • correct wrong error message and graphical output for
               cases where no De can be calculated for Ln/Tn values
               much higher than the highest Lx/Tx value,

             • fix ‘'EXP+EXP'’ fit as is was broken, due to a coding
               error,

             • correct for wrong ‘par()’ resetting,

             • minor code polishing and adjustment.

         • ‘plot_RadialPlot()’:

             • support of user-defined centrality value,

             • rug option added,

             • bug for small values fixed, rounding to 0 decimals
               replaced by 3 significant digits,

             • individual statistical summary order supported (#184),

             • minor fixes for the graphical output.

         • ‘plot_RLum.Analysis()’:

             • Add argument ‘abline’ to allow inserting similar
               vertical or horizontal lines in every plot. The decision
               to implement this argument in this function instead the
               function ‘plot_RLum.Data.Curve()’ was made because in a
               single plot modus ‘abline’ is more sufficiently used as
               separat function call,

             • now reset ‘par’ parameters suffciently,

             • add argument ‘combine’ to allow fast combining of curves
               in single plot window.

         • ‘plot_RLum.Data.Curve()’:

             • Add argument ‘norm’ to allow for curve normalisation to
               the highest value (#129),

             • Correct for insufficient information on the channel
               resolution when data was imported from an XSYG file.

         • ‘plot_RLum.Data.Spectrum()’:

             • Correct an error that caused a chrash when ‘xlim’ was
               set in a way that only one wavelength (colour value) was
               remained,

             • correct zebra-colour-pattern for rare cases of ‘xlim’
               settings using ‘plot.type = "persp"’ or ‘plot.type =
               "persp3d"’,

             • add argument new plot type ‘"transect"’ for plotting a
               transect along the time/temperature axis for a specific
               wavelength/channel intervall (#120, requested by Regina
               DeWitt),

             • correct function break for a single column matrix
               (single frame spectrum) by automatically resetting
               ‘plot.type’ to ‘single’ for single frame spectra,

             • colour rug (‘rug = TRUE’) implemented for plot type
               ‘"multiple.lines"’ (#130),

             • argument ‘xaxis.energy’ for wavelength energy conversion
               for 2D plots added (#141).

         • ‘readBIN2R()’:

             • Integrity checks added to avoid unspecific errors for
               wrong input formats,

             • complete format support as now a more throughtful
               distinction is made between version 03 and 04 (also made
               for function ‘writeR2BIN()’) (#182),

             • ‘TAG’ bit is now used to trigger the ‘SEL’ element
               during import.  With this, previous curve selections
               made with other software are kept (#181, Norbert
               Mercier).

         • ‘readXSYG2R()’:

             • If the stimulator is infrared light the ‘recordType’
               will be set to ‘IRSL’. This makes the curve types more
               consistent with the commonly applied nomenclature,

             • now the function automatically converts time values to
               temperature values also for spectra data (#121);
               behavious is triggered with the argument
               ‘recalculate.TL.curves’.

         • ‘Second2Gray()’:

             • Minor code and example adjustments in along with
               creating a new function ‘calc_SourceDoseRate()’ (#56).

         • ‘writeBIN2R()’:

             • Complete format support as now a more throughtful
               distinction is made between version 03 and 04 (also made
               for function ‘readBIN2R()’) (#182),

             • ‘SEL’ will now be kept using the ‘TAG’ bit, releated to
               changes made in function ‘readBIN2R’ (#181, Norbert
               Mercier).

  Internals:

         • Add new dependency for package ‘raster’ and ‘sp’, which is
           used for the ‘RLum.Data.Image-class’,

         • dependency to package 'Rserve' removed,

         • dependcy to package 'zoo' added (used for running means),

         • dependency to package 'bbmle' added (used for maximum
           likelihood estimations).

