hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
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(x) 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(x)=fT(x)f(x), represents the goodness-of-fit of a nonlinear model to observed data. The function assumes that the Hessian of F(x)F(x), at the solution, can be adequately approximated by 2JTJ2JTJ, where JJ is the Jacobian of f(x)f(x) at the solution. The estimated variance-covariance matrix CC is then given by
C = σ2(JTJ)1,  JTJ  nonsingular,
C=σ2(JTJ)-1,  JTJ  nonsingular,
where σ2σ2 is the estimated variance of the residual at the solution, xx-, given by
σ2 = (F(x))/(mn),
σ2=F(x-) m-n ,
mm being the number of observations and nn the number of variables.
The diagonal elements of CC 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 CC.
When JTJJTJ is singular then CC is taken to be
C = σ2(JTJ),
C=σ2 (JTJ) ,
where (JTJ) (JTJ)  is the pseudo-inverse of JTJJTJ, and
σ2 = ( F (x) )/(mk) ,   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 JJ has linear dependencies in its columns. The assumed rank of JJ can be obtained from ifail.
The function can be used to find either the diagonal elements of CC, or the elements of the jjth column of CC, or the whole of CC.
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(x-) and s and v contain the singular values and right singular vectors respectively in the singular value decomposition of JJ. 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)wns, where
ns = 6 × n + 2 × m + m × n + 1 + max (1, n × (n1) / 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)wns, where
ns = 7 × n + 2 × m + m × n + n × (n + 1) / 2 + 1 + max (1, n × (n1) / 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)wnv, 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)(n+n2) elements w(ns) , w(ns + 1) , , w( nv + n2 1 ) wns , wns+1 , , w nv+ n2 -1  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 nsns must be computed as
ns = 7 × n + 2 × m + m × n + (n × (n + 1)) / 2 + 1 + max ((1, n × (n1) ) / 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 CC are returned as follows:
job = 1job=-1
The nn by nn symmetric matrix CC is returned.
job = 0job=0
The diagonal elements of CC are returned.
job > 0job>0
The elements of column job of CC are returned.
Constraint: 1jobn-1jobn.
2:     m – int64int32nag_int scalar
The number mm of observations (residuals fi(x)fi(x)).
Constraint: mnmn.
3:     fsumsq – double scalar
The sum of squares of the residuals, F(x)F(x-), at the solution xx-, as returned by the nonlinear least squares function.
Constraint: fsumsq0.0fsumsq0.0.
4:     s(n) – double array
n, the dimension of the array, must satisfy the constraint 1nm1nm.
The nn 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 = 1job=-1, ldvnldvn.
The nn by nn right-hand orthogonal matrix (the right singular vectors) of JJ 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 nn of variables (xj)(xj).
Constraint: 1nm1nm.

Input Parameters Omitted from the MATLAB Interface

ldv work

Output Parameters

1:     v(ldv,n) – double array
If job0job0, v is unchanged.
If job = 1job=-1, the leading nn by nn part of v stores the nn by nn matrix CC. When nag_opt_lsq_uncon_covariance (e04yc) is called with job = 1job=-1 following an easy-to-use function this means that CC is returned, column by column, in the n2n2 elements of w given by w(nv),w(nv + 1),,w(nv + n21)wnv,wnv+1,,wnv+n2-1. (See Section [Description] for the definition of nvnv.)
2:     cj(n) – double array
If job = 0job=0, cj returns the nn diagonal elements of CC.
If job = j > 0job=j>0, cj returns the nn elements of the jjth column of CC.
If job = 1job=-1, cj is not referenced.
3:     ifail – int64int32nag_int scalar
ifail = 0ifail=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 = 1ifail=1
On entry,job < 1job<-1,
orjob > njob>n,
orn < 1n<1,
orm < nm<n,
orfsumsq < 0.0fsumsq<0.0,
orldv < nldv<n.
W ifail = 2ifail=2
The singular values are all zero, so that at the solution the Jacobian matrix JJ has rank 00.
W ifail > 2ifail>2
At the solution the Jacobian matrix contains linear, or near linear, dependencies amongst its columns. In this case the required elements of CC have still been computed based upon JJ having an assumed rank given by ifail2ifail-2. The rank is computed by regarding singular values SV(j)SV(j) that are not larger than 10ε × SV(1)10ε×SV(1) as zero, where εε 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 ifail = 1ifail=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).
  OverflowOverflow
If overflow occurs then either an element of CC is very large, or the singular values or singular vectors have been incorrectly supplied.

Accuracy

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

Further Comments

When job = 1job=-1 the time taken by nag_opt_lsq_uncon_covariance (e04yc) is approximately proportional to n3n3. When job0job0 the time taken by the function is approximately proportional to n2n2.

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



PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013