calED: 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

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

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

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

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

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.

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

Run this code

# NOT RUN {
  ### 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)
 
# }

Run the code above in your browser using DataLab

Last chance! 50% off unlimited learning