fit_CWCurve: Nonlinear Least Squares Fit for CW-OSL curves -beta version-
In Luminescence: Comprehensive Luminescence Dating Data Analysis
fit_CWCurve R Documentation
Nonlinear Least Squares Fit for CW-OSL curves -beta version-
Description
The function determines the weighted least-squares estimates of the
component parameters of a CW-OSL signal for a given maximum number of
components and returns various component parameters. The fitting procedure
uses the nls function with the port algorithm.
Usage
fit_CWCurve(
values,
n.components.max,
fit.failure_threshold = 5,
fit.method = "port",
fit.trace = FALSE,
fit.calcError = FALSE,
LED.power = 36,
LED.wavelength = 470,
cex.global = 0.6,
sample_code = "Default",
output.path,
output.terminal = TRUE,
output.terminalAdvanced = TRUE,
plot = TRUE,
...
)
Arguments
values
RLum.Data.Curve or data.frame (required):
x, y data of measured values (time and counts). See examples.
n.components.max
vector (optional):
maximum number of components that are to be used for fitting.
The upper limit is 7.
fit.failure_threshold
vector (with default):
limits the failed fitting attempts.
fit.method
character (with default):
select fit method, allowed values: 'port' and 'LM'. 'port' uses the 'port'
routine from the function nls 'LM' utilises the function nlsLM from
the package minpack.lm and with that the Levenberg-Marquardt algorithm.
fit.trace
logical (with default):
traces the fitting process on the terminal.
fit.calcError
logical (with default):
calculate 1-sigma error range of components using stats::confint
LED.power
numeric (with default):
LED power (max.) used for intensity ramping in mW/cm^2.
Note: The value is used for the calculation of the absolute
photoionisation cross section.
LED.wavelength
numeric (with default):
LED wavelength used for stimulation in nm.
Note: The value is used for the calculation of the absolute
photoionisation cross section.
cex.global
numeric (with default):
global scaling factor.
sample_code
character (optional):
sample code used for the plot and the optional output table (mtext).
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.
plot
logical (with default):
returns a plot of the fitted curves.
...
further arguments and graphical parameters passed to plot.
Details
Fitting function
The function for the CW-OSL fitting has the general form:
y = I0_{1}*\lambda_{1}*exp(-\lambda_1*x) + ,\ldots, + I0_{i}*\lambda_{i}*exp(-\lambda_i*x)
where 0 < i < 8
and \lambda is the decay constant
and I0 the initial number of trapped electrons.
(for the used equation cf. Boetter-Jensen et al., 2003, Eq. 2.31)
Start values
Start values are estimated automatically by fitting a linear function to the
logarithmized input data set. Currently, there is no option to manually
provide start parameters.
Goodness of fit
The goodness of the fit is given as 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 stats::confint. Due to
considerable calculation time, this option is deactivated 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 details on the nonlinear regression in R, see Ritz & Streibig (2008).
Value
plot (optional)
the fitted CW-OSL curves are returned as plot.
table (optional)
an output table (*.csv) with parameters of the fitted components is
provided if the output.path is set.
RLum.Results
Beside the plot and table output options, an RLum.Results object is
returned.
fit:
an nls object ($fit) for which generic R functions are
provided, e.g. summary, stats::confint, profile. For more
details, see nls.
output.table:
a data.frame containing the summarised parameters including the error
component.contribution.matrix:
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. The last columns cont. provide information on
the relative component contribution for each time interval including the row
sum for this values.
object
beside the plot and table output options, an RLum.Results object
is returned.
fit:
an nls object ($fit) for which generic R functions
are provided, e.g. summary, confint, profile. For more
details, see nls.
output.table:
a data.frame containing the summarised parameters including the error
component.contribution.matrix: 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. The last columns cont. provide information on
the relative component contribution for each time interval including the row
sum for this values.
Function version
0.5.2
How to cite
Kreutzer, S., 2024. fit_CWCurve(): Nonlinear Least Squares Fit for CW-OSL curves -beta version-. Function version 0.5.2. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.24. https://CRAN.R-project.org/package=Luminescence
Note
Beta version - This function has not been properly tested yet and
should therefore not be used for publication purposes!
The pseudo-R^2 may not be the best parameter to describe the goodness of the
fit. The trade off between the n.components and the pseudo-R^2 value
is currently not considered.
The function does not ensure that the fitting procedure has reached a
global minimum rather than a local minimum!
Author(s)
Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany)
, RLum Developer Team
References
Boetter-Jensen, L., McKeever, S.W.S., Wintle, A.G., 2003.
Optically Stimulated Luminescence Dosimetry. Elsevier Science B.V.
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. In: R.
Gentleman, K. Hornik, G. Parmigiani, eds., Springer, p. 150.
See Also
fit_LMCurve, plot,nls, RLum.Data.Curve,
RLum.Results, get_RLum, minpack.lm::nlsLM
Examples
##load data
data(ExampleData.CW_OSL_Curve, envir = environment())
##fit data
fit <- fit_CWCurve(values = ExampleData.CW_OSL_Curve,
main = "CW Curve Fit",
n.components.max = 4,
log = "x")
Luminescence documentation built on June 22, 2024, 9:54 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.
| fit_CWCurve | R Documentation |
Nonlinear Least Squares Fit for CW-OSL curves -beta version-
Description
The function determines the weighted least-squares estimates of the
component parameters of a CW-OSL signal for a given maximum number of
components and returns various component parameters. The fitting procedure
uses the nls function with the port algorithm.
Usage
fit_CWCurve(
values,
n.components.max,
fit.failure_threshold = 5,
fit.method = "port",
fit.trace = FALSE,
fit.calcError = FALSE,
LED.power = 36,
LED.wavelength = 470,
cex.global = 0.6,
sample_code = "Default",
output.path,
output.terminal = TRUE,
output.terminalAdvanced = TRUE,
plot = TRUE,
...
)
Arguments
values |
RLum.Data.Curve or data.frame (required): x, y data of measured values (time and counts). See examples. |
n.components.max |
vector (optional): maximum number of components that are to be used for fitting. The upper limit is 7. |
fit.failure_threshold |
vector (with default): limits the failed fitting attempts. |
fit.method |
character (with default):
select fit method, allowed values: |
fit.trace |
logical (with default): traces the fitting process on the terminal. |
fit.calcError |
logical (with default): calculate 1-sigma error range of components using stats::confint |
LED.power |
numeric (with default): LED power (max.) used for intensity ramping in mW/cm^2. Note: The value is used for the calculation of the absolute photoionisation cross section. |
LED.wavelength |
numeric (with default): LED wavelength used for stimulation in nm. Note: The value is used for the calculation of the absolute photoionisation cross section. |
cex.global |
numeric (with default): global scaling factor. |
sample_code |
character (optional):
sample code used for the plot and the optional output table ( |
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 |
plot |
logical (with default): returns a plot of the fitted curves. |
... |
further arguments and graphical parameters passed to plot. |
Details
Fitting function
The function for the CW-OSL fitting has the general form:
y = I0_{1}*\lambda_{1}*exp(-\lambda_1*x) + ,\ldots, + I0_{i}*\lambda_{i}*exp(-\lambda_i*x)
where 0 < i < 8
and \lambda is the decay constant
and I0 the initial number of trapped electrons.
(for the used equation cf. Boetter-Jensen et al., 2003, Eq. 2.31)
Start values
Start values are estimated automatically by fitting a linear function to the logarithmized input data set. Currently, there is no option to manually provide start parameters.
Goodness of fit
The goodness of the fit is given as 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 stats::confint. Due to considerable calculation time, this option is deactivated 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 details on the nonlinear regression in R, see Ritz & Streibig (2008).
Value
plot (optional)
the fitted CW-OSL curves are returned as plot.
table (optional)
an output table (*.csv) with parameters of the fitted components is
provided if the output.path is set.
RLum.Results
Beside the plot and table output options, an RLum.Results object is returned.
fit:
an nls object ($fit) for which generic R functions are
provided, e.g. summary, stats::confint, profile. For more
details, see nls.
output.table:
a data.frame containing the summarised parameters including the error
component.contribution.matrix:
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. The last columns cont. provide information on
the relative component contribution for each time interval including the row
sum for this values.
object
beside the plot and table output options, an RLum.Results object is returned.
fit:
an nls object ($fit) for which generic R functions
are provided, e.g. summary, confint, profile. For more
details, see nls.
output.table:
a data.frame containing the summarised parameters including the error
component.contribution.matrix: 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. The last columns cont. provide information on
the relative component contribution for each time interval including the row
sum for this values.
Function version
0.5.2
How to cite
Kreutzer, S., 2024. fit_CWCurve(): Nonlinear Least Squares Fit for CW-OSL curves -beta version-. Function version 0.5.2. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.24. https://CRAN.R-project.org/package=Luminescence
Note
Beta version - This function has not been properly tested yet and should therefore not be used for publication purposes!
The pseudo-R^2 may not be the best parameter to describe the goodness of the
fit. The trade off between the n.components and the pseudo-R^2 value
is currently not considered.
The function does not ensure that the fitting procedure has reached a global minimum rather than a local minimum!
Author(s)
Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany) , RLum Developer Team
References
Boetter-Jensen, L., McKeever, S.W.S., Wintle, A.G., 2003. Optically Stimulated Luminescence Dosimetry. Elsevier Science B.V.
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. In: R. Gentleman, K. Hornik, G. Parmigiani, eds., Springer, p. 150.
See Also
fit_LMCurve, plot,nls, RLum.Data.Curve, RLum.Results, get_RLum, minpack.lm::nlsLM
Examples
##load data
data(ExampleData.CW_OSL_Curve, envir = environment())
##fit data
fit <- fit_CWCurve(values = ExampleData.CW_OSL_Curve,
main = "CW Curve Fit",
n.components.max = 4,
log = "x")
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.