OEFPIL (version 0.1.1)

OEFPIL: 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

data

a data file can be any object of type data.frame with 2 named columns or list with 2 elements.

form

an object of class formula (or one that can be coerced to that class): a symbolic description of the model to be fitted. The details of model specification are given under <U+2018>Details<U+2019>.

start.val

a named list of starting values of estimating parameters.

CM

a covariance matrix of data (See 'Details' for the information about required structure.).

max.iter

maximum number of iterations.

see.iter.val

logical. If TRUE, all the partial results of the 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. The default value is .Machine$double.eps ^ (2 / 3).

signif.level

a significance level for the confidence interval. If missing, the default value 0.05 is used.

useNLS

logical. If TRUE (the default value), function will set up starting parameters calculated by nlsLM function (nonlinear least square estimation).

Value

Returns an object of class "OEFPIL". It is a list containing 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.

cov.m_nlsLM

a covariance matrix of starting values of parameters from nlsLM function (if useNLS was set to TRUE).

it_num

number of iterations.

name_previous.step

the parameter values from the previous iterative step.

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.

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

Details

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

• 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<U+00E1><U+010D>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.

References

Kub<U+00E1><U+010D>ek, L. and Kub<U+00E1><U+010D>kov<U+00E1>, L. (2000) Statistika a metrologie. Univerzita Palack<U+00E9>ho v Olomouci.

K<U+00F6>ning, R., Wimmer, G. and Witkovsk<U+00FD>, 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

# NOT RUN {
##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)

# }