fitGrowth: Growth curve fitting

Description Usage Arguments Details Value Note References See Also Examples

View source: R/fitGrowth.R

Description

Fitting growth curves using the Levenberg-Marquardt algorithm.

Usage

1
2
3
4
5
6
7
8
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 http://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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 ### 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 May 1, 2019, 8:45 p.m.