calSGCED: SGC Equivalent dose calculation and selection

Description

Calculating and selecting equivalent doses in a batch model according to the "standardised growth curve" (SGC) method suggested by Roberts and Duller (2004) or the "global standardised growth curve" (gSGC) method suggested by Li et al. (2015, 2016).

Usage

calSGCED(obj_analyseBIN, SGCpars, model, origin, avgDev, 
         method = "SGC", SAR.Cycle = "N", errMethod = "sp", 
         Tn.above.3BG = TRUE, TnBG.ratio.low = NULL, 
         rseTn.up = NULL, FR.low = NULL, rseED.up = NULL, 
         use.se = TRUE, outpdf = NULL, outfile = NULL)

Value

Return an invisible list that contains the following elements:

scale.Ltx: scaled standardised natural-dose signals and associated standard errors used for SGC equivalent dose calculation. Note that standardised natural-dose signals will remain un-scaled if method="SGC"
sgcED: calculated SGC equivalent doses
ConfInt: 68 percent (one sigma) and 95 percent (two sigma) confidence intervals of SGC equivalent doses
agID: aliquot (grain) ID of calculated (selected) SGC equivalent doses
summary.info: a summary of the SGC equivalent dose calculation

Arguments

obj_analyseBIN: list(required): an object of S3 class "analyseBIN" produced by
function analyseBINdata or as_analyseBIN
SGCpars: vector(required): optimized parameters of the SGC obtained using function lsNORM (or fitGrowth)
model: character(required): fitting model used for obtaining SGCpars
origin: logical(required): logical value indicating if established SGC passes the origin
avgDev: numeric(required): average deviation (i.e., average fit error) of the SGC obtained using function fitGrowth or lsNORM. This quantity stands for the uncertainty of established SGC when assessing the equivalent dose error using the simple transformaion method
method: character(with default): method used for equivalent dose calculation, i.e.,
method="SGC" (for the original SGC method) or method="gSGC" (for the improved SGC method)
SAR.Cycle: character(with default): SAR cycles used for SGC equivalent dose calculation.
Example: SAR.Cycle=c("N","R3")
errMethod: character(with default): method used for equivalent dose error assessment
Tn.above.3BG: logical(with default): logical value indicating if aliquot (grain) with Tn below 3 sigma BG should be rejected
TnBG.ratio.low: numeric(optional): lower limit on ratio of initial Tn signal to BG
rseTn.up: numeric(optional): upper limit on relative standard error of Tn in percent
FR.low: numeric(optional): lower limit on fast ratio of Tn
rseED.up: numeric(optional): upper limit on the relative standard error of equivalent dose in percent
use.se: logical(with default): logical value indicating if standard errors of values should be used during application of rejection criteria
outpdf: character(optional): if specified, results of SGC equivalent dose calculation will be written to a PDF file named "outpdf" and saved to the current work directory
outfile: character(optional): if specified, SGC equivalent doses related quantities will be written to a CSV file named "outfile" and saved to the current work directory

References

Li B, Roberts RG, Jacobs Z, Li SH, 2015. Potential of establishing a "global standardised growth curve" (gSGC) for optical dating of quartz from sediments. Quaternary Geochronology, 27: 94-104.

Li B, Jacobs Z, Roberts RG, 2016. Investigation of the applicability of standardised growth curves for OSL dating of quartz from Haua Fteah cave, Libya. Quaternary Geochronology, 35: 1-15.

Roberts HM, Duller GAT, 2004. Standardised growth curves for optical dating of sediment using multiple-grain aliquots. Radiation Measurements, 38(2): 241-252.

Examples

Run this code

 data(SARdata)
 ### (1) gSGC ED calculation:
 ### gSGCpars were obtained using function "lsNORM".
 gSGCpars <- c(137.440874251, 0.007997863, 2.462035263, -0.321536177)
 avg.error2 <- 0.1111623
 res <- calSGCED(as_analyseBIN(SARdata), gSGCpars, method="gSGC", 
                 model="gok", origin=FALSE, avgDev=avg.error2,
                 SAR.Cycle=c("N","R3"))
 print(res$sgcED)

 ### (2) SGC ED calculation (not run): 
 ### SGCpars were obtained using function "fitGrowth".
 # SGCpars <- c(183.474322547,  0.007038048,  4.254287622, -0.337734151)
 # avg.error <- 0.3156259
 # calSGCED(as_analyseBIN(SARdata), SGCpars, method="SGC", model="gok", 
 #          origin=FALSE, avgDev=avg.error, SAR.Cycle="N", outpdf="SGCED")

 ### (3) gSGC ED calculation and signal-related 
 ###     rejection criteria application (not run):
 # data(BIN)
 # res_pickBIN <-pickBINdata(BIN, LType="OSL")
 # res_analyseBIN <- analyseBINdata(res_pickBIN, nfchn=4, nlchn=30)
 # res_lsNORM <- lsNORM(res_analyseBIN$SARdata, model="gok", origin=FALSE)

 # calSGCED(res_analyseBIN, SGCpars=res_lsNORM$LMpars2[,1], 
 #         model="gok", origin=FALSE, avgDev=res_lsNORM$avg.error2,
 #         method="gSGC", SAR.Cycle=c("N","R3"), Tn.above.3BG=TRUE, 
 #         TnBG.ratio.low=4, rseTn.up=10, outpdf="foo", outfile="foo")