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(ipip+2ip)
Real (Kind=nag_wp), Intent (Out)	::	b(ip), se(ip), cov(ip(ip+1)/2), wk(ipip+(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,

\hat{β}

, their standard errors and their variance-covariance matrix.

R

is of full rank, then

\hat{β}

is the solution to

R \hat{β} = c_{1},

where

c_{1}

is the first

p

elements of

c

R

is not of full rank a solution is obtained by means of a singular value decomposition (SVD) of

R

R = Q_{*} (\begin{array}{l} D & 0 \\ 0 & 0 \end{array}) P^{T},

where

D

is a

k

k

diagonal matrix with nonzero diagonal elements,

k

being the rank of

R

, and

Q_{*}

and

P

are

p

p

orthogonal matrices. This gives the solution

\hat{β} = P_{1} D^{- 1} Q_{*_{1}}^{T} c_{1} .

P_{1}

being the first

k

columns of

P

, i.e.,

P = (P_{1} P_{0})

, 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^{*} = (\begin{matrix} D^{- 1} P_{1}^{T} \\ P_{0}^{T} \end{matrix}) .

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:

n \geq 1

2: $ip$ – IntegerInput

On entry:

p

, the number of terms in the regression model.

Constraint:

ip \geq 1

3: $q (ldq, ip + 1)$ – Real (Kind=nag_wp) arrayInput

On entry: must be the array q as output by g02dcf, g02def, g02dff or g02eef. If on entry

rss \leq 0.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 $rss \leq 0.0$ , $ldq \geq n$ ;
otherwise $ldq \geq ip$ .

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

rss \leq 0.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: $b (ip)$ – Real (Kind=nag_wp) arrayOutput

On exit: the estimates of the

p

parameters,

\hat{β}

8: $se (ip)$ – Real (Kind=nag_wp) arrayOutput

On exit: the standard errors of the

p

parameters given in b.

9: $cov (ip \times (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

b (i)

and the parameter estimate given in

b (j)

j \geq i

, is stored in

cov (j \times (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.

svd = .FALSE.

irank = ip

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 \times

(largest singular value). It is possible for the SVD to be carried out but irank to be returned as ip.

12: $p (ip \times ip + 2 \times ip)$ – Real (Kind=nag_wp) arrayOutput

On exit: contains details of the singular value decomposition if used.

svd = .FALSE.

, p is not referenced.

svd = .TRUE.

, the first ip elements of p will not be referenced, the next ip values contain the singular values. The following

ip \times 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:

tol \geq 0.0

14: $wk (ip \times ip + (ip - 1) \times 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

- 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: $ip \geq 1$ .

On entry, $ldq = 〈value〉$ and $ip = 〈value〉$ .
Constraint: if $rss \leq 0.0$ , $ldq \geq n$ .

On entry, $ldq = 〈value〉$ and $ip = 〈value〉$ .
Constraint: $ldq \geq ip$ .

On entry, $n = 〈value〉$ .
Constraint: $n \geq 1$ .

On entry, $tol = 〈value〉$ .
Constraint: $tol \geq 0.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.

NAG Library Routine Document

g02ddf (linregm_update)

▸▿ 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