fit_OSLLifeTimes: Fitting and Deconvolution of OSL Lifetime Components
In Luminescence: Comprehensive Luminescence Dating Data Analysis
View source: R/fit_OSLLifeTimes.R
fit_OSLLifeTimes R Documentation
Fitting and Deconvolution of OSL Lifetime Components
Description
Fitting and Deconvolution of OSL Lifetime Components
Usage
fit_OSLLifeTimes(
object,
tp = 0,
signal_range = NULL,
n.components = NULL,
method_control = list(),
plot = TRUE,
plot_simple = FALSE,
verbose = TRUE,
...
)
Arguments
object
RLum.Data.Curve, RLum.Analysis, data.frame or matrix (required):
Input object containing the data to be analysed. All objects can be provided also as list for an automated
processing. Please note: NA values are automatically removed and the dataset should comprise at least 5 data points.
tp
numeric (with default): option to account for the stimulation pulse width. For off-time measurements
the default value is 0. tp has the same unit as the measurement data, e.g., µs. Please set this parameter
carefully, if it all, otherwise you may heavily bias your fit results.
signal_range
numeric (optional): allows to set a channel range, by default all channels are used, e.g.
signal_range = c(2,100) considers only channels 2 to 100 and signal_range = c(2) considers only channels
from channel 2 onwards.
n.components
numeric (optional): Fix the number of components. If set the algorithm will try
to fit the number of predefined components. If nothing is set, the algorithm will try to find the best number
of components.
method_control
list (optional): Named to allow a more fine control of the fitting process. See details
for allowed options.
plot
logical (with default): Enable/disable plot output
plot_simple
logical (with default): Enable/disable reduced plot output. If TRUE, no
residual plot is shown, however, plot output can be combined using the standard R layout options,
such as par(mfrow = c(2,2)).
verbose
logical (with default): Enable/disable terminal feedback
...
parameters passed to plot.default to control the plot output, supported are:
main, xlab, ylab, log, xlim, ylim, col, lty, legend.pos, legend.text. If the input
object is of type RLum.Analysis this arguments can be provided as a list.
Details
The function intends to provide an easy access to pulsed optically stimulated luminescence (POSL) data,
in order determine signal lifetimes. The fitting is currently optimised to work with the off-time flank of POSL measurements
only. For the signal deconvolution, a differential evolution optimisation is combined with nonlinear least-square fitting
following the approach by Bluszcz & Adamiec (2006).
Component deconvolution algorithm
The component deconvolution consists of two steps:
(1) Adaptation phase
In the adaptation phase the function tries to figure out the optimal and statistically justified
number of signal components following roughly the approach suggested by Bluszcz & Adamiec (2006). In
contrast to their work, for the optimisation by differential evolution here the package 'DEoptim' is used.
The function to be optimized has the form:
\chi^2 = \sum(w * (n_i/c - \sum(A_i * exp(-x/(tau_i + t_p))))^2)
with w = 1 for unweighted regression analysis (method_control = list(weights = FALSE)) or
w = c^2/n_i for weighted regression analysis. The default values is TRUE.
F = (\Delta\chi^2 / 2) / (\chi^2/(N - 2*m - 2))
(2) Final fitting
method_control
Parameter Type Description
p numeric controls the probability for the F statistic reference values. For a significance level of 5 % a value of 0.95 (the default) should be added, for 1 %, a value of 0.99 is sufficient: 1 > p > 0 (cf. stats::FDist)
seed numeric set the seed for the random number generator, provide a value here to get reproducible results
DEoptim.trace logical enables/disables the tracing of the differential evolution (cf. DEoptim::DEoptim.control)
DEoptim.itermax logical controls the number of the allowed generations (cf. DEoptim::DEoptim.control)
weights logical enables/disables the weighting for the start parameter estimation and fitting (see equations above).
The default values is TRUE
nlsLM.trace logical enables/disables trace mode for the nls fitting (minpack.lm::nlsLM), can be used to identify convergence problems, default is FALSE
nlsLM.upper logical enables/disables upper parameter boundary, default is TRUE
nlsLM.lower logical enables/disables lower parameter boundary, default is TRUE
Value
———————————–
[ NUMERICAL OUTPUT ]
———————————–
RLum.Results-object
slot: @data
Element Type Description
$data matrix the final fit matrix
$start_matrix matrix the start matrix used for the fitting
$total_counts integer Photon count sum
$fit nls the fit object returned by minpack.lm::nls.lm
slot: @info
The original function call
————————
[ TERMINAL OUTPUT ]
————————
Terminal output is only shown of the argument verbose = TRUE.
(1) Start parameter and component adaption
Trave of the parameter adaptation process
(2) Fitting results (sorted by ascending tau)
The fitting results sorted by ascending tau value. Please note
that if you access the nls fitting object, the values are not sorted.
(3) Further information
The photon count sum
Durbin-Watson residual statistic to asses whether the residuals are correlated, ideally
the residuals should be not correlated at all. Rough measures are:
D = 0: the residuals are systematically correlated
D = 2: the residuals are randomly distributed
D = 4: the residuals are systematically anti-correlated
You should be suspicious if D differs largely from 2.
————————
[ PLOT OUTPUT ]
————————
A plot showing the original data and the fit so far possible. The lower plot shows the
residuals of the fit.
Function version
0.1.5
How to cite
Kreutzer, S., Schmidt, C., 2024. fit_OSLLifeTimes(): Fitting and Deconvolution of OSL Lifetime Components. Function version 0.1.5. 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
Author(s)
Sebastian Kreutzer, Geography & Earth Sciences, Aberystwyth University,
Christoph Schmidt, University of Bayreuth (Germany)
, RLum Developer Team
References
Bluszcz, A., Adamiec, G., 2006. Application of differential evolution to fitting OSL decay curves.
Radiation Measurements 41, 886-891. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.radmeas.2006.05.016")}
Durbin, J., Watson, G.S., 1950. Testing for Serial Correlation in Least Squares Regression: I.
Biometrika 37, 409-21. doi:10.2307/2332391
Further reading
Hughes, I., Hase, T., 2010. Measurements and Their Uncertainties. Oxford University Press.
Storn, R., Price, K., 1997. Differential Evolution –
A Simple and Efficient Heuristic for Global Optimization over Continuous Spaces.
Journal of Global Optimization 11, 341–359.
See Also
minpack.lm::nls.lm, DEoptim::DEoptim
Examples
##load example data
data(ExampleData.TR_OSL, envir = environment())
##fit lifetimes (short run)
fit_OSLLifeTimes(
object = ExampleData.TR_OSL,
n.components = 1)
##long example
## Not run:
fit_OSLLifeTimes(
object = ExampleData.TR_OSL)
## End(Not run)
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.
View source: R/fit_OSLLifeTimes.R
| fit_OSLLifeTimes | R Documentation |
Fitting and Deconvolution of OSL Lifetime Components
Description
Fitting and Deconvolution of OSL Lifetime Components
Usage
fit_OSLLifeTimes(
object,
tp = 0,
signal_range = NULL,
n.components = NULL,
method_control = list(),
plot = TRUE,
plot_simple = FALSE,
verbose = TRUE,
...
)
Arguments
object |
RLum.Data.Curve, RLum.Analysis, data.frame or matrix (required):
Input object containing the data to be analysed. All objects can be provided also as list for an automated
processing. Please note: |
tp |
numeric (with default): option to account for the stimulation pulse width. For off-time measurements
the default value is 0. |
signal_range |
numeric (optional): allows to set a channel range, by default all channels are used, e.g.
|
n.components |
numeric (optional): Fix the number of components. If set the algorithm will try to fit the number of predefined components. If nothing is set, the algorithm will try to find the best number of components. |
method_control |
list (optional): Named to allow a more fine control of the fitting process. See details for allowed options. |
plot |
logical (with default): Enable/disable plot output |
plot_simple |
logical (with default): Enable/disable reduced plot output. If |
verbose |
logical (with default): Enable/disable terminal feedback |
... |
parameters passed to plot.default to control the plot output, supported are:
|
Details
The function intends to provide an easy access to pulsed optically stimulated luminescence (POSL) data, in order determine signal lifetimes. The fitting is currently optimised to work with the off-time flank of POSL measurements only. For the signal deconvolution, a differential evolution optimisation is combined with nonlinear least-square fitting following the approach by Bluszcz & Adamiec (2006).
Component deconvolution algorithm
The component deconvolution consists of two steps:
(1) Adaptation phase
In the adaptation phase the function tries to figure out the optimal and statistically justified
number of signal components following roughly the approach suggested by Bluszcz & Adamiec (2006). In
contrast to their work, for the optimisation by differential evolution here the package 'DEoptim' is used.
The function to be optimized has the form:
\chi^2 = \sum(w * (n_i/c - \sum(A_i * exp(-x/(tau_i + t_p))))^2)
with w = 1 for unweighted regression analysis (method_control = list(weights = FALSE)) or
w = c^2/n_i for weighted regression analysis. The default values is TRUE.
F = (\Delta\chi^2 / 2) / (\chi^2/(N - 2*m - 2))
(2) Final fitting
method_control
| Parameter | Type | Description |
p | numeric | controls the probability for the F statistic reference values. For a significance level of 5 % a value of 0.95 (the default) should be added, for 1 %, a value of 0.99 is sufficient: 1 > p > 0 (cf. stats::FDist) |
seed | numeric | set the seed for the random number generator, provide a value here to get reproducible results |
DEoptim.trace | logical | enables/disables the tracing of the differential evolution (cf. DEoptim::DEoptim.control) |
DEoptim.itermax | logical | controls the number of the allowed generations (cf. DEoptim::DEoptim.control) |
weights | logical | enables/disables the weighting for the start parameter estimation and fitting (see equations above).
The default values is TRUE |
nlsLM.trace | logical | enables/disables trace mode for the nls fitting (minpack.lm::nlsLM), can be used to identify convergence problems, default is FALSE |
nlsLM.upper | logical | enables/disables upper parameter boundary, default is TRUE |
nlsLM.lower | logical | enables/disables lower parameter boundary, default is TRUE
|
Value
———————————–
[ NUMERICAL OUTPUT ]
———————————–
RLum.Results-object
slot: @data
| Element | Type | Description |
$data | matrix | the final fit matrix |
$start_matrix | matrix | the start matrix used for the fitting |
$total_counts | integer | Photon count sum |
$fit | nls | the fit object returned by minpack.lm::nls.lm |
slot: @info
The original function call
————————
[ TERMINAL OUTPUT ]
————————
Terminal output is only shown of the argument verbose = TRUE.
(1) Start parameter and component adaption
Trave of the parameter adaptation process
(2) Fitting results (sorted by ascending tau)
The fitting results sorted by ascending tau value. Please note
that if you access the nls fitting object, the values are not sorted.
(3) Further information
The photon count sum
Durbin-Watson residual statistic to asses whether the residuals are correlated, ideally the residuals should be not correlated at all. Rough measures are:
D = 0: the residuals are systematically correlated
D = 2: the residuals are randomly distributed
D = 4: the residuals are systematically anti-correlated
You should be suspicious if D differs largely from 2.
————————
[ PLOT OUTPUT ]
————————
A plot showing the original data and the fit so far possible. The lower plot shows the residuals of the fit.
Function version
0.1.5
How to cite
Kreutzer, S., Schmidt, C., 2024. fit_OSLLifeTimes(): Fitting and Deconvolution of OSL Lifetime Components. Function version 0.1.5. 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
Author(s)
Sebastian Kreutzer, Geography & Earth Sciences, Aberystwyth University, Christoph Schmidt, University of Bayreuth (Germany) , RLum Developer Team
References
Bluszcz, A., Adamiec, G., 2006. Application of differential evolution to fitting OSL decay curves.
Radiation Measurements 41, 886-891. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.radmeas.2006.05.016")}
Durbin, J., Watson, G.S., 1950. Testing for Serial Correlation in Least Squares Regression: I. Biometrika 37, 409-21. doi:10.2307/2332391
Further reading
Hughes, I., Hase, T., 2010. Measurements and Their Uncertainties. Oxford University Press.
Storn, R., Price, K., 1997. Differential Evolution – A Simple and Efficient Heuristic for Global Optimization over Continuous Spaces. Journal of Global Optimization 11, 341–359.
See Also
minpack.lm::nls.lm, DEoptim::DEoptim
Examples
##load example data
data(ExampleData.TR_OSL, envir = environment())
##fit lifetimes (short run)
fit_OSLLifeTimes(
object = ExampleData.TR_OSL,
n.components = 1)
##long example
## Not run:
fit_OSLLifeTimes(
object = ExampleData.TR_OSL)
## End(Not run)
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.