Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_opt_lsq_uncon_covariance (e04yc)

## Purpose

nag_opt_lsq_uncon_covariance (e04yc) 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(x)$f\left(x\right)$ at the solution.
This function may be used following any one of the nonlinear least squares functions nag_opt_lsq_uncon_mod_func_comp (e04fc), nag_opt_lsq_uncon_mod_func_easy (e04fy), nag_opt_lsq_uncon_quasi_deriv_comp (e04gb), nag_opt_lsq_uncon_mod_deriv_comp (e04gd), nag_opt_lsq_uncon_quasi_deriv_easy (e04gy), nag_opt_lsq_uncon_mod_deriv_easy (e04gz), nag_opt_lsq_uncon_mod_deriv2_comp (e04he) or nag_opt_lsq_uncon_mod_deriv2_easy (e04hy).

## Syntax

[v, cj, ifail] = e04yc(job, m, fsumsq, s, v, 'n', n)
[v, cj, ifail] = nag_opt_lsq_uncon_covariance(job, m, fsumsq, s, v, 'n', n)

## Description

nag_opt_lsq_uncon_covariance (e04yc) is intended for use when the nonlinear least squares function, F(x) = fT(x)f(x)$F\left(x\right)={f}^{\mathrm{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(x)$F\left(x\right)$, at the solution, can be adequately approximated by 2JTJ$2{J}^{\mathrm{T}}J$, where J$J$ is the Jacobian of f(x)$f\left(x\right)$ at the solution. The estimated variance-covariance matrix C$C$ is then given by
 C = σ2(JTJ) − 1,  JTJ  nonsingular, $C=σ2(JTJ)-1, JTJ nonsingular,$
where σ2${\sigma }^{2}$ is the estimated variance of the residual at the solution, x$\stackrel{-}{x}$, given by
 σ2 = (F(x))/(m − n), $σ2=F(x-) m-n ,$
m$m$ being the number of observations and n$n$ the number of variables.
The diagonal elements of C$C$ are estimates of the variances of the estimated regression coefficients. See the E04 Chapter Introduction, Bard (1974) and Wolberg (1967) for further information on the use of C$C$.
When JTJ${J}^{\mathrm{T}}J$ is singular then C$C$ is taken to be
 C = σ2(JTJ)†, $C=σ2 (JTJ) †,$
where (JTJ)${\left({J}^{\mathrm{T}}J\right)}^{†}$ is the pseudo-inverse of JTJ${J}^{\mathrm{T}}J$, and
 σ2 = ( F (x) )/(m − k) ,   k = rank ​(J) $σ2 = F (x-) m-k , k=rank ​(J)$
but in this case the parameter ifail is returned as nonzero as a warning to you that J$J$ has linear dependencies in its columns. The assumed rank of J$J$ can be obtained from ifail.
The function can be used to find either the diagonal elements of C$C$, or the elements of the j$j$th column of C$C$, or the whole of C$C$.
nag_opt_lsq_uncon_covariance (e04yc) must be preceded by one of the nonlinear least squares functions mentioned in Section [Purpose], and requires the parameters fsumsq, s and v to be supplied by those functions (e.g., see nag_opt_lsq_uncon_mod_func_comp (e04fc)). fsumsq is the residual sum of squares F(x)$F\left(\stackrel{-}{x}\right)$ and s and v contain the singular values and right singular vectors respectively in the singular value decomposition of J$J$. s and v are returned directly by the comprehensive functions nag_opt_lsq_uncon_mod_func_comp (e04fc), nag_opt_lsq_uncon_quasi_deriv_comp (e04gb), nag_opt_lsq_uncon_mod_deriv_comp (e04gd) and nag_opt_lsq_uncon_mod_deriv2_comp (e04he), but are returned as part of the workspace parameter w (from one of the easy-to-use functions). In the case of nag_opt_lsq_uncon_mod_func_easy (e04fy), s starts at w(ns)${\mathbf{w}}\left(\mathit{ns}\right)$, where
 ns = 6 × n + 2 × m + m × n + 1 + max (1, n × (n − 1) / 2 ) $ns=6× n+2× m+m× n+1+ max(1, n × (n-1) / 2 )$
and in the cases of the remaining easy-to-use functions, s starts at w(ns)${\mathbf{w}}\left(\mathit{ns}\right)$, where
 ns = 7 × n + 2 × m + m × n + n × (n + 1) / 2 + 1 + max (1, n × (n − 1) / 2 ) . $ns=7× n+2× m+m× n+n× (n+1) / 2+1+ max(1, n × (n-1) / 2 ) .$
The parameter v starts immediately following the elements of s, so that v starts at w(nv)${\mathbf{w}}\left(\mathit{nv}\right)$, where
 nv = ns + n . $nv=ns+n .$
For all the easy-to-use functions the parameter ldv must be supplied as n. Thus a call to nag_opt_lsq_uncon_covariance (e04yc) following nag_opt_lsq_uncon_mod_func_easy (e04fy) can be illustrated as
``` .
.
.
[x, fsumsq, user, ifail] = e04fy(m, lsfun1, x);
.
.
.
ns = 6*n + 2*m + m*n + 1 + max((1,(n*(n-1))/2);
nv = ns + n;
[v, cj, ifail] = e04yc(job, m, fsumsq, w(ns:nv-1), w(nv:numel(w)));
```
where the parameters m, n, fsumsq and the (n + n2)$\left(n+{n}^{2}\right)$ elements w(ns) , w(ns + 1) , , w( nv + n2 1 ) ${\mathbf{w}}\left(\mathit{ns}\right),{\mathbf{w}}\left(\mathit{ns}+1\right),\dots ,{\mathbf{w}}\left(\mathit{nv}+{{\mathbf{n}}}^{2}-1\right)$ must not be altered between the calls to nag_opt_lsq_uncon_mod_func_easy (e04fy) and nag_opt_lsq_uncon_covariance (e04yc). The above illustration also holds for a call to nag_opt_lsq_uncon_covariance (e04yc) following a call to one of nag_opt_lsq_uncon_quasi_deriv_easy (e04gy), nag_opt_lsq_uncon_mod_deriv_easy (e04gz) or nag_opt_lsq_uncon_mod_deriv2_easy (e04hy), except that ns$\mathit{ns}$ must be computed as
 ns = 7 × n + 2 × m + m × n + (n × (n + 1)) / 2 + 1 + max ((1, n × (n − 1) ) / 2) . $ns=7× n+2× m+m× n+ ( n× (n+1) ) /2+1+ max( (1, n × (n-1) ) / 2 ) .$

## References

Bard Y (1974) Nonlinear Parameter Estimation Academic Press
Wolberg J R (1967) Prediction Analysis Van Nostrand

## Parameters

### Compulsory Input Parameters

1:     job – int64int32nag_int scalar
Which elements of C$C$ are returned as follows:
job = 1${\mathbf{job}}=-1$
The n$n$ by n$n$ symmetric matrix C$C$ is returned.
job = 0${\mathbf{job}}=0$
The diagonal elements of C$C$ are returned.
job > 0${\mathbf{job}}>0$
The elements of column job of C$C$ are returned.
Constraint: 1jobn$-1\le {\mathbf{job}}\le {\mathbf{n}}$.
2:     m – int64int32nag_int scalar
The number m$m$ of observations (residuals fi(x)${f}_{i}\left(x\right)$).
Constraint: mn${\mathbf{m}}\ge {\mathbf{n}}$.
3:     fsumsq – double scalar
The sum of squares of the residuals, F(x)$F\left(\stackrel{-}{x}\right)$, at the solution x$\stackrel{-}{x}$, as returned by the nonlinear least squares function.
Constraint: fsumsq0.0${\mathbf{fsumsq}}\ge 0.0$.
4:     s(n) – double array
n, the dimension of the array, must satisfy the constraint 1nm$1\le {\mathbf{n}}\le {\mathbf{m}}$.
The n$n$ singular values of the Jacobian as returned by the nonlinear least squares function. See Section [Description] for information on supplying s following one of the easy-to-use functions.
5:     v(ldv,n) – double array
ldv, the first dimension of the array, must satisfy the constraint if job = 1${\mathbf{job}}=-1$, ldvn$\mathit{ldv}\ge {\mathbf{n}}$.
The n$n$ by n$n$ right-hand orthogonal matrix (the right singular vectors) of J$J$ as returned by the nonlinear least squares function. See Section [Description] for information on supplying v following one of the easy-to-use functions.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the array s and the second dimension of the array v. (An error is raised if these dimensions are not equal.)
The number n$n$ of variables (xj)$\left({x}_{j}\right)$.
Constraint: 1nm$1\le {\mathbf{n}}\le {\mathbf{m}}$.

ldv work

### Output Parameters

1:     v(ldv,n) – double array
If job0${\mathbf{job}}\ge 0$, v is unchanged.
If job = 1${\mathbf{job}}=-1$, the leading n$n$ by n$n$ part of v stores the n$n$ by n$n$ matrix C$C$. When nag_opt_lsq_uncon_covariance (e04yc) is called with job = 1${\mathbf{job}}=-1$ following an easy-to-use function this means that C$C$ is returned, column by column, in the n2${n}^{2}$ elements of w given by w(nv),w(nv + 1),,w(nv + n21)${\mathbf{w}}\left(\mathit{nv}\right),{\mathbf{w}}\left(\mathit{nv}+1\right),\dots ,{\mathbf{w}}\left(\mathit{nv}+{{\mathbf{n}}}^{2}-1\right)$. (See Section [Description] for the definition of nv$\mathit{nv}$.)
2:     cj(n) – double array
If job = 0${\mathbf{job}}=0$, cj returns the n$n$ diagonal elements of C$C$.
If job = j > 0${\mathbf{job}}=j>0$, cj returns the n$n$ elements of the j$j$th column of C$C$.
If job = 1${\mathbf{job}}=-1$, cj is not referenced.
3:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Note: nag_opt_lsq_uncon_covariance (e04yc) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

ifail = 1${\mathbf{ifail}}=1$
 On entry, job < − 1${\mathbf{job}}<-1$, or job > n${\mathbf{job}}>{\mathbf{n}}$, or n < 1${\mathbf{n}}<1$, or m < n${\mathbf{m}}<{\mathbf{n}}$, or fsumsq < 0.0${\mathbf{fsumsq}}<0.0$, or ldv < n$\mathit{ldv}<{\mathbf{n}}$.
W ifail = 2${\mathbf{ifail}}=2$
The singular values are all zero, so that at the solution the Jacobian matrix J$J$ has rank 0$0$.
W ifail > 2${\mathbf{ifail}}>2$
At the solution the Jacobian matrix contains linear, or near linear, dependencies amongst its columns. In this case the required elements of C$C$ have still been computed based upon J$J$ having an assumed rank given by ifail2${\mathbf{ifail}}-2$. The rank is computed by regarding singular values SV(j)$SV\left(j\right)$ that are not larger than 10ε × SV(1)$10\epsilon ×SV\left(1\right)$ as zero, where ε$\epsilon$ is the machine precision (see nag_machine_precision (x02aj)). If you expect near linear dependencies at the solution and are happy with this tolerance in determining rank you should call nag_opt_lsq_uncon_covariance (e04yc) with ${\mathbf{ifail}}={\mathbf{1}}$ in order to prevent termination. It is then essential to test the value of ifail on exit from nag_opt_lsq_uncon_covariance (e04yc).
Overflow$\mathbf{\text{Overflow}}$
If overflow occurs then either an element of C$C$ is very large, or the singular values or singular vectors have been incorrectly supplied.

## Accuracy

The computed elements of C$C$ will be the exact covariances corresponding to a closely neighbouring Jacobian matrix J$J$.

When job = 1${\mathbf{job}}=-1$ the time taken by nag_opt_lsq_uncon_covariance (e04yc) is approximately proportional to n3${n}^{3}$. When job0${\mathbf{job}}\ge 0$ the time taken by the function is approximately proportional to n2${n}^{2}$.

## Example

```function nag_opt_lsq_uncon_covariance_example
job = int64(0);
m = int64(15);
fsumsq = 0.00821487730657898;
s = [4.096503460740998;
1.59495793805472;
0.06125849312174952];
v = [0.9353959086918022, 0.3529512209498857, -0.02144597007884219;
-0.2592284256717189, 0.6432345920936757, -0.7204511661853596;
-0.2404893289241745, 0.6794664783225641, 0.6931739951192144];
[vOut, cj, ifail] = nag_opt_lsq_uncon_covariance(job, m, fsumsq, s, v)
```
```

vOut =

0.9354    0.3530   -0.0214
-0.2592    0.6432   -0.7205
-0.2405    0.6795    0.6932

cj =

0.0002
0.0948
0.0878

ifail =

0

```
```function e04yc_example
job = int64(0);
m = int64(15);
fsumsq = 0.00821487730657898;
s = [4.096503460740998;
1.59495793805472;
0.06125849312174952];
v = [0.9353959086918022, 0.3529512209498857, -0.02144597007884219;
-0.2592284256717189, 0.6432345920936757, -0.7204511661853596;
-0.2404893289241745, 0.6794664783225641, 0.6931739951192144];
[vOut, cj, ifail] = e04yc(job, m, fsumsq, s, v)
```
```

vOut =

0.9354    0.3530   -0.0214
-0.2592    0.6432   -0.7205
-0.2405    0.6795    0.6932

cj =

0.0002
0.0948
0.0878

ifail =

0

```