# fit_SurfaceExposure

0th

Percentile

##### Nonlinear Least Squares Fit for OSL surface exposure data

This function determines the (weighted) least-squares estimates of the parameters of either eq. 1 in Sohbati et al. (2012a) or eq. 12 in Sohbati et al. (2012b) for a given OSL surface exposure data set (BETA).

Keywords
datagen
##### Usage
fit_SurfaceExposure(data, sigmaphi = NULL, mu = NULL, age = NULL,
Ddot = NULL, D0 = NULL, weights = FALSE, plot = TRUE,
legend = TRUE, error_bars = TRUE, coord_flip = FALSE, ...)
##### Arguments
data

data.frame or list (required): Measured OSL surface exposure data with the following structure:

                               (optional)
| depth (a.u.)| intensity | error |
|     [ ,1]   |    [ ,2]  | [ ,3] |
|-------------|-----------|-------|
[1, ]|    ~~~~     |    ~~~~   | ~~~~  |
[2, ]|    ~~~~     |    ~~~~   | ~~~~  |
... |     ...     |     ...   |  ...  |
[x, ]|    ~~~~     |    ~~~~   | ~~~~  |

Alternatively, a list of data.frames can be provided, where each data.frame has the same structure as shown above, with the exception that they must not include the optional error column. Providing a list as input automatically activates the global fitting procedure (see details).

sigmaphi

numeric (optional): A numeric value for sigmaphi, i.e. the charge detrapping rate. Example: sigmaphi = 5e-10

mu

numeric (optional): A numeric value for mu, i.e. the light attenuation coefficient. Example: mu = 0.9

age

numeric (optional): The age (a) of the sample, if known. If data is a list of x samples, then age must be a numeric vector of length x. Example: age = 10000, or age = c(1e4, 1e5, 1e6).

Ddot

numeric (optional): A numeric value for the environmental dose rate (Gy/ka). For this argument to be considered a value for D0 must also be provided; otherwise it will be ignored.

D0

numeric (optional): A numeric value for the characteristic saturation dose (Gy). For this argument to be considered a value for Ddot must also be provided; otherwise it will be ignored.

weights

logical (optional): If TRUE the fit will be weighted by the inverse square of the error. Requires data to be a data.frame with three columns.

plot

logical (optional): Show or hide the plot.

legend

logical (optional): Show or hide the equation inside the plot.

error_bars

logical (optional): Show or hide error bars (only applies if errors were provided).

coord_flip

logical (optional): Flip the coordinate system.

...

Further parameters passed to plot. Custom parameters include:

• verbose (logical): show or hide console output

• line_col: Color of the fitted line

• line_lty: Type of the fitted line (see lty in ?par)

• line_lwd: Line width of the fitted line (see lwd in ?par)

##### Details

Weighted fitting

If weights = TRUE the function will use the inverse square of the error ($$1/\sigma^2$$) as weights during fitting using minpack.lm::nlsLM. Naturally, for this to take effect individual errors must be provided in the third column of the data.frame for data. Weighted fitting is not supported if data is a list of multiple data.frames, i.e., it is not available for global fitting.

Dose rate

If any of the arguments Ddot or D0 is at its default value (NULL), this function will fit eq. 1 in Sohbati et al. (2012a) to the data. If the effect of dose rate (i.e., signal saturation) needs to be considered, numeric values for the dose rate (Ddot) (in Gy/ka) and the characteristic saturation dose (D0) (in Gy) must be provided. The function will then fit eq. 12 in Sohbati et al. (2012b) to the data.

NOTE: Currently, this function does not consider the variability of the dose rate with sample depth (x)! In the original equation the dose rate D is an arbitrary function of x (term D(x)), but here D is assumed constant.

Global fitting

If data is list of multiple data.frames, each representing a separate sample, the function automatically performs a global fit to the data. This may be useful to better constrain the parameters sigmaphi or mu and requires that known ages for each sample is provided (e.g., age = c(100, 1000) if data is a list with two samples).

##### Value

Function returns results numerically and graphically:

----------------------------------- [ NUMERICAL OUTPUT ] -----------------------------------

RLum.Results-object

slot: @data

 Element Type Description $summary data.frame summary of the fitting results $data data.frame the original input data $fit nls the fitting object produced by minpack.lm::nlsLM $args character arguments of the call $call call the original function call slot: @info Currently unused. ------------------------ [ PLOT OUTPUT ] ------------------------ A scatter plot of the provided depth-intensity OSL surface exposure data with the fitted model. ##### Note This function has BETA status. If possible, results should be cross-checked. ##### Function version 0.1.0 (2018-01-21 17:22:38) ##### How to cite Burow, C. (2018). fit_SurfaceExposure(): Nonlinear Least Squares Fit for OSL surface exposure data. Function version 0.1.0. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2018). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.8.6. https://CRAN.R-project.org/package=Luminescence ##### References Sohbati, R., Murray, A.S., Chapot, M.S., Jain, M., Pederson, J., 2012a. Optically stimulated luminescence (OSL) as a chronometer for surface exposure dating. Journal of Geophysical Research 117, B09202. doi:10.1029/2012JB009383 Sohbati, R., Jain, M., Murray, A.S., 2012b. Surface exposure dating of non-terrestial bodies using optically stimulated luminescence: A new method. Icarus 221, 160-166. ##### See Also ##### Aliases • fit_SurfaceExposure ##### Examples # NOT RUN { ## Load example data data("ExampleData.SurfaceExposure") ## Example 1 - Single sample # Known parameters: 10000 a, mu = 0.9, sigmaphi = 5e-10 sample_1 <- ExampleData.SurfaceExposure$sample_1
results <- fit_SurfaceExposure(sample_1, mu = 0.9, sigmaphi = 5e-10)
get_RLum(results)

## Example 2 - Single sample and considering dose rate
# Known parameters: 10000 a, mu = 0.9, sigmaphi = 5e-10,
# dose rate = 2.5 Gy/ka, D0 = 40 Gy
sample_2 <- ExampleData.SurfaceExposure$sample_2 head(sample_2) results <- fit_SurfaceExposure(sample_2, mu = 0.9, sigmaphi = 5e-10, Ddot = 2.5, D0 = 40) get_RLum(results) ## Example 3 - Multiple samples (global fit) to better constrain 'mu' # Known parameters: ages = 1e3, 1e4, 1e5, 1e6 a, mu = 0.9, sigmaphi = 5e-10 set_1 <- ExampleData.SurfaceExposure$set_1
str(set_1, max.level = 2)
results <- fit_SurfaceExposure(set_1, age = c(1e3, 1e4, 1e5, 1e6),
sigmaphi = 5e-10)
get_RLum(results)

## Example 4 - Multiple samples (global fit) and considering dose rate
# Known parameters: ages = 1e2, 1e3, 1e4, 1e5, 1e6 a, mu = 0.9, sigmaphi = 5e-10,
# dose rate = 1.0 Ga/ka, D0 = 40 Gy
set_2 <- ExampleData.SurfaceExposure\$set_2
str(set_2, max.level = 2)
results <- fit_SurfaceExposure(set_2, age = c(1e2, 1e3, 1e4, 1e5, 1e6),
sigmaphi = 5e-10, Ddot = 1, D0 = 40)
get_RLum(results)

# }

Documentation reproduced from package Luminescence, version 0.8.6, License: GPL-3

### Community examples

Looks like there are no examples yet.