Estimation of parameters in nanoindentation

Description

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').

Usage

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)

Arguments

Details

In this special case of the OEFPIL function, the dependence of parameters is fixed in the form: F = \alpha * (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').

Value

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

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).

References

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).

See Also

OEFPIL

Examples

##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)

Optimal Estimation of Parameters by Iterated Linearization

Description

Function for computing optimal estimate of parameters of a nonlinear function by iterated linearization (using Taylor expansion). The model considers measurements errors in both (dependent and independent) variables.

Usage

OEFPIL(data, form, start.val, CM, max.iter = 100, see.iter.val = FALSE,
       save.file.name, th, signif.level, useNLS = TRUE)

Arguments

Details

Models for OEPFIL function are specified symbolically. A typical model has the form y ~ f(x, a_1,...,a_n), where

• y is the (numerical) response vector,

• x is the predictor,

• terms a_1,...,a_n are parameters of specified model.

Function f is known nonlinear function with continuous second partial derivatives with respect to x and parameters a_1,...a_n (for more details see (Kubáček, 2000).

All calculations are performed assuming normality of a response vector and measurements errors.

In the data entry of type data.frame, both columns must be named as variables in formula. The same holds for elements of list.

A choice of start.val is important for the convergence of the algorithm. If the OEFPIL algorithm does not converge, starting values modified by nlsLM function (useNLS = TRUE) are recommended (see Example 3).

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 independent variable (x) and other to the variance of dependent variable (y). If argument CM is missing, the input covariance matrix is set to a diagonal variance matrix with sample variance on the main diagonal.

Value

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

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).

Note

The symbol pi is reserved for the Ludolf's constant. So naming one of the model´s parameters by this symbol results in constant entry of the model.

References

Kubáček, L. and Kubáčková, L. (2000) Statistika a metrologie. Univerzita Palackého v Olomouci.

Köning, R., Wimmer, G. and Witkovský, V. (2014) 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.

See Also

NanoIndent.OEFPIL and function nlsLM from minpack.lm package for nonlinear least square algorithms.

Examples

##Example 1 - Use of OEFPIL function for steam data from MASS library
library(MASS)
steamdata <- steam
colnames(steamdata) <- c("x","y")
k <- nrow(steamdata)
CM <- diag(rep(5,2*k))

st1 <- OEFPIL(steamdata, y ~ b1 * 10 ^ (b2 * x/ (b3 + x)),
 list(b1 = 5, b2 = 8, b3 = 200), CM, useNLS = FALSE)

## Displaying results using summary function
summary(st1)

## Plot of estimated function
plot(st1, signif.level = 0.05)

## Example 2 - Use of OEFPIL for nanoindentation data "silica2098.RData"
## (which is part of the OEFPIL package)
## Preparing arguments for OEFPIL function
max.iter = 100
see.iter.val = FALSE
signif.level = 0.05
useNLS = TRUE

## Creating a list with starting values for parameters
start.val <- list(alpha=0.1, m=1.5, hp=0.9)
names(start.val) <- c("alpha", "m", "hp")

## Imputed formula
form <- Load ~ alpha * (Depth - hp) ^ m
k <- length(silica2098[,1])
CM <- diag(c(rep(0.5^2,k),rep(0.001^2,k)))

## Use of OEFPIL function with defined arguments
output.form <- OEFPIL(silica2098, form, start.val, CM = CM, max.iter = max.iter,
 see.iter.val = see.iter.val, signif.level = signif.level, useNLS = useNLS)

## Displaying results with summary (the result is the same as in NanoIndent.OEFPIL function)
summary(output.form)

Extract model coefficients from OEFPIL

Description

Function which extracts the estimated model coefficients from an object of class "OEFPIL".

Usage

## S3 method for class 'OEFPIL'
coef(object, ...)

Arguments

Value

A named vector of estimated model coefficients extracted from an "OEFPIL" object.

See Also

OEFPIL

Examples

##Creating a data file (using steam data from MASS library)
library(MASS)
steamdata <- steam
colnames(steamdata) <- c("x","y")
startsteam <- list(b1 = 5, b2 = 8, b3 = 200)
k <- nrow(steamdata)
CM <- diag(rep(0.1,2*k))

##Creating an OEFPIL object
st1 <- OEFPIL(steamdata, y ~ b1 * 10^(b2 * x/ (b3 + x)), startsteam, CM, useNLS = FALSE)

##Use of coef function
coef(st1)

Confidence and prediction bands for OEFPIL object

Description

Function calculates pointwise confidence bands and prediction bands of estimated function from an object of class "OEFPIL".

Usage

## S3 method for class 'OEFPIL'
   confBands(object, xx, signif.level = 0.05, new.obs.variance)

Arguments

Details

An argument signif.level can be one numerical value or vector of numerical values of significance levels for confidence intervals.

If new.obs.variance is not defined by user, the average variance in the dependent variable is used to compute prediction intervals.

Value

Returns an object of type list containing the following components.

See Also

OEFPIL, plot.OEFPIL

Examples

##-- Continuing the coef.OEFPIL(.) example:

##Use of confBands function with default parameters
a <- confBands(st1)
str(a)

##Computing two different confidence bands in one step
b <- confBands(st1, signif.level = c(0.01,0.05))
str(b)

Confidence intervals for OEFPIL parameters

Description

Function computes confidence intervals for the parameters counted by OEFPIL function.

Usage

confInt.OEFPIL(object, signif.level = object$contents$signif.level, parm)

Arguments

Details

The confidence intervals are computing under normality assumption.

Value

A matrix of estimated confidence intervals for model coefficients from an "OEFPIL" object. The matrix contains lower and upper confidence limits (columns) for each parameter (rows).

See Also

OEFPIL

Examples

##-- Continuing the coef.OEFPIL(.) example:

##Use of confint function
#one numerical value
confInt.OEFPIL(st1)

#vector of numerical values
confInt.OEFPIL(st1, signif.level = c(0.01,0.05,0.1))

#estimation of specified parameters
confInt.OEFPIL(st1 , signif.level = c(0.01,0.05,0.1), parm = c('b1','b2'))

Plot of estimated curve for OEFPIL object

Description

Function for plotting the estimated curve with pointwise confidence bands for an object of class "OEFPIL".

Usage

curvplot.OEFPIL(object, signif.level, xx)

Arguments

Value

A ggplot graph of the estimated curve with pointwise confidence bands. The result can be edit using other ggplot components as usually.

See Also

OEFPIL, paramplot.OEFPIL and plot.OEFPIL.

Examples

library(MASS)
library(ggplot2)

##Creating a data file
steamdata <- steam
colnames(steamdata) <- c("x","y")
n <- nrow(steamdata)
CM1 <- diag(rep(10,2*n))
CM2 <- diag(c(rep(12,n), rep(14,n)))

##Creating OEFPIL objects
st1 <- OEFPIL(steamdata, y ~ b1 * 10^(b2 * x/ (b3 + x)), list(b1 = 5, b2 = 8, b3 = 200),
             CM1, useNLS = FALSE)
st2 <- OEFPIL(steamdata, y ~ b1 * 10^(b2 * x/ (b3 + x)), list(b1 = 5, b2 = 8, b3 = 200),
             CM2, useNLS = FALSE)

##Use of curvplot.OEFPIL function on an object of class 'OEFPIL'
curvplot.OEFPIL(st1, signif.level = 0.05)

##Use of curvplot.OEFPIL function on an object of class 'OEFPIL' with different arguments
curvplot.OEFPIL(st2, signif.level = c(0.01,0.05), xx = seq(0,110,1))

##Use of curvplot.OEFPIL function with additional arguments as for ggplot2
curvplot.OEFPIL(st1, signif.level = 0.05) +
 labs(x = "New x label") +
 labs(title = "New graph title")

Orthogonal residuals from an OEFPIL object

Description

Function for calculating orthogonal residuals of an "OEFPIL" object (i.e. the shortest Euclidean distance between data points and the estimated function from OEFPIL).

Usage

ortresiduals.OEFPIL(object, min.c)

Arguments

Value

Returns an object of type list containing following components

Note

The value min.c should not be too small. In that case the minimization interval is too narrow and the result can be misleading (see Example 3).

See Also

OEFPIL

Examples

##-- Continuing the coef.OEFPIL(.) example:

##Example 1 Use ortresiduals.OEFPIL function on the OEFPIL object, with specified value 'min.c'
ortresiduals.OEFPIL(st1,5)

##Example 2 Use ortresiduals.OEFPIL function without value 'min.c' (defaut.value = 0.05 * range(x))
ortresiduals.OEFPIL(st1)

##Example 3 Choice of too narrow interval. Misleading result!
ortresiduals.OEFPIL(st1,0.5)

Plot parameters of an OEFPIL object

Description

Function for plotting the estimated values of the parameters with error bars (plus minus standard deviation) using ggplot for an object (or list of objects) of class "OEFPIL".

Usage

paramplot.OEFPIL(object)

Arguments

Details

The input list has to be without NaN, NA, Inf or -Inf values in the estimated parameters or covariance matrix in the source "OEFPIL" object. In that case the function returns a warning message and no graph is plotted.

Value

A ggplot graph of the estimated parameter values with error bars. The result can be edit using other ggplot components as usually.

Note

Due to possible large differences in units of estimated parameters, the scale argument for facetting in the ggplot graph is set to "free". It should be taken into account when interpreting the results.

See Also

OEFPIL, curvplot.OEFPIL and plot.OEFPIL.

Examples

##-- Continuing the coef.OEFPIL(.) example:

n <- nrow(steamdata)
CM2 <- diag(c(rep(0.2^2,n), rep(0.1^2,n)))
st2 <- OEFPIL(steamdata, y ~ b1 * 10^(b2 * x/ (b3 + x)), list(b1 = 5, b2 = 8, b3 = 200),
             CM2, useNLS = FALSE)

##Example 1 - Use of paramplot.OEFPIL function on an object of class 'OEFPIL'
paramplot.OEFPIL(st2)

##Example 2 - Use of paramplot.OEFPIL function on a list of objects of class 'OEFPIL'
paramplot.OEFPIL(list(st1,st2))

Plot the estimate from an OEPFIL object

Description

Plot of the iterated linearization estimate of a function from an "OEFPIL" object with pointwise confidence and prediction bands.

Usage

## S3 method for class 'OEFPIL'
plot(x, xx, signif.level, interval, new.obs.variance, ...)

Arguments

Details

If the signif.level argument is missing, even though an interval argument is set to "conf", the default value 0.05 is used. The line type is set to 'dashed' for confidence bands and 'dotted' for prediction bands. The confidence and prediction bands are computed under normality assumption. If the vector signif.level length is greater than 1, then multiple bands are plotted. The widest band has colour no. 2. The second widest band has colour no. 3 etc.

Value

Returns an object of type list containing at least the following components

See Also

OEFPIL

Examples

library(MASS)

##Use of plot function with default parameters
##(only estimation of the function is plotted, without confidence or prediction bands)
steamdata <- steam
colnames(steamdata) <- c("x","y")
n <- nrow(steamdata)
CM1 <- diag(rep(10,2*n))
st1 <- OEFPIL(steamdata, y ~ b1 * 10^(b2 * x/ (b3 + x)), list(b1 = 5, b2 = 8, b3 = 200),
             CM1, useNLS = FALSE)
plot(st1)

##Use of plot function for plotting confidence bands
plot(st1, seq(0,113,0.1), signif.level = c(0.01,0.05), interval = "conf",
 main = "Graph of estimated function")

##Use of plot function for plotting prediction bands
plot(st1, seq(0,113,0.1), interval = "pred", new.obs.variance = 15)

##Return values of plot function
(a <- plot(st1, signif.level = 0.05, interval = "conf"))

Print function for an object of class 'OEFPIL'

Description

Function prints the information about an object of class "OEFPIL".

Usage

## S3 method for class 'OEFPIL'
print(x, ...)

Arguments

Value

Function prints short summary of "OEFPIL" object into the console. In case of assigning value into the variable, it returns object of class "OEFPIL", which is a list with components defined in OEFPIL.

See Also

OEFPIL

Examples

##-- Continuing the coef.OEFPIL(.) example:

##Use of print function
print(st1)

Nanoindentation measurements data

Description

Load and depth measured with Berkovich diamond tip on fused silica material. Data contains only cutted part of unloading indentation curve from silicaBerk data (20-98 %, as recommended in ISO 14577 standard). The relationship between Load (F) and Depth (h) is given by equation F = \alpha (h - h_p)^{m}, where h_{p} is permanent indentation depth after removal of the load, \alpha is fitting constant related to the indenter geometry and power law exponent m should be from (1,2) interval.

Usage

silica2098

Format

The data frame contains two columns:

Depth

nanoindentation depth, in nanometers.

Load

load, in milinewtons.

Source

Czech Metrology Institute, Brno, Czech Republic.

References

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).

Examples

attach(silica2098)
plot(Depth, Load, main = 'Graph of nanoindentation data', xlab = 'Depth (nm)', ylab = 'Load (mN)',
col = 'darkgreen', cex = 1)

Nanoindentation measurements data

Description

Load and depth measured with Berkovich diamond tip on fused silica material. Data contains only unloading part of indentation curve. The relationship between Load (F) and Depth (h) is given by equation F = \alpha (h - h_p)^{m}, where h_{p} is permanent indentation depth after removal of the load, \alpha is fitting constant related to the indenter geometry and power law exponent m should be from (1,2) interval.

Usage

silicaBerk

Format

The data frame contains two columns:

Depth

nanoindentation depth, in nanometers.

Load

load, in milinewtons.

Source

Czech Metrology Institute, Brno, Czech Republic.

Examples

attach(silicaBerk)
plot(Depth, Load, main = 'Graph of nanoindentation data', xlab = 'Depth (nm)', ylab = 'Load (mN)',
col = 'darkgreen', cex = 1)

Summary from an OEFPIL object

Description

Function for fast and clean output of all basic information of an "OEFPIL" object.

Usage

## S3 method for class 'OEFPIL'
summary(object, signif.level = object$contents$signif.level, print = TRUE, ...)

Arguments

Value

Returns an object of type list containing following components

See Also

OEFPIL

Examples

##-- Continuing the coef.OEFPIL(.) example:

##Use of summary function with default parameters
summary(st1)

##Use of summary function with different parameters
summary(st1, signif.level = 0.01, print = FALSE)

Covariance matrix from an OEFPIL object

Description

Function for extracting the estimated covariance matrix from an object of class "OEFPIL".

Usage

## S3 method for class 'OEFPIL'
vcov(object, ...)

Arguments

Value

A matrix of the estimated covariances between the parameter estimates from an "OEFPIL" object.

See Also

OEFPIL

Examples

##-- Continuing the coef.OEFPIL(.) example:

##Use of vcov function
vcov(st1)