fit_LMCurve: Nonlinear Least Squares Fit for LM-OSL curves

Description

The function determines weighted nonlinear least-squares estimates of the component parameters of an LM-OSL curve (Bulur 1996) for a given number of components and returns various component parameters. The fitting procedure uses the function nls with the port algorithm.

Usage

fit_LMCurve(values, values.bg, n.components = 3, start_values, 
    input.dataType = "LM", sample_code = "", sample_ID = "", 
    LED.power = 36, LED.wavelength = 470, cex.global = 0.8, fit.trace = FALSE, 
    fit.advanced = FALSE, fit.calcError = FALSE, bg.subtraction = "polynomial", 
    output.path, output.terminal = TRUE, output.terminaladvanced = TRUE, 
    output.plot = TRUE, output.plotBG = FALSE, ...)

Arguments

values

RLum.Data.Curve or data.frame (required): x,y data of measured values (time and counts). See examples.

values.bg

RLum.Data.Curve or data.frame (optional): x,y data of measured values (time and counts) for background subtraction.

n.components

integer (with default): fixed number of components that are to be recognised during fitting (min = 1, max = 7).

start_values

data.frame (optional): start parameters for lm and xm data for the fit. If no start values are given, an automatic start value estimation is attempted (see details).

input.dataType

character (with default): alter the plot output depending on the input data: "LM" or "pLM" (pseudo-LM). See: CW2pLM

sample_code

character (optional): sample code used for the plot and the optional output table (mtext).

sample_ID

character (optional): additional identifier used as column header for the table output.

LED.power

numeric (with default): LED power (max.) used for intensity ramping in mW/cm^2. Note: This value is used for the calculation of the absolute photoionisation cross section.

LED.wavelength

numeric (with default): LED wavelength in nm used for stimulation. Note: This value is used for the calculation of the absolute photoionisation cross section.

cex.global

numeric (with default): global scaling factor.

fit.trace

logical (with default): traces the fitting process on the terminal.

fit.advanced

logical (with default): enables advanced fitting attempt for automatic start parameter recognition. Works only if no start parameters are provided. Note: It may take a while.

fit.calcError

logical (with default): calculate 1-sigma error range of components using confint.

bg.subtraction

character (with default): specifies method for background subtraction (polynomial, linear, channel, see Details). Note: requires input for values.bg.

output.path

character (optional): output path for table output containing the results of the fit. The file name is set automatically. If the file already exists in the directory, the values are appended.

output.terminal

logical (with default): terminal output with fitting results.

output.terminaladvanced

logical (with default): enhanced terminal output. Requires output.terminal = TRUE. If output.terminal = FALSE no advanced output is possible.

output.plot

logical (with default): returns a plot of the fitted curves.

output.plotBG

logical (with default): returns a plot of the background values with the fit used for the background subtraction.

...

Further arguments that may be passed to the plot output, e.g. xlab, xlab, main, log.

Value

plot(optional) various types of plots are returned. For details see above.
table(optional) an output table (*.csv) with the fitted components is provided if the output.path is set.
list objectbeside the plot and table output, a list is returned. The list contains: (a) an nls object ($fit) for which generic R functions are provided, e.g. summary, confint, profile. For more details, see nls. (b) a data.frame containing the summarised parameters including the error ($output.table). (c) a matrix containing the values for the component to sum contribution plot ($component.contribution.matrix). Matrix structure: Column 1 and 2: time and rev(time) values Additional columns are used for the components, two for each component, containing I0 and n0

Details

Fitting function The function for the fitting has the general form: $$y = (exp(0.5)*Im_1*x/xm_1)*exp(-x^2/(2*xm_1^2)) + ,\ldots, + exp(0.5)*Im_i*x/xm_i)*exp(-x^2/(2*xm_i^2))$$ where $1 < i < 8$ This function and the equations for the conversion to b (detrapping probability) and n0 (proportional to initially trapped charge) have been taken from Kitis et al. (2008): $$xm_i=\sqrt{max(t)/b_i}$$ $$Im_i=exp(-0.5)n0/xm_i$$ Background subtraction Three methods for background subtraction are provided for a given background signal (values.bg). polynomial: default method. A polynomial function is fitted using glm and the resulting function is used for background subtraction: $$y = a*x^4 + b*x^3 + c*x^2 + d*x + e$$ linear: a linear function is fitted using glm and the resulting function is used for background subtraction: $$y = a*x + b$$ channel: the measured background signal is subtracted channelwise from the measured signal. Start values The choice of the initial parameters for the nls-fitting is a crucial point and the fitting procedure may mainly fail due to ill chosen start parameters. Here, three options are provided: (a) If no start values (start_values) are provided by the user, a cheap guess is made by using the detrapping values found by Jain et al. (2003) for quartz for a maximum of 7 components. Based on these values, the pseudo start parameters xm and Im are recalculated for the given data set. In all cases, the fitting starts with the ultra-fast component and (depending on n.components) steps through the following values. If no fit could be achieved, an error plot (for output.plot = TRUE) with the pseudo curve (based on the pseudo start parameters) is provided. This may give the opportunity to identify appropriate start parameters visually. (b) If start values are provided, the function works like a simple nls fitting approach. (c) If no start parameters are provided and the option fit.advanced = TRUE is chosen, an advanced start paramter estimation is applied using a stochastical attempt. Therefore, the recalculated start parameters (a) are used to construct a normal distribution. The start parameters are then sampled randomly from this distribution. A maximum of 100 attempts will be made. Note: This process may be time consuming. Goodness of fit The goodness of the fit is given by a pseudoR^2 value (pseudo coefficient of determination). According to Lave (1970), the value is calculated as: $$pseudoR^2 = 1 - RSS/TSS$$ where $RSS = Residual~Sum~of~Squares$ and $TSS = Total~Sum~of~Squares$ Error of fitted component parameters The 1-sigma error for the components is calculated using the function confint. Due to considerable calculation time, this option is deactived by default. In addition, the error for the components can be estimated by using internal R functions like summary. See the nls help page for more information. For more details on the nonlinear regression in R, see Ritz & Streibig (2008).

References

Bulur, E., 1996. An Alternative Technique For Optically Stimulated Luminescence (OSL) Experiment. Radiation Measurements, 26, 5, 701-709. Jain, M., Murray, A.S., Boetter-Jensen, L., 2003. Characterisation of blue-light stimulated luminescence components in different quartz samples: implications for dose measurement. Radiation Measurements, 37, 4-5, 441-449. Kitis, G. & Pagonis, V., 2008. Computerized curve deconvolution analysis for LM-OSL. Radiation Measurements, 43, 737-741. Lave, C.A.T., 1970. The Demand for Urban Mass Transportation. The Review of Economics and Statistics, 52, 3, 320-323. Ritz, C. & Streibig, J.C., 2008. Nonlinear Regression with R. R. Gentleman, K. Hornik, & G. Parmigiani, eds., Springer, p. 150.

Examples

Run this code

##(1) fit LM data without background subtraction 
data(ExampleData.FittingLM, envir = environment())
fit_LMCurve(values = values.curve, n.components = 3, log = "x")

##(2) fit LM data with background subtraction and export as JPEG
## -alter file path for your preferred system
##jpeg(file = "~/Desktop/Fit_Output\\%03d.jpg", quality = 100, 
## height = 3000, width = 3000, res = 300)
data(ExampleData.FittingLM, envir = environment())
fit_LMCurve(values = values.curve, values.bg = values.curveBG,
            n.components = 2, log = "x", output.plotBG = TRUE)
##dev.off()

##(3) fit LM data with manual start parameters
data(ExampleData.FittingLM, envir = environment())
fit_LMCurve(values = values.curve, 
            values.bg = values.curveBG, 
            n.components = 3, 
            log = "x",
            start_values = data.frame(Im = c(170,25,400), xm = c(56,200,1500)))

Run the code above in your browser using DataLab