calED: Equivalent dose calculation and error assessment
In numOSL: Numeric Routines for Optically Stimulated Luminescence Dating

calED

R Documentation

Equivalent dose calculation and error assessment

Description

Calculating an equivalent dose and assessing its standard error.

Usage

calED(Curvedata, Ltx, model = "gok", origin = FALSE, 
      errMethod = "sp", nsim = 500, weight = TRUE,  
      trial = FALSE, plot = TRUE, nofit.rgd = NULL, 
      agID = NULL, Tn = NULL, Tn3BG = NULL, 
      TnBG.ratio = NULL, rseTn = NULL, FR = NULL, 
      LnTn.curve = NULL, TxTn = NULL)

Arguments

`Curvedata`	matrix(required): a three-column matrix (i.e., regenerative doses, sensitivity-corrected regenerative-dose signals, and associated standard errors)
`Ltx`	vector(required): a two-element vector consists of sensitivity-corrected natural-dose signal and its error
`model`	character(with default): model used for growth curve fitting, see fitGrowth for available models
`origin`	logical(with default): logical value indicating if the growth curve should be forced to pass the origin
`errMethod`	character(with default): method used for equivalent dose error assessment. `"sp"` and `"mc"` denote error estimation using the Simple Transformation and Monte Carlo methods, respectively
`nsim`	integer(with default): desired number of randomly simulated equivalent dose obtained by Monte Carlo simulation
`weight`	logical(with default): logical value indicating if the growth curve should be fitted using a weighted procedure, see function fitGrowth for details
`trial`	logical(with default): logical value indicating if the growth curve should be fitted using other models if the given model fails, see function fitGrowth for details
`plot`	logical(with default): logical value indicating if the results should be plotted
`nofit.rgd`	integer(optional): regenerative doses that will not be used during the fitting. For example, if `nofit.rgd=1` then the first regenerative dose will not be used during growth curve fitting
`agID`	vector(optional): a three-elemenet vector indicating aliquot (grain) ID, i.e., `agID[1]=NO`, `agID[2]=Position`, `agID[3]=Grain`
`Tn`	vector(optional): a two-element vector containing value and standard error of Tn
`Tn3BG`	numeric(optional): 0-1 value indicating if Tn is more than 3 sigma above BG, 1 indicates Tn>3_sigma_BG, 0 indicates Tn<=3_sigma_BG
`TnBG.ratio`	vector(optional): a two-element vector containing value and standard error of ratio of initial Tn signal to BG
`rseTn`	numeric(optional): relative standard error of Tn in percent
`FR`	vector(optional): a two-element vector containing value and standard error of fast ratio of Tn
`LnTn.curve`	list(optional): decay curve data for Ln and Tn, it should contain four elements, i.e., `names(LnTn.curve)=c("Ln.x","Ln.y","Tn.x","Tn.y")`
`TxTn`	vector(optional): ratios of Tx to Tn for various SAR cycles

Details

Function calED is used for calculating an equivalent dose and assessing its standard error. The standard errors of an equivalent dose can be assessd using the Simple Transformation or Monte Carlo method (Duller, 2007).

Interpolation is performed using a combination of golden section search and successive parabolic interpolation (R function optimize in package stats) (freely available Fortran 77 source code at https://www.netlib.org/fmm/fmin.f). See function fitGrowth for more details on growth curve fitting.

Value

Return an invisible list that contains the following elements:

`message`	return 0 if calculation succeeds, 1 if growth curve fitting fails, 2 if natural-dose signal saturates, 3 if equivalent dose calculation fails, 4 if equivalent dose error assessment fails
`fitIDX`	Indices of dose points used in growth curve fitting
`LMpars`	optimized parameters for the growth curve
`value`	minimized objective for the growth curve
`avg.error`	average fit error for the growth curve
`RCS`	reduced chi-square value for the growth curve
`FOM`	figure of merit value for the growth curve in percent
`calED.method`	method used for equivalent dose calculation, i.e., `"Interpolation"` or `"Extrapolation"`
`mcED`	randomly simulated equivalent doses
`ED`	calculated equivalent dose and its standard error
`ConfInt`	68 percent and 95 percent confidence intervals for the equivalent dose
`RecyclingRatio1`	the first recycling ratio and its standard error
`RecyclingRatio2`	the second recycling ratio and its standard error
`RecyclingRatio3`	the third recycling ratio and its standard error
`Recuperation1`	the first recuperation (i.e., ratio of the sensitivity-corrected zero-dose signal to natural-dose signal) and its standard error in percent
`Recuperation2`	the second recuperation (i.e., ratio of the sensitivity-corrected zero-dose signal to maximum regenerative-dose signal) and its standard error in percent

Note

Arguments agID, Tn, Tn3BG, TnBG.ratio, rseTn, FR, LnTn.curve, and TxTn have nothing to do with equivalent dose calculation. They are used only for plotting purpose.

Argument Tn3BG indicates if Tn (after background subtraction) is more than 3 sigma above BG, while argument TnBG.ratio denotes the ratio of Tn (no background subtraction) to BG.

Function calED will return message=3 (i.e.,"Failed in equivalent dose calculation") if the equivalent dose to be calculated below -50 (<Gy>|<s>).

68 percent (one sigma) and 95 percent (two sigma) confidence intervals of equivalent doses will be determined respectively using normal approximation and Monte Carlo simulation,
for errMethod="sp" and errMethod="mc".

Function sgcED in previous versions was bundled to function calSGCED.

References

Duller GAT, 2007. Assessing the error on equivalent dose estimates derived from single aliquot regenerative dose measurements. Ancient TL, 25(1): 15-24.

Duller GAT, 2016. Analyst (v4.31.9), User Mannual.

Galbraith RF, Roberts RG, 2012. Statistical aspects of equivalent dose and error calculation and display in OSL dating: an overview and some recommendations. Quaternary Geochronology, 11: 1-27.

Examples

  ### Example 1:
  Curvedata <- cbind(c(0, 18, 36, 54, 72, 0, 18),               
                    c(0.026, 1.55, 2.39, 3.46, 4.13, 0.023, 1.61),  
                    c(0.005, 0.11, 0.27, 0.22, 0.20, 0.008, 0.24))                         
  Ltx <- c(3.1,0.31)
  calED(Curvedata, Ltx, model="exp", origin=FALSE)
  
  ### Example 2 (not run):
  # data(BIN)
  # obj_pickBIN <- pickBINdata(BIN, Position=48, 
  #                            LType="OSL", view=FALSE)
  # obj_analyseBIN <- analyseBINdata(obj_pickBIN, nfchn=3, nlchn=20)
  # Curvedata <- obj_analyseBIN$SARdata[-1,3:5]
  # Ltx <- as.numeric(obj_analyseBIN$SARdata[1,4:5])
  # calED(Curvedata, Ltx, model="gok", origin=FALSE)

numOSL documentation built on Sept. 18, 2023, 9:07 a.m.