NAG Library ManualKeyword Search:

NAG Library Routine Document

e04ycf (lsq_uncon_covariance)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

▸▿ 10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

1

Purpose

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

at the solution.

This routine may be used following any one of the nonlinear least squares routines e04fcf, e04fyf, e04gbf, e04gdf, e04gyf, e04gzf, e04hef or e04hyf.

2

Specification

Fortran Interface

Subroutine e04ycf (

job, m, n, fsumsq, s, v, ldv, cj, work, ifail)

Integer, Intent (In)	::	job, m, n, ldv
Integer, Intent (Inout)	::	ifail
Real (Kind=nag_wp), Intent (In)	::	fsumsq, s(n)
Real (Kind=nag_wp), Intent (Inout)	::	v(ldv,n)
Real (Kind=nag_wp), Intent (Out)	::	cj(n), work(n)

C Header Interface

#include nagmk26.h

void	e04ycf_ ( const Integer job, const Integer m, const Integer n, const double fsumsq, const double s[], double v[], const Integer ldv, double cj[], double work[], Integer ifail)

3

Description

e04ycf is intended for use when the nonlinear least squares function,

F (x) = f^{T} (x) f (x)

, represents the goodness-of-fit of a nonlinear model to observed data. The routine assumes that the Hessian of

F (x)

, at the solution, can be adequately approximated by

2 J^{T} J

, where

J

is the Jacobian of

f (x)

at the solution. The estimated variance-covariance matrix

C

is then given by

C = σ^{2} {(J^{T} J)}^{- 1}, J^{T} J nonsingular,

where

σ^{2}

is the estimated variance of the residual at the solution,

\bar{x}

, given by

σ^{2} = \frac{F (\bar{x})}{m - n},

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 Chapter 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 = σ^{2} {(J^{T} J)}^{†},

where

{(J^{T} J)}^{†}

is the pseudo-inverse of

J^{T} J

, and

σ^{2} = \frac{F (\bar{x})}{m - k}, k = rank ​ (J)

but in this case the argument ifail 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 ifail.

The routine 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

e04ycf must be preceded by one of the nonlinear least squares routines mentioned in Section 1, and requires the arguments fsumsq, s and v to be supplied by those routines (e.g., see e04fcf). fsumsq is the residual sum of squares

F (\bar{x})

and s and v contain the singular values and right singular vectors respectively in the singular value decomposition of

J

. s and v are returned directly by the comprehensive routines e04fcf, e04gbf, e04gdf and e04hef, but are returned as part of the workspace argument w (from one of the easy-to-use routines e04fyf, e04gyf, e04gzf and e04hyf). In the case of e04fyf, s starts at

w (NS)

, where

NS = 6 \times n + 2 \times m + m \times n + 1 + \max (1, n \times (n - 1) / 2)

and in the cases of the remaining easy-to-use routines, s starts at

w (NS)

, where

NS = 7 \times n + 2 \times m + m \times n + n \times (n + 1) / 2 + 1 + \max (1, n \times (n - 1) / 2) .

The argument v starts immediately following the elements of s, so that v starts at

w (NV)

, where

NV = NS + n .

For all the easy-to-use routines the argument ldv must be supplied as n. Thus a call to e04ycf following e04fyf can be illustrated as

.
.
.
Call e04fyf (m, n, lfun1, x, fsumsq, w, lw, iuser, ruser, ifail)
.
.
.
ns = 6*n + 2*m + m*n + 1 + max(1,n*(n-1)/2)
nv = ns + n
Call e04ycf (job, m, n, fsumsq, w(ns), w(nv), n, cj, work, ifail)

where the arguments m, n, fsumsq and the

(n + n^{2})

elements

w (NS), w (NS + 1), \dots, w (NV + n^{2} - 1)

must not be altered between the calls to e04fyf and e04ycf. The above illustration also holds for a call to e04ycf following a call to one of e04gyf, e04gzf or e04hyf, except that

NS

must be computed as

NS = 7 \times n + 2 \times m + m \times n + (n \times (n + 1)) / 2 + 1 + \max ((1, n \times (n - 1)) / 2) .

4

References

Bard Y (1974) Nonlinear Parameter Estimation Academic Press

Wolberg J R (1967) Prediction Analysis Van Nostrand

5

Arguments

1: $job$ – IntegerInput

On entry: which elements of

C

are returned as follows:

$job = - 1$: The $n$ by $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.

Constraint:

- 1 \leq job \leq n

2: $m$ – IntegerInput

On entry: the number

m

of observations (residuals

f_{i} (x)

Constraint:

m \geq n

3: $n$ – IntegerInput

On entry: the number

n

of variables

(x_{j})

Constraint:

1 \leq n \leq m

4: $fsumsq$ – Real (Kind=nag_wp)Input

On entry: the sum of squares of the residuals,

F (\bar{x})

, at the solution

\bar{x}

, as returned by the nonlinear least squares routine.

Constraint:

fsumsq \geq 0.0

5: $s (n)$ – Real (Kind=nag_wp) arrayInput

On entry: the

n

singular values of the Jacobian as returned by the nonlinear least squares routine. See Section 3 for information on supplying s following one of the easy-to-use routines.

6: $v (ldv, n)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: the

n

n

right-hand orthogonal matrix (the right singular vectors) of

J

as returned by the nonlinear least squares routine. See Section 3 for information on supplying v following one of the easy-to-use routines.

On exit: if

job \geq 0

, v is unchanged.

job = - 1

, the leading

n

n

part of v is overwritten by the

n

n

matrix

C

. When e04ycf is called with

job = - 1

following an easy-to-use routine this means that

C

is returned, column by column, in the

n^{2}

elements of w given by

w (NV), w (NV + 1), \dots, w (NV + n^{2} - 1)

. (See Section 3 for the definition of

NV

7: $ldv$ – IntegerInput

On entry: the first dimension of the array v as declared in the (sub)program from which e04ycf is called. When v is passed in the workspace argument w (following one of the easy-to-use least square routines), ldv must be the value n.

Constraint:

ldv \geq n

8: $cj (n)$ – Real (Kind=nag_wp) arrayOutput

On exit: if

job = 0

, cj returns the

n

diagonal elements of

C

job = j > 0

, cj returns the

n

elements of the

j

th column of

C

job = - 1

, cj is not referenced.

9: $work (n)$ – Real (Kind=nag_wp) arrayWorkspace

job = - 1

0

, work is used as internal workspace.

job > 0

, work is not referenced.

10: $ifail$ – IntegerInput/Output

On entry: ifail must be set to

0

- 1 ​ or ​ 1

. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value

- 1 ​ or ​ 1

is recommended. If the output of error messages is undesirable, then the value

1

is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if

ifail \neq 0

on exit, the recommended value is

- 1

. When the value $- 1 or 1$ is used it is essential to test the value of ifail on exit.

On exit:

ifail = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6

Error Indicators and Warnings

If on entry

ifail = 0

- 1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Note: e04ycf may return useful information for one or more of the following detected errors or warnings.

Errors or warnings detected by the routine:

$ifail = 1$

On entry,	$job < - 1$ ,
or	$job > n$ ,
or	$n < 1$ ,
or	$m < n$ ,
or	$fsumsq < 0.0$ ,
or	$ldv < n$ .

$ifail = 2$: The singular values are all zero, so that at the solution the Jacobian matrix $J$ has rank $0$ .

$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$ have still been computed based upon $J$ having an assumed rank given by $ifail - 2$ . The rank is computed by regarding singular values $S V (j)$ that are not larger than $10 ε \times S V (1)$ as zero, where $ε$ is the machine precision (see x02ajf). If you expect near linear dependencies at the solution and are happy with this tolerance in determining rank you should call e04ycf with $ifail = 1$ in order to prevent termination (see the description of ifail). It is then essential to test the value of ifail on exit from e04ycf.

$Overflow$: If overflow occurs then either an element of $C$ is very large, or the singular values or singular vectors have been incorrectly supplied.

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

The computed elements of

C

will be the exact covariances corresponding to a closely neighbouring Jacobian matrix

J

8

Parallelism and Performance

e04ycf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.

e04ycf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9

Further Comments

When

job = - 1

the time taken by e04ycf is approximately proportional to

n^{3}

. When

job \geq 0

the time taken by the routine is approximately proportional to

n^{2}

10

Example

This example estimates the variance-covariance matrix

C

for the least squares estimates of

x_{1}

x_{2}

and

x_{3}

in the model

y = x_{1} + \frac{t_{1}}{x_{2} t_{2} + x_{3} t_{3}}

using the

15

sets of data given in the following table:

\begin{array}{r} y & t_{1} & t_{2} & t_{3} \\ 0.14 & 1.0 & 15.0 & 1.0 \\ 0.18 & 2.0 & 14.0 & 2.0 \\ 0.22 & 3.0 & 13.0 & 3.0 \\ 0.25 & 4.0 & 12.0 & 4.0 \\ 0.29 & 5.0 & 11.0 & 5.0 \\ 0.32 & 6.0 & 10.0 & 6.0 \\ 0.35 & 7.0 & 9.0 & 7.0 \\ 0.39 & 8.0 & 8.0 & 8.0 \\ 0.37 & 9.0 & 7.0 & 7.0 \\ 0.58 & 10.0 & 6.0 & 6.0 \\ 0.73 & 11.0 & 5.0 & 5.0 \\ 0.96 & 12.0 & 4.0 & 4.0 \\ 1.34 & 13.0 & 3.0 & 3.0 \\ 2.10 & 14.0 & 2.0 & 2.0 \\ 4.39 & 15.0 & 1.0 & 1.0 \end{array}

The program uses

(0.5, 1.0, 1.5)

as the initial guess at the position of the minimum and computes the least squares solution using e04fyf. See the routine document e04fyf for further information.

NAG Library Routine Document

e04ycf (lsq_uncon_covariance)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

6

Error Indicators and Warnings

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

10.2

Program Data

10.3

Program Results