NAG Library Routine Document

g02ddf  (linregm_update)

 Contents

    1  Purpose
    7  Accuracy

1
Purpose

g02ddf calculates the regression arguments for a general linear regression model. It is intended to be called after g02dcf, g02def or g02dff.

2
Specification

Fortran Interface
Subroutine g02ddf ( n, ip, q, ldq, rss, idf, b, se, cov, svd, irank, p, tol, wk, ifail)
Integer, Intent (In):: n, ip, ldq
Integer, Intent (Inout):: ifail
Integer, Intent (Out):: idf, irank
Real (Kind=nag_wp), Intent (In):: q(ldq,ip+1), tol
Real (Kind=nag_wp), Intent (Inout):: rss, p(ip*ip+2*ip)
Real (Kind=nag_wp), Intent (Out):: b(ip), se(ip), cov(ip*(ip+1)/2), wk(ip*ip+(ip-1)*5)
Logical, Intent (Out):: svd
C Header Interface
#include nagmk26.h
void  g02ddf_ ( const Integer *n, const Integer *ip, const double q[], const Integer *ldq, double *rss, Integer *idf, double b[], double se[], double cov[], logical *svd, Integer *irank, double p[], const double *tol, double wk[], Integer *ifail)

3
Description

A general linear regression model fitted by g02daf may be adjusted by adding or deleting an observation using g02dcf, adding a new independent variable using g02def or deleting an existing independent variable using g02dff. Alternatively a model may be constructed by a forward selection procedure using g02eef. These routines compute the vector c and the upper triangular matrix R. g02ddf takes these basic results and computes the regression coefficients, β^, their standard errors and their variance-covariance matrix.
If R is of full rank, then β^ is the solution to
Rβ^=c1,  
where c1 is the first p elements of c.
If R is not of full rank a solution is obtained by means of a singular value decomposition (SVD) of R,
R=Q* D 0 0 0 PT,  
where D is a k by k diagonal matrix with nonzero diagonal elements, k being the rank of R, and Q* and P are p by p orthogonal matrices. This gives the solution
β^=P1D-1Q*1Tc1.  
P1 being the first k columns of P, i.e., P=P1P0, and Q*1 being the first k columns of Q*.
Details of the SVD are made available in the form of the matrix P*:
P*= D-1 P1T P0T .  
This will be only one of the possible solutions. Other estimates may be obtained by applying constraints to the arguments. These solutions can be obtained by calling g02dkf after calling g02ddf. Only certain linear combinations of the arguments will have unique estimates; these are known as estimable functions. These can be estimated using g02dnf.
The residual sum of squares required to calculate the standard errors and the variance-covariance matrix can either be input or can be calculated if additional information on c for the whole sample is provided.

4
References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25
Searle S R (1971) Linear Models Wiley

5
Arguments

1:     n – IntegerInput
On entry: the number of observations.
Constraint: n1.
2:     ip – IntegerInput
On entry: p, the number of terms in the regression model.
Constraint: ip1.
3:     qldqip+1 – Real (Kind=nag_wp) arrayInput
On entry: must be the array q as output by g02dcf, g02def, g02dff or g02eef. If on entry rss0.0 then all n elements of c are needed. This is provided by routines g02def, g02dff or g02eef.
4:     ldq – IntegerInput
On entry: the first dimension of the array q as declared in the (sub)program from which g02ddf is called.
Constraints:
  • if rss0.0, ldqn;
  • otherwise ldqip.
5:     rss – Real (Kind=nag_wp)Input/Output
On entry: either the residual sum of squares or a value less than or equal to 0.0 to indicate that the residual sum of squares is to be calculated by the routine.
On exit: if rss0.0 on entry, then on exit rss will contain the residual sum of squares as calculated by g02ddf.
If rss was positive on entry, it will be unchanged.
6:     idf – IntegerOutput
On exit: the degrees of freedom associated with the residual sum of squares.
7:     bip – Real (Kind=nag_wp) arrayOutput
On exit: the estimates of the p parameters, β^.
8:     seip – Real (Kind=nag_wp) arrayOutput
On exit: the standard errors of the p parameters given in b.
9:     covip×ip+1/2 – Real (Kind=nag_wp) arrayOutput
On exit: the upper triangular part of the variance-covariance matrix of the p parameter estimates given in b. They are stored packed by column, i.e., the covariance between the parameter estimate given in bi and the parameter estimate given in bj, ji, is stored in covj×j-1/2+i.
10:   svd – LogicalOutput
On exit: if a singular value decomposition has been performed, svd=.TRUE., otherwise svd=.FALSE..
11:   irank – IntegerOutput
On exit: the rank of the independent variables.
If svd=.FALSE., irank=ip.
If svd=.TRUE., irank is an estimate of the rank of the independent variables.
irank is calculated as the number of singular values greater than tol× (largest singular value). It is possible for the SVD to be carried out but irank to be returned as ip.
12:   pip×ip+2×ip – Real (Kind=nag_wp) arrayOutput
On exit: contains details of the singular value decomposition if used.
If svd=.FALSE., p is not referenced.
If svd=.TRUE., the first ip elements of p will not be referenced, the next ip values contain the singular values. The following ip×ip values contain the matrix P* stored by columns.
13:   tol – Real (Kind=nag_wp)Input
On entry: the value of tol is used to decide if the independent variables are of full rank and, if not, what is the rank of the independent variables. The smaller the value of tol the stricter the criterion for selecting the singular value decomposition. If tol=0.0, the singular value decomposition will never be used, this may cause run time errors or inaccuracies if the independent variables are not of full rank.
Suggested value: tol=0.000001.
Constraint: tol0.0.
14:   wkip×ip+ip-1×5 – Real (Kind=nag_wp) arrayWorkspace
15:   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, if you are not familiar with this argument, the recommended value is 0. 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 or -1, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
ifail=1
On entry, ip=value.
Constraint: ip1.
On entry, ldq=value and ip=value.
Constraint: if rss0.0, ldqn.
On entry, ldq=value and ip=value.
Constraint: ldqip.
On entry, n=value.
Constraint: n1.
On entry, tol=value.
Constraint: tol0.0.
ifail=2
The degrees of freedom for error are less than or equal to 0. In this case the estimates of β are returned but not the standard errors or covariances.
ifail=3
SVD solution failed to converge.
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 accuracy of the results will depend on the accuracy of the input R matrix, which may lose accuracy if a large number of observations or variables have been dropped.

8
Parallelism and Performance

g02ddf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g02ddf 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

None.

10
Example

A dataset consisting of 12 observations and four independent variables is input and a regression model fitted by calls to g02def. The arguments are then calculated by g02ddf and the results printed.

10.1
Program Text

Program Text (g02ddfe.f90)

10.2
Program Data

Program Data (g02ddfe.d)

10.3
Program Results

Program Results (g02ddfe.r)

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