NAG FL Interface
e04ycf (lsq_uncon_covariance)
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 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
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 <nag.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) |
|
C++ Header Interface
#include <nag.h> extern "C" {
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) |
}
|
The routine may be called by the names e04ycf or nagf_opt_lsq_uncon_covariance.
3
Description
e04ycf is intended for use when the nonlinear least squares function,
, represents the goodness-of-fit of a nonlinear model to observed data. The routine assumes that the Hessian of
, at the solution, can be adequately approximated by
, where
is the Jacobian of
at the solution. The estimated variance-covariance matrix
is then given by
where
is the estimated variance of the residual at the solution,
, given by
being the number of observations and
the number of variables.
The diagonal elements of
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
.
When
is singular then
is taken to be
where
is the pseudo-inverse of
, and
but in this case the argument
ifail is returned as nonzero as a warning to you that
has linear dependencies in its columns. The assumed rank of
can be obtained from
ifail.
The routine can be used to find either the diagonal elements of , or the elements of the th column of , or the whole of .
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
and
s and
v contain the singular values and right singular vectors respectively in the singular value decomposition of
.
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
, where
and in the cases of the remaining easy-to-use routines,
s starts at
, where
The argument
v starts immediately following the elements of
s, so that
v starts at
, where
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
elements
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
must be computed as
4
References
Bard Y (1974) Nonlinear Parameter Estimation Academic Press
Wolberg J R (1967) Prediction Analysis Van Nostrand
5
Arguments
-
1:
– Integer
Input
-
On entry: which elements of
are returned as follows:
- The by symmetric matrix is returned.
- The diagonal elements of are returned.
- The elements of column job of are returned.
Constraint:
.
-
2:
– Integer
Input
-
On entry: the number of observations (residuals ).
Constraint:
.
-
3:
– Integer
Input
-
On entry: the number of variables .
Constraint:
.
-
4:
– Real (Kind=nag_wp)
Input
-
On entry: the sum of squares of the residuals, , at the solution , as returned by the nonlinear least squares routine.
Constraint:
.
-
5:
– Real (Kind=nag_wp) array
Input
-
On entry: the
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:
– Real (Kind=nag_wp) array
Input/Output
-
On entry: the
by
right-hand orthogonal matrix (the right singular vectors) of
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
,
v is unchanged.
If
, the leading
by
part of
v is overwritten by the
by
matrix
. When
e04ycf is called with
following an easy-to-use routine this means that
is returned, column by column, in the
elements of
w given by
. (See
Section 3 for the definition of
.)
-
7:
– Integer
Input
-
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:
.
-
8:
– Real (Kind=nag_wp) array
Output
-
On exit: if
,
cj returns the
diagonal elements of
.
If
,
cj returns the
elements of the
th column of
.
If
,
cj is not referenced.
-
9:
– Real (Kind=nag_wp) array
Workspace
-
If
or
,
work is used as internal workspace.
If
,
work is not referenced.
-
10:
– Integer
Input/Output
-
On entry:
ifail must be set to
,
. If you are unfamiliar with this argument you should refer to
Section 4 in the Introduction to the NAG Library FL Interface for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
is recommended. If the output of error messages is undesirable, then the value
is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if
on exit, the recommended value is
.
When the value is used it is essential to test the value of ifail on exit.
On exit:
unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
or
, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
Note: in some cases e04ycf may return useful information.
-
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, , and .
Constaint: if , .
On entry, and .
Constraint: .
On entry, and .
Constraint: .
On entry, .
Constraint: .
-
The singular values are all zero, so that at the solution the Jacobian matrix has rank .
-
At the solution the Jacobian matrix contains linear, or near linear, dependencies amongst its columns. The required elements of
have still been computed based upon
having an assumed rank
. The rank is computed by regarding as zero singular values
that are not larger than
, where
is the
machine precision (see
x02ajf).
- Overflow
If overflow occurs then either an element of is very large, or the singular values or singular vectors have been incorrectly supplied.
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 7 in the Introduction to the NAG Library FL Interface for further information.
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library FL Interface for further information.
Dynamic memory allocation failed.
See
Section 9 in the Introduction to the NAG Library FL Interface for further information.
7
Accuracy
The computed elements of will be the exact covariances corresponding to a closely neighbouring Jacobian matrix .
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.
When the time taken by e04ycf is approximately proportional to . When the time taken by the routine is approximately proportional to .
10
Example
This example estimates the variance-covariance matrix
for the least squares estimates of
,
and
in the model
using the
sets of data given in the following table:
The program uses
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.
10.1
Program Text
10.2
Program Data
10.3
Program Results