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. For exponential
fits at least three dose points (including the natural) should be provided.
na.rm
logical (with default): excludes NA values
from the data set prior to any further operations.
fit.method
character (with default): function used for
fitting. Possible options are: LIN, QDR, EXP, EXP OR LIN,
EXP+LIN or EXP+EXP. See details.
fit.force_through_origin
logical (with default) allow to force
the fitted function through the origin. For method = "EXP+EXP" the function will
go to the origin in either case, so this option will have no effect.
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 inserted
for experimental application only!
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, just the growth curve will be plotted.
Requires:output.plot = TRUE.
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 = TRUE.
cex.global
numeric (with default): global scaling
factor.
txtProgressBar
logical (with default): enables or disables txtProgressBar.
If verbose = FALSE also no txtProgressBar is shown.
verbose
logical (with default): enables or disables terminal feedback.
...
Further arguments and graphical parameters to be passed. Note:
Standard arguments will only be passed to the growth curve plot. Supported:
xlim, ylim, main, xlab, ylab
Details
Fitting methods
For all options (except for the LIN, QDR and
the EXP OR LIN), the nlsLM function with the
LM (Levenberg-Marquardt algorithm) algorithm is used. Note: For historical reasons
for the Monte Carlo simulations partly the function nls using the port algorithm.
The solution is found by transforming the function or using uniroot.
LIN: fits a linear function to the data using
lm:
y = m*x+n
QDR: fits a linear function to the data using
lm:
y = a + b * x + c * x^2
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.
Value
Along with a plot (so far wanted) an RLum.Results object is returned containing,
the slot data contains the following elements:
DATA.OBJECT
TYPE
DESCRIPTION
..$De :
data.frame
Table with De values
..$De.MC :
numeric
Table with De values from MC runs
..$Fit :
nls or lm
object from the fitting for EXP,
EXP+LIN and EXP+EXP. In case of a resulting linear fit when using LIN, QDR or
EXP OR LIN
..$Formula :
expression
Fitting formula as R expression
..$call :
call
The original function call
Function version
1.8.12 (2016-05-29 17:57:29)
Author(s)
Sebastian Kreutzer, IRAMAT-CRP2A, Universite Bordeaux Montaigne
(France), Michael Dietze, GFZ Potsdam (Germany)
R Luminescence Package Team
See Also
nls, RLum.Results,
get_RLum, nlsLM, lm, uniroot
Examples
##(1) plot growth curve for a dummy data.set and show De value
data(ExampleData.LxTxData, envir = environment())
temp <- plot_GrowthCurve(LxTxData)
get_RLum(temp)
##(1a) to access the fitting value try
get_RLum(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()
Results
R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)
R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.
R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.
Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.
> library(Luminescence)
Welcome to the R package Luminescence version 0.6.0 [Built: 2016-05-30 16:47:30 UTC]
The undecided OSL component: 'Should I stay or should I go?'
> png(filename="/home/ddbj/snapshot/RGM3/R_CC/result/Luminescence/plot_GrowthCurve.Rd_%03d_medium.png", width=480, height=480)
> ### Name: plot_GrowthCurve
> ### Title: Fit and plot a growth curve for luminescence data (Lx/Tx against
> ### dose)
> ### Aliases: plot_GrowthCurve
>
> ### ** Examples
>
>
> ##(1) plot growth curve for a dummy data.set and show De value
> data(ExampleData.LxTxData, envir = environment())
> temp <- plot_GrowthCurve(LxTxData)
[plot_GrowthCurve()] Fit: EXP | De = 1737.88 | D01 = 1766.07
> get_RLum(temp)
De De.Error D01 D01.ERROR D02 D02.ERROR De.MC Fit
1 1737.88 53.35 1766.07 85.97893 NA NA 1732.3 EXP
>
> ##(1a) to access the fitting value try
> get_RLum(temp, data.object = "Fit")
Nonlinear regression model
model: y ~ a * (1 - exp(-(x + c)/b))
data: data
a b c
6.806 1766.074 5.051
weighted residual sum-of-squares: 0.0004268
Number of iterations to convergence: 4
Achieved convergence tolerance: 1.49e-08
>
> ##(2) plot the growth curve only - uncomment to use
> ##pdf(file = "~/Desktop/Growth_Curve_Dummy.pdf", paper = "special")
> plot_GrowthCurve(LxTxData)
[plot_GrowthCurve()] Fit: EXP | De = 1737.88 | D01 = 1766.07
> ##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)
[plot_GrowthCurve()] Fit: EXP | De = 1737.88 | D01 = 1766.07
> ##dev.off()
>
>
>
>
>
>
> dev.off()
null device
1
>