R: Growth curve fitting

fitGrowth {numOSL}

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.

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)

[Package numOSL version 2.8 Index]