calED: Equivalent dose calculation and error assessment

Description Usage Arguments Details Value Note References See Also Examples

View source: R/calED.R

Description

Calculating an equivalent dose and assessing its standard error.

Usage

1
2
3
4
5
6
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 http://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.

See Also

analyseBINdata; fitGrowth; calRcyRcp;
calSARED; fastED; calSGCED

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
  ### 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 May 1, 2019, 8:45 p.m.