NanoIndent.OEFPIL: Estimation of parameters in nanoindentation
In OEFPIL: Optimal Estimation of Function Parameters by Iterated Linearization

Description Usage Arguments Details Value References See Also Examples

Fitting the unloading curve in nanoindentation process by power law function with parameters estimated by iterated linearization algorithm (OEFPIL). The special case of OEFPIL function customized for using in nanoindentation (see 'Details').

NanoIndent.OEFPIL(data, alpha.start, m.start, hp.start, unload.data = FALSE, ucut = 0.98,
                 lcut = 0.4, CM, uh = 0.5, uF = 0.001, max.iter = 100,
                 see.iter.val = FALSE, save.file.name, th = .Machine$double.eps ^ (2 / 3),
                 signif.level = 0.05, useNLS = TRUE)

`data`	an object of type `data.frame` with 2 named columns or `list` with 2 elements.
`alpha.start`	a starting value of the fitting constant alpha.
`m.start`	a starting value of the exponent m.
`hp.start`	a starting value of the permanent indentation depth hp.
`unload.data`	a logical value (default `FALSE`) indicating the structure of `data`. If `TRUE`, an input data contains only unloading part of the curve. If `FALSE`, an input data contains complete loading, hold and unloading parts of an indentation process.
`ucut`	a numerical value, indicating the upper bound of cut off.
`lcut`	a numerical value, indicating the lower bound of cut off.
`CM`	a covariance matrix of the input `data`. See 'Details' for more information.
`uh`	standard deviation of depth.
`uF`	standard deviation of load.
`max.iter`	maximum number of iterations.
`see.iter.val`	logical. If `TRUE`, all the partial results of the OEFPIL algorithm are displayed and saved. The default value is `FALSE`.
`save.file.name`	a name of the file for saving results. If missing, no output file is saved.
`th`	a numerical value, indicating threshold necessary for the iteration stoppage.
`signif.level`	a significance level for the confidence interval.
`useNLS`	logical. If `TRUE` (the default value), function will set up starting parameters calculated by `nlsLM` function (nonlinear least square estimation).

In this special case of the OEFPIL function, the dependence of parameters is fixed in the form: F = α * (h - h_p)^m, where F is load and h depth measured within a nanoindentation process. It is possible to set own starting values of the parameters, in the other case these values are calculated by the algorithm and printing into the console.

A selection of the part of the unloading curve fitted by a power law function is provided with lcut and ucut arguments. The default values 0.4 and 0.98 corresponds to the range 40-98 % F_{max} (maximum force) as recommended in ISO 14577 standard.

The CM has to be a 2n covariance matrix (where n is length of data) of following structure: first n elements of the diagonal correspond to the variance of depth and other to the variance of load. If argument CM is missing, the input covariance matrix is set to a diagonal matrix with variance of depth and load (calculated from uh and uF) on the diagonal. If standard deviations are missing too, the default values (uh=0.5, uF=0.001) are used.

The estimations and confidence intervals are computed under normality assumption (see OEFPIL 'Details').

Returns an object of class "OEFPIL". It is a list containing at least the following components

`name_Est`	estimations of model parameters.
`name_upgraded.start.val`	modified starting values of estimating parameters (result from `nlsLM` function).
`cov.m_Est`	estimated covariance matrix of parameters.
`it_num`	number of iterations.
`CI_parameters`	a list of confidence intervals for estimated parameters (a significance level is based on `signif.level` argument).
`logs`	warnings or messages of events, which happen during the run of the algorithm.
`...`	for other components specification see `OEFPIL`.
`contents`	a list of outputs as original values of data and other characteristics, which are usable in plotting or other operations with model results.

If useNLS argument is set to FALSE, the name_upgraded.start.val are the same as start.values (no nlsLM procedure for starting value fitting is performed).

ISO/IEC: 14577-1:2015 Metallic materials – Instrumented indentation test for hardness and materials parameters – Part 1: Test method (ISO/IEC, Internation Organisation for Standardisation, 2015).

Anna Charvátová Campbell, Petr Grolich, Radek šlesinger. (2019). Niget: Nanoindentation general evaluation tool. SoftwareX, Vol. 9: 248–254. doi: 10.1016/j.softx.2019.03.001.

Köning, R., Wimmer, G. and Witkovský, V. Ellipse fitting by nonlinear constraints to demodulate quadrature homodyne interferometer signals and to determine the statistical uncertainty of the interferometric phase. Measurement Science and Technology (2014).

OEFPIL

##Use of NanoIndent function for data file "silicaBerk.RData" (a part of the OEFPIL package)
signif.level = 0.05
output.form.NI <- NanoIndent.OEFPIL(silicaBerk, unload.data = TRUE, ucut = 0.98, lcut = 0.2,
uh = 0.5, uF = 0.001, signif.level = signif.level)

##The output is an object of class 'OEFPIL', supplementary functions for this class are available
##Use of summary function
summary(output.form.NI)

##Plot of estimated unloading curve
plot(output.form.NI, signif.level = signif.level)