E04YCF (pdf version)
Chapter Contents
Chapter Introduction
NAG Library Manual

NAG Fortran Library Routine Document

E04YCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

+ Contents

     1 Purpose
     7 Accuracy

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 fx at the solution.
This routine may be used following any one of the nonlinear least-squares routines E04FCF, E04FYF, E04GBF, E04GYF, E04GDF, E04GZF, E04HEF or E04HYF.

2  Specification

SUBROUTINE E04YCF (JOB, M, N, FSUMSQ, S, V, LV, CJ, WORK, IFAIL)
INTEGERJOB, M, N, LV, IFAIL
double precisionFSUMSQ, S(N), V(LV,N), CJ(N), WORK(N)

3  Description

E04YCF is intended for use when the nonlinear least-squares function, Fx=fTxfx, represents the goodness-of-fit of a nonlinear model to observed data. The routine assumes that the Hessian of Fx, at the solution, can be adequately approximated by 2JTJ, where J is the Jacobian of fx at the solution. The estimated variance-covariance matrix C is then given by
C=σ2JTJ-1,  JTJ  non-singular,
where σ2 is the estimated variance of the residual at the solution, x-, given by
σ2=Fx- 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 JTJ is singular then C is taken to be
C=σ2 JTJ ,
where JTJ  is the pseudo-inverse of JTJ, and
σ2 = F x- m-k ,   k=rank ​J
but in this case the parameter IFAIL is returned as non-zero 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 jth 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 parameters FSUMSQ, S and V to be supplied by those routines (e.g., see E04FCF). FSUMSQ is the residual sum of squares Fx- 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 parameter W (from one of the easy-to-use routines). In the case of E04FYF, S starts at WNS, where
NS=6× N+2× M+M× N+1+ max1, N × N-1 / 2
and in the cases of the remaining easy-to-use routines, S starts at WNS, where
NS=7× N+2× M+M× N+N× N+1 / 2+1+ max1, N × N-1 / 2 .
The parameter V starts immediately following the elements of S, so that V starts at WNV, where
NV=NS+N .
For all the easy-to-use routines the parameter LV must be supplied as N. Thus a call to E04YCF following E04FYF can be illustrated as
 .
 .
 .
 CALL E04FYF (M, N, LSFUN1, 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 parameters M, N, FSUMSQ and the n+n2 elements WNS , WNS+1 , , W NV+ N2 -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× N+2× M+M× N+ N× N+1 /2+1+ max 1, N × N-1 / 2 .

4  References

Bard Y (1974) Nonlinear Parameter Estimation Academic Press

Wolberg J R (1967) Prediction Analysis Van Nostrand

5  Parameters

1:     JOB – INTEGERInput
Constraint: -1JOBN.
2:     M – INTEGERInput
3:     N – INTEGERInput
4:     FSUMSQ – double precisionInput
5:     S(N) – double precision 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(LV,N) – double precision arrayInput/Output
On entry: the n by 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 JOB0, V is unchanged.
If JOB=-1, the leading n by n part of V is overwritten by the n by 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 n2 elements of W given by WNV,WNV+1,,WNV+N2-1. (See Section 3 for the definition of NV.)
7:     LV – 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 parameter W (following one of the easy-to-use least-square routines), LV must be the value N.
Constraint: if JOB=-1, LVN.
8:     CJ(N) – double precision arrayOutput
On exit: if JOB=0, CJ returns the n diagonal elements of C.
If JOB=j>0, CJ returns the n elements of the jth column of C.
If JOB=-1, CJ is not referenced.
9:     WORK(N) – double precision arrayWorkspace
If JOB = -1 or 0, WORK is used as internal workspace.
If JOB>0, WORK is not referenced.
10:   IFAIL – INTEGERInput/Output
On initial entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this parameter you should refer to Chapter P01 for details.
On final exit: IFAIL =0 unless the routine detects an error (see Section 6).
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 parameters may be useful even if IFAIL 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.

6  Error Indicators and Warnings

Errors or warnings specified by the routine:
IFAIL = 1
On entry,JOB<-1,
orJOB>N,
orN<1,
orM<N,
orFSUMSQ<0.0,
orLV<N.
IFAIL = 2
The singular values are all zero, so that at the solution the Jacobian matrix J has rank 0.
IFAIL > 2
IFAIL = overflow
If overflow occurs then either an element of C is very large, or the singular values or singular vectors have been incorrectly supplied.

7  Accuracy

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

8  Further Comments

When JOB=-1 the time taken by E04YCF is approximately proportional to n3. When JOB0 the time taken by the routine is approximately proportional to n2.

9  Example

To estimate the variance-covariance matrix C for the least-squares estimates of x1, x2 and x3 in the model
y=x1+t1x2t2+x3t3
using the 15 sets of data given in the following table:
y t1 t2 t3 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
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.

9.1  Program Text

Program Text (e04ycfe.f)

9.2  Program Data

Program Data (e04ycfe.d)

9.3  Program Results

Program Results (e04ycfe.r)


E04YCF (pdf version)
Chapter Contents
Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2006