bootstrap.nlsfit: Bootstrap a non-linear least-squares fit
In hadron: Analysis Framework for Monte Carlo Simulation Data in Physics

bootstrap.nlsfit

R Documentation

Bootstrap a non-linear least-squares fit

Description

Performs and bootstraps a non-linear least-squares fit to data with y and x errors.

Usage

bootstrap.nlsfit(fn, par.guess, y, x, bsamples, priors = list(param = c(), p
  = c(), psamples = c()), ..., lower = rep(x = -Inf, times =
  length(par.guess)), upper = rep(x = +Inf, times = length(par.guess)), dy,
  dx, CovMatrix, gr, dfn, mask, use.minpack.lm = TRUE, parallel = FALSE,
  error = sd, cov_fn = cov, maxiter = 500, success.infos = 1:3,
  relative.weights = FALSE, na.rm = FALSE)

Arguments

`fn`	`fn(par, x, ...)`. The (non-linear) function to be fitted to the data. Its first argument must be the fit parameters named `par`. The second must be `x`, the explaining variable. Additional parameters might be passed to the function. Currently we pass `boot.r` which is `0` for the original data and the ID (1, ...) of the bootstrap sample otherwise. As more parameters might be added in the future it is recommended that the fit function accepts `...` as the last parameter to be forward compatible.
`par.guess`	initial guess values for the fit parameters.
`y`	the data as a one-dimensional numerical vector to be described by the fit function.
`x`	values of the explaining variable in form of a one-dimensional numerical vector.
`bsamples`	bootstrap samples of `y` (and `x`, if applicable). Must be provided as array of dimensions `c(boot.R, n)` with `n` equals to `length(y)` in case of 'yerrors' and For 'xyerrors' to `length(y) + length(x)`.
`priors`	List possessing the elements `param`, `p` and `psamples`. The vector `param` includes the indices of all fit parameters that are to be constrained and the vector `p` the corresponding paramater values (e.g. known from a previous fit). The list element `psamples` is a matrix of dimensions `(boot.R, length(param))` and contains the corresponding bootstrap samples. If this list is not specified priors are omitted within the fit.
`...`	Additional parameters passed to `fn`, `gr` and `dfn`.
`lower`	Numeric vector of length `length(par.guess)` of lower bounds on the fit parameters. If missing, `-Inf` will be set for all.
`upper`	Numeric vector of length `length(par.guess)` of upper bounds on the fit parameters. If missing, `+Inf` will be set for all.
`dy, dx`	Numeric vector. Errors of the dependent and independent variable, respectively. These do not need to be specified as they can be computed from the bootstrap samples. In the case of parametric bootstrap it might would lead to a loss of information if they were computed from the pseudo-bootstrap samples. They must not be specified if a covariance matrix is given.
`CovMatrix`	complete variance-covariance matrix of dimensions `c(length(y), length(y))` or `c(length(y)+length(x), length(y)+length(x))` depending on the errormodel. Pass `NULL` if the matrix has to be calculated from the `bsamples`. In that case, if the number of boostrap samples is small compared to the number of variables, singular value decomposition with small eigenvalue replacement will be used (see invertCovMatrix) to attempt a clean inversion. In case a variance-covariance matrix is passed, the inversion will simply be attempted using `solve` on the Cholesky decomposition. Finally, if `CovMatrix` is missing, an uncorrelated fit will be performed.
`gr`	`gr(par, x, ...)`. `gr=d(fn) / d(par)` is a function to return the gradient of `fn`. It must return an array with `length(x)` rows and `length(par)` columns.
`dfn`	`dfn(par, x, ...)`. `dfn=d(fn) / dx` is the canonical derivative of `fn` by `x` and only relevant if x-errors are provided.
`mask`	logical or integer index vector. The mask is applied to select the observations from the data that are to be used in the fit. It is applied to `x`, `y`, `dx`, `dy`, `bsamples` and `CovMatrix` as applicable.
`use.minpack.lm`	use the `minpack.lm` library if available. This is usually faster than the default `optim` but somtimes also less stable.
`parallel`	parallelise over bootstrap samples. The package `parallel` is required.
`error`	Function that takes a sample vector and returns the error estimate. This is a parameter in order to support different resampling methods like jackknife.
`cov_fn`	function. Function to compute the covariance (matrix). Default is cov.
`maxiter`	integer. Maximum number of iterations that can be used in the optimization process.
`success.infos`	integer vector. When using `minpack.lm` there is the `info` in the return value. Values of 1, 2 or 3 are certain success. A value of 4 could either be a success or a saddle point. If you want to interpret this as a success as well just pass `1:4` instead of the default `1:3`.
`relative.weights`	are the errors on y (and x) to be interpreted as relative weights instead of absolute ones? If TRUE, the covariance martix of the fit parameter results is multiplied by chi^2/dof. This is the default in many fit programs, e.g. gnuplot.
`na.rm`	logical. If set to `true`, NAs in `y` and `dy` will be ignored. If x-errors are taken into account, NAs in `x` and `dx` will be ignored, too.

Value

returns a list of class 'bootstrapfit'. It returns all input parameters and adds in addition the following:

`t0`	the one dimensional numerical vector of length `npar+1`. `npar` is the number of fit parameters. In case of 'yerrors' this equals `length(par.guess)`. For 'xyerrors' this equals `length(par.guess) + length(x)`. `t0` contains the best fit parameters obtained on the original data. The last element in `t0` is the chisquare value.
`t`	an array of dimensions `(npar+1, boot.R)` with `npar` as in `t0`. The rows contain the individual bootstrap observations.
`bsamples`	the bootstrap samples used as an array of dimensions `(length(y), boot.R)` or `(length(y)+length(x), boot.R)` depending on the error model with `npar` as in `t0`.
`Qval`	the p-value of the fit on the original data
`chisqr`	the residual chisqr value.
`dof`	the residual degrees of freedom of the fit.
`nx`	the number of x-values.
`tofn`	the original `...` list of parameters to be passed on to the fit function
`mask`	original `mask` value

Examples

## Declare some data.
value <- c(0.1, 0.2, 0.31)
dvalue <- c(0.01, 0.01, 0.015)
x <- c(1, 2, 3)
dx <- c(0.1, 0.1, 0.1)
boot.R <- 1500

fn <- function (par, x, boot.r, ...) par[1] + par[2] * x

## Before we can use the fit with this data, we need to create bootstrap
## samples. We do not want to use the correlation matrix here. Note that you
## can simply use the parametric.nlsfit function as a convenient wrapper of
## the two steps.
bsamples <- parametric.bootstrap(boot.R, c(value, x), c(dvalue, dx))
head(bsamples)

fit.result <- bootstrap.nlsfit(fn, c(1, 1), value, x, bsamples)
summary(fit.result)
plot(fit.result, main = 'Ribbon on top')
plot(fit.result, ribbon.on.top = FALSE, main = 'Ribbon below')
residual_plot(fit.result, main = 'Residual Plot')

hadron documentation built on Sept. 9, 2022, 5:06 p.m.