naginterfaces.library.opt.lsq_​uncon_​covariance

naginterfaces.library.opt.lsq_uncon_covariance(job, m, fsumsq, s, v)

lsq_uncon_covariance returns estimates of elements of the variance-covariance matrix of the estimated regression coefficients for a nonlinear least squares problem. The estimates are derived from the Jacobian of the function $f\left(x\right)$ at the solution.

This function may be used following any one of the nonlinear least squares functions lsq_uncon_mod_func_comp(), lsq_uncon_quasi_deriv_comp(), lsq_uncon_mod_deriv_comp() or lsq_uncon_mod_deriv2_comp().

For full information please refer to the NAG Library document for e04yc

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e04/e04ycf.html

Parameters

jobint

Which elements of $C$ are returned as follows:

$job=-1$

The $n\times n$ symmetric matrix $C$ is returned.

$job=0$

The diagonal elements of $C$ are returned.

$job>0$

The elements of column $job$ of $C$ are returned.

mint

The number $m$ of observations (residuals $f_i\left(x\right)$).

fsumsqfloat

The sum of squares of the residuals, $F\left(\overline{x}\right)$, at the solution $\overline{x}$, as returned by the nonlinear least squares function.

sfloat, array-like, shape $\left(n\right)$

The $n$ singular values of the Jacobian as returned by the nonlinear least squares function. See Notes for information on supplying $s$ following one of the easy-to-use functions.

vfloat, array-like, shape $(n,n)$

The $n\times n$ right-hand orthogonal matrix (the right singular vectors) of $J$ as returned by the nonlinear least squares function. See Notes for information on supplying $v$ following one of the easy-to-use functions.

Returns

vfloat, ndarray, shape $(n,n)$

If $job\ge 0$, $v$ is unchanged.

If $job=-1$, the leading $n\times n$ part of $v$ is overwritten by the $n\times n$ matrix $C$.

When lsq_uncon_covariance is called with $job=-1$ following an easy-to-use function this means that $C$ is returned, column by column, in the $n^2$ elements of $\text{w}$ given by $\text{w}[\text{NV}-1],\text{w}\left[\text{NV}\right],\dots ,\text{w}[\text{NV}+n^2-2]$. (See Notes for the definition of $\text{NV}$.)

cjfloat, ndarray, shape $\left(n\right)$

If $job=0$, $cj$ returns the $n$ diagonal elements of $C$.

If $job=j>0$, $cj$ returns the $n$ elements of the $j$th column of $C$.

If $job=-1$, $cj$ is not referenced.

Raises

NagValueError

(errno $1$)

On entry, $job=⟨value⟩$.

Constraint: $job\ge -1$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $1$)

On entry, $job=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $job\le n$.

(errno $1$)

On entry, $m=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $m\ge n$.

(errno $1$)

On entry, $fsumsq=⟨value⟩$.

Constraint: $fsumsq\ge 0.0$.

(errno $1$)

On entry, $job=-1$, $\text{ldv}=⟨value⟩$ and $n=⟨value⟩$.

Constaint: if $job=-1$, $\text{ldv}\ge n$.

Warns

NagAlgorithmicWarning

(errno $2$)

The singular values are all zero, so that at the solution the Jacobian matrix has rank $0$.

(errno $i>2$)

At the solution the Jacobian matrix contains linear, or near linear, dependencies amongst its columns. The required elements of $C$ have still been computed based upon $J$ having an assumed rank $\text{errno}-2=⟨value⟩$. The rank is computed by regarding as zero singular values $SV\left(j\right)$ that are not larger than $10\times ϵ\times SV\left(1\right)$, where $ϵ$ is the machine precision (see machine.precision).

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

lsq_uncon_covariance is intended for use when the nonlinear least squares function, $F\left(x\right)=f^T\left(x\right)f\left(x\right)$, represents the goodness-of-fit of a nonlinear model to observed data. The function assumes that the Hessian of $F\left(x\right)$, at the solution, can be adequately approximated by $2J^{T}J$, where $J$ is the Jacobian of $f\left(x\right)$ at the solution. The estimated variance-covariance matrix $C$ is then given by

$$C={\sigma }^2{\left(J^{T}J\right)}^{-1}\text{,}{J}^{T}J\text{nonsingular,}$$

where ${\sigma }^2$ is the estimated variance of the residual at the solution, $\overline{x}$, given by

$${\sigma }^2=\frac{F\left(\overline{x}\right)}{m-n}\text{,}$$

$m$ being the number of observations and $n$ the number of variables.

The diagonal elements of $C$ are estimates of the variances of the estimated regression coefficients. See the E04 Introduction, Bard (1974) and Wolberg (1967) for further information on the use of $C$.

When $J^{T}J$ is singular then $C$ is taken to be

$$C={\sigma }^2{\left(J^{T}J\right)}^{†}\text{,}$$

where ${\left(J^{T}J\right)}^{†}$ is the pseudo-inverse of $J^{T}J$, and

$${\sigma }^2=\frac{F\left(\overline{x}\right)}{m-k}\text{,}k=\text{rank}\left(J\right)$$

but in this case the argument $\text{errno}$ is returned as nonzero as a warning to you that $J$ has linear dependencies in its columns. The assumed rank of $J$ can be obtained from $\text{errno}$.

The function can be used to find either the diagonal elements of $C$, or the elements of the $j$th column of $C$, or the whole of $C$.

References

Bard, Y, 1974, Nonlinear Parameter Estimation, Academic Press

Wolberg, J R, 1967, Prediction Analysis, Van Nostrand