Luminescence (version 0.2.2)

plot_GrowthCurve: Fit and plot a growth curve for luminescence data (Lx/Tx against dose)

Description

A dose response curve is produced for luminescence measurements using a regenerative protocol.

Usage

plot_GrowthCurve(sample, main = "Growth Curve", mtext = "",
                 fit.method = "EXP",
                 fit.weights = TRUE,
                 fit.includingRepeatedRegPoints = TRUE,
                 fit.NumberRegPoints,
                 fit.NumberRegPointsReal,
                 fit.bounds = TRUE,
                 NumberIterations.MC = 100, xlab = "s",
                 output.plot = TRUE, output.plotExtended = TRUE,
                 cex.global = 1)

Arguments

sample

data.frame (required): data frame with three columns for x=Dose,y=LxTx,z=LxTx.Error, y1=TnTx. The column for the test dose response is optional, but requires 'TnTx' as column name if used.

main

character (with default): header of the plot.

mtext

character (optional): additional text on the right side of the plot.

fit.method

character (with default): functions used for fitting. Possible options are: LIN, EXP, EXP OR LIN,EXP+LIN or EXP+EXP

fit.weights

logical (with default): option whether the fitting is done with or without weights. See details.

fit.includingRepeatedRegPoints

logical (with default): includes repeated points for fitting (TRUE/FALSE)

fit.NumberRegPoints

integer (optional): set number of regeneration points manually. By default the number of all(!) regeneration points is grepped automatically.

fit.NumberRegPointsReal

integer (optional): if the number of regeneration points is provided manually the value of the real regenerations points = all points - repeated points - reg 0 has to be inserted.

fit.bounds

logical (with default): set lower fit bounds for fitting parameter to 0. Limited for the use with the fit methods EXP, EXP+LIN and EXP OR LIN. Argument to be inserted for expe

NumberIterations.MC

integer (with default): number of Monte Carlo simulation for the error estimation. See details.

xlab

character (with default): unit for x-axis labelling. Possible values are "Gy" and "s".

output.plot

logical (with default): plot output (TRUE/FALSE).

output.plotExtended

logical (with default): If TRUE 3-plots on one plot area are provided: (1) growth curve, (2) histogram from error Monte Carlo simulation and (3) a test dose response plot. If FALSE, j

cex.global

numeric (with default): global scale factor.

Value

• list
  a list containing the De (De, De Error, D01 value, D02 value and Fit type) and Fit object nls object for EXP, EXP+LIN and EXP+EXP. In case of a linear fit EXP OR LIN, a lm object is returned.
• Plot
  A plot of the growth curve. A histogram for the error calculation and a test dose response plot.

Version

0.9.8 [2012-12-05]

Details

Fitting methods For all options (except for the LIN and the EXP OR LIN), the nls function with the port algorithm is used.

LIN: fit a linear function to the data using lm: $$y=mx+n$$ EXP: try to fit a function of the form $$y=a\ast (1-exp(-(x+c)/b))$$ Parameters b and c are approximated by a linear fit using lm. EXP OR LIN: works for some cases where an EXP fit failes. If the EXP fit failes, a LIN fit is done instead. EXP+LIN: try to fit an exponential plus linear function of the form:

$$y=a\ast (1-exp(-(x+c)/b)+(g\ast x))$$ The De is calculated by iteration. Note: In the context of luminescence dating, this function has no physical meaning. Therefore, no D0 value is returned. EXP+EXP: try to fit a double exponential function of the form $$y=(a1\ast (1-exp(-(x)/b1)))+(a2\ast (1-exp(-(x)/b2)))$$ This fitting procedure is not robust against wrong start parameters and should be further improved. Fit weighting (suggested by Michael Dietze and Margret Fuchs) If the option fit.weights = TRUE is chosen weights are calculated using provided signal errors (Lx/Tx error) and the equation:

$$fit.weights=1/error/(sum(1/error))$$

Error estimation using Monte Carlo simulation Error estimation is done using a Monte Carlo (MC) simulation approach. A set of values is constructed by randomly drawing curve data from a normal distribution. The normal distribution is defined by the input values (mean = value, sd = value.error). Then, a growth curve fit is attempted for each dataset which results in new distribution of values. The sd of this distribution is the error of the De. With increasing iterations, the error value is becoming more stable. Note: It may take some calculation time with increasing MC runs, especially for the composed functions (EXP+LIN and EXP+EXP).

Each error estimation is done with the function of the chosen fitting method.

References

Duller, G.A.T., 2007. Assessing the error on equivalent dose estimates derived from single aliquot regenerative dose measurements. Ancient TL, 25, pp. 15-24.

Galbraith, R.F. & Roberts, R.G., 2012. Statistical aspects of equivalent dose and error calculation and display in OSL dating: An overview and some recommendations. Quaternary Geochronology, 11, pp.1-27.

See Also

hist, plot, nls, lm

Examples

##(1) plot growth curve for a dummy data.set
data(ExampleData.LxTxData)
plot_GrowthCurve(LxTxData)
                                   
                                   
##(2) plot the growth curve only

##pdf(file = "~/Desktop/Growth_Curve_Dummy.pdf", paper = "special")
data(ExampleData.LxTxData)
plot_GrowthCurve(LxTxData)
##dev.off()                                   
                                   
##(3) plot growth curve with pdf output on desktop (path works for Mac)

##pdf(file = "~/Desktop/Growth_Curve_Dummy.pdf", paper = "special")
data(ExampleData.LxTxData)
plot_GrowthCurve(LxTxData)
##dev.off()