fitGrowth: Growth curve fitting
In numOSL: Numeric Routines for Optically Stimulated Luminescence Dating
fitGrowth R Documentation
Growth curve fitting
Description
Fitting growth curves using the Levenberg-Marquardt algorithm.
Usage
fitGrowth(Curvedata, model = "gok", origin = FALSE,
weight = TRUE, trial = FALSE, plot = TRUE,
nofit.rgd = NULL, agID = NULL, Tn = NULL,
Tn3BG = NULL, TnBG.ratio = NULL, rseTn = NULL,
FR = NULL, RecyclingRatio1 = NULL,
RecyclingRatio2 = NULL, RecyclingRatio3 = NULL,
Recuperation1 = NULL, Recuperation2 = 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)
model
character(with default): model used for growth curve fitting, see details
origin
logical(optional): logical value indicating if the growth curve should be forced to pass the origin
weight
logical(with default): logical value indicating if the growth curve should be fitted using a weighted procedure, see details
trial
logical(with default): logical value indicating if the growth curve should be fitted using other models if the given model fails, see 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=c(5,6) then both the fifth and sixth regenerative doses 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
Tn
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
FR
vector(optional): a two-element vector containing value and
standard error of fast ratio of Tn
RecyclingRatio1
vector(optional): a two-element vector containing value and
standard error of the first recycling ratio
RecyclingRatio2
vector(optional): a two-element vector containing value and
standard error of the second recycling ratio
RecyclingRatio3
vector(optional): a two-element vector containing value and
standard error of the third recycling ratio
Recuperation1
vector(optional): a two-element vector containing value and
standard error of the first recuperation
Recuperation2
vector(optional): a two-element vector containing value and
standard error of the second recuperation
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
Details
In growth curve fitting using function fitGrowth, five models are available:
(1) "line": a linear model, y=a*x+b;
(2) "exp": a single saturation exponential model, y=a*[1-exp(-b*x)]+c;
(3) "lexp": a single saturation exponential plus linear model, y=a*[1-exp(-b*x)]+c*x+d;
(4) "dexp": a double saturation exponential model, y=a*[1-exp(-b*x)]+c*[1-exp(-d*x)]+e;
(5) "gok": a general order kinetic model (Guralnik et al., 2015), y=a*[1-(1+b*c*x)^(-1/c)]+d.
The fitting process is performed using the Levenberg-Marquardt algorithm (minpack: Fortran 90 source code by John Burkardt, freely available at https://people.sc.fsu.edu/~jburkardt/f_src/minpack/minpack.html). If weight=TRUE, a weighted procedure will be performed through weighting each data point by its inverse variance. User is advised to set argument plot=TRUE if possible to visualize the quality of fit.
Argument trial=TRUE means that if the growth curve can not be fitted successfully using the user-supplied model, then the procedure will try to fit other models instead:
Model Tried model
"dexp" c("dexp", "gok", "exp", "line")
"lexp" c("lexp", "gok", "exp", "line")
"gok" c("gok", "exp", "line")
"exp" c("exp", "line")
"line" c("line")
For example, if model="dexp" and trial=TRUE, then a number of models from sequence
c("dexp", "gok", "exp", "line") will be applied one after another until the fit succeeds.
The required number of data points for each model is (value inside the parentheses denotes the required number of observations if the model passes the origin):
Model Required NPoints
"dexp" >=5 (>=4)
"lexp" >=4 (>=3)
"gok" >=4 (>=3)
"exp" >=3 (>=2)
"line" >=2 (>=1)
If user-provided data is not enough for model fitting (i.e., the number of data points is less than the number of parameters of a given model),
then a model with less parameters will be fitted. For example, if 4 data points are fitted using a "dexp" (origin=FALSE) model that actually needs at least 5 data points,
then a 4-parameter "gok" model will be fitted instead.
Value
Return a list that contains the following elements:
message
return 0 if the fit succeeds, else 1
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
Note
Arguments agID, Tn, Tn3BG, TnBG.ratio, rseTn, FR,
RecyclingRatio1, RecyclingRatio2, RecyclingRatio3,
Recuperation1, Recuperation2, LnTn.curve, TxTn have nothing to do with growth curve fitting. They are used only for plotting purpose.
The model to be optimized should not be underdetermined. This means that the number of data points should exceed (or at least be equal to) the number of parameters. For a given model, the procedure will return an error if any standard errors of parameters cannot be estimated by numerical difference-approximation.
References
Balian HG, Eddy NW, 1977. Figure-of-merit (FOM), an improved criterion over the normalized chi-squared test for assessing
goodness-of-fit of gamma-ray spectral peaks. Nuclear Instruments and Methods, 145(2): 389-95.
Guralnik B, Li B, Jain M, Chen R, Paris RB, Murray AS, Li SH, Pagonis V, Valla PG, Herman F, 2015. Radiation-induced growth and isothermal decay of
infrared-stimulated luminescence from feldspar. Radiation Measurements, 81: 224-231.
More JJ, 1978. "The Levenberg-Marquardt algorithm: implementation and theory" in Lecture Notes in Mathematics: Numerical Analysis,
Springer-Verlag: Berlin. 105-116.
See Also
analyseBINdata; SARdata; calED; calSARED; fastED;
pickSARdata; lsNORM; calSGCED
Examples
### 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))
fitGrowth(Curvedata, model="gok", origin=FALSE, plot=TRUE)
### Example 2 (not run):
# data(SARdata)
# Curvedata <- SARdata[!is.element(SARdata[,2], "N"),3:5]
# fitGrowth(Curvedata, model="gok", origin=FALSE)
numOSL documentation built on Sept. 18, 2023, 9:07 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| fitGrowth | R Documentation |
Growth curve fitting
Description
Fitting growth curves using the Levenberg-Marquardt algorithm.
Usage
fitGrowth(Curvedata, model = "gok", origin = FALSE,
weight = TRUE, trial = FALSE, plot = TRUE,
nofit.rgd = NULL, agID = NULL, Tn = NULL,
Tn3BG = NULL, TnBG.ratio = NULL, rseTn = NULL,
FR = NULL, RecyclingRatio1 = NULL,
RecyclingRatio2 = NULL, RecyclingRatio3 = NULL,
Recuperation1 = NULL, Recuperation2 = NULL,
LnTn.curve = NULL, TxTn = NULL)
Arguments
Curvedata |
matrix(required): a three-column matrix (i.e., regenerative doses, |
model |
character(with default): model used for growth curve fitting, see details |
origin |
logical(optional): logical value indicating if the growth curve should be forced to pass the origin |
weight |
logical(with default): logical value indicating if the growth curve should be fitted using a weighted procedure, see details |
trial |
logical(with default): logical value indicating if the growth curve should be fitted using other models if the given model fails, see 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 |
agID |
vector(optional): a three-elemenet vector indicating aliquot (grain) ID, i.e., |
Tn |
vector(optional): a two-element vector containing value and |
Tn3BG |
numeric(optional): 0-1 value indicating if Tn is more than 3 sigma above BG, |
TnBG.ratio |
vector(optional): a two-element vector containing value and |
rseTn |
numeric(optional): relative standard error of Tn in percent |
FR |
vector(optional): a two-element vector containing value and |
RecyclingRatio1 |
vector(optional): a two-element vector containing value and |
RecyclingRatio2 |
vector(optional): a two-element vector containing value and |
RecyclingRatio3 |
vector(optional): a two-element vector containing value and |
Recuperation1 |
vector(optional): a two-element vector containing value and |
Recuperation2 |
vector(optional): a two-element vector containing value and |
LnTn.curve |
list(optional): decay curve data for Ln and Tn, it should contain four elements,
i.e., |
TxTn |
vector(optional): ratios of Tx to Tn for various SAR cycles |
Details
In growth curve fitting using function fitGrowth, five models are available:
(1) "line": a linear model, y=a*x+b;
(2) "exp": a single saturation exponential model, y=a*[1-exp(-b*x)]+c;
(3) "lexp": a single saturation exponential plus linear model, y=a*[1-exp(-b*x)]+c*x+d;
(4) "dexp": a double saturation exponential model, y=a*[1-exp(-b*x)]+c*[1-exp(-d*x)]+e;
(5) "gok": a general order kinetic model (Guralnik et al., 2015), y=a*[1-(1+b*c*x)^(-1/c)]+d.
The fitting process is performed using the Levenberg-Marquardt algorithm (minpack: Fortran 90 source code by John Burkardt, freely available at https://people.sc.fsu.edu/~jburkardt/f_src/minpack/minpack.html). If weight=TRUE, a weighted procedure will be performed through weighting each data point by its inverse variance. User is advised to set argument plot=TRUE if possible to visualize the quality of fit.
Argument trial=TRUE means that if the growth curve can not be fitted successfully using the user-supplied model, then the procedure will try to fit other models instead:
| Model | Tried model |
"dexp" | c("dexp", "gok", "exp", "line") |
"lexp" | c("lexp", "gok", "exp", "line") |
"gok" | c("gok", "exp", "line") |
"exp" | c("exp", "line") |
"line" | c("line")
|
For example, if model="dexp" and trial=TRUE, then a number of models from sequence
c("dexp", "gok", "exp", "line") will be applied one after another until the fit succeeds.
The required number of data points for each model is (value inside the parentheses denotes the required number of observations if the model passes the origin):
| Model | Required NPoints |
"dexp" | >=5 (>=4) |
"lexp" | >=4 (>=3) |
"gok" | >=4 (>=3) |
"exp" | >=3 (>=2) |
"line" | >=2 (>=1) |
If user-provided data is not enough for model fitting (i.e., the number of data points is less than the number of parameters of a given model),
then a model with less parameters will be fitted. For example, if 4 data points are fitted using a "dexp" (origin=FALSE) model that actually needs at least 5 data points,
then a 4-parameter "gok" model will be fitted instead.
Value
Return a list that contains the following elements:
message |
return 0 if the fit succeeds, else 1 |
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 |
Note
Arguments agID, Tn, Tn3BG, TnBG.ratio, rseTn, FR,
RecyclingRatio1, RecyclingRatio2, RecyclingRatio3,
Recuperation1, Recuperation2, LnTn.curve, TxTn have nothing to do with growth curve fitting. They are used only for plotting purpose.
The model to be optimized should not be underdetermined. This means that the number of data points should exceed (or at least be equal to) the number of parameters. For a given model, the procedure will return an error if any standard errors of parameters cannot be estimated by numerical difference-approximation.
References
Balian HG, Eddy NW, 1977. Figure-of-merit (FOM), an improved criterion over the normalized chi-squared test for assessing goodness-of-fit of gamma-ray spectral peaks. Nuclear Instruments and Methods, 145(2): 389-95.
Guralnik B, Li B, Jain M, Chen R, Paris RB, Murray AS, Li SH, Pagonis V, Valla PG, Herman F, 2015. Radiation-induced growth and isothermal decay of infrared-stimulated luminescence from feldspar. Radiation Measurements, 81: 224-231.
More JJ, 1978. "The Levenberg-Marquardt algorithm: implementation and theory" in Lecture Notes in Mathematics: Numerical Analysis, Springer-Verlag: Berlin. 105-116.
See Also
analyseBINdata; SARdata; calED; calSARED; fastED;
pickSARdata; lsNORM; calSGCED
Examples
### 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))
fitGrowth(Curvedata, model="gok", origin=FALSE, plot=TRUE)
### Example 2 (not run):
# data(SARdata)
# Curvedata <- SARdata[!is.element(SARdata[,2], "N"),3:5]
# fitGrowth(Curvedata, model="gok", origin=FALSE)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.