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, na.rm = TRUE, main = "Growth curve", 
    fit.method = "EXP", fit.weights = TRUE, fit.includingRepeatedRegPoints = TRUE, 
    fit.NumberRegPoints, fit.NumberRegPointsReal, fit.bounds = TRUE, 
    NumberIterations.MC = 100, output.plot = TRUE, output.plotExtended = TRUE, 
    output.plotExtended.single = FALSE, 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.

na.rm

logical (with default): excludes NA values from the data set prior to any further operations.

main

character (with default): header of the plot.

fit.method

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

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 used automatically.

fit.NumberRegPointsReal

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

fit.bounds

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

NumberIterations.MC

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

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 Monte Carlo error simulation and (3) a test dose response plot. If FALSE

output.plotExtended.single

logical (with default): 
single plot output (TRUE/FALSE) to allow for plotting the results 
in single plot windows. 
Requires output.plot = TRUE and output.plotExtended =

cex.global

numeric (with default): global scaling factor.

...

Further arguments and graphical parameters to be passed. Note: Standard 
arguments will only be passed to the growth curve plot

`Value`

RLum.Results object containing the De (De, De Error, D01 value, D02 value, De.MC and Fit 
type) and the fit object nls object for EXP, EXP+LIN 
and EXP+EXP. In case of a resulting linear fit when using 
EXP OR LIN, a lm object is returned. 
The formula Formula is returned as R expression for further evaluation.
Additionally a plot is returned.

`Function version`

1.3 (2015-01-24 23:35:48)

`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: fits a linear function to the data using lm:
$$y = m*x+n$$
EXP: try to fit a function of the form 
$$y = a*(1-exp(-(x+c)/b))$$
Parameters b and c are approximated by a linear fit using lm.
Note: b = D0
EXP OR LIN: works for some cases where an EXP fit fails. 
If the EXP fit fails, a LIN fit is done instead. 
EXP+LIN: tries to fit an exponential plus linear function of the 
form: $$y = a*(1-exp(-(x+c)/b)+(g*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: tries to fit a double exponential function of the form
$$y = (a1*(1-exp(-(x)/b1)))+(a2*(1-exp(-(x)/b2)))$$
This fitting procedure is not robust against wrong start parameters 
and should be further improved.

Fit weighting
If the option fit.weights = TRUE is chosen, weights are calculated 
using provided signal errors (Lx/Tx error):
$$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 Lx/Tx values is constructed by randomly drawing curve data from samled from normal 
distributions. The normal distribution is defined by the input values 
(mean = value, sd = value.error). Then, a growth curve fit is attempted 
for each dataset resulting in a new distribution of single De values. The 
sd of this distribution is becomes then the error of the De. With increasing 
iterations, the error value becomes 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. 
Subtitle information
To avoid plotting the subtitle information, provide an empty user mtext
mtext = "". To plot any other subtitle text, use mtext.

`Examples`

Run this code##(1) plot growth curve for a dummy data.set and show De value
data(ExampleData.LxTxData, envir = environment())
temp <- plot_GrowthCurve(LxTxData)
get_RLum.Results(temp)

##(1a) to access the fitting value try
get_RLum.Results(temp, data.object = "Fit")
  
##(2) plot the growth curve only - uncomment to use
##pdf(file = "~/Desktop/Growth_Curve_Dummy.pdf", paper = "special")
plot_GrowthCurve(LxTxData)
##dev.off()                                   

##(3) plot growth curve with pdf output - uncomment to use, single output
##pdf(file = "~/Desktop/Growth_Curve_Dummy.pdf", paper = "special")
plot_GrowthCurve(LxTxData, output.plotExtended.single = TRUE)
##dev.off()
Run the code above in your browser using DataLab