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 <nag.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)

The routine may be called by the names g02ddf or nagf_correg_linregm_update.

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

diagonal matrix with nonzero diagonal elements,

k

being the rank of

R

, and

Q_{*}

and

P

are

p \times 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 parameters. These solutions can be obtained by calling g02dkf after calling g02ddf. Only certain linear combinations of the parameters 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$ – Integer Input

On entry: the number of observations.

Constraint:

n \geq 1

2: $ip$ – Integer Input

On entry:

p

, the number of terms in the regression model.

Constraint:

ip \geq 1

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

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$ – Integer Input

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$ – Integer Output

On exit: the degrees of freedom associated with the residual sum of squares.

7: $b (ip)$ – Real (Kind=nag_wp) array Output

On exit: the estimates of the

p

parameters,

\hat{β}

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

On exit: the standard errors of the

p

parameters given in b.

9: $cov (ip \times (ip + 1) / 2)$ – Real (Kind=nag_wp) array Output

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$ – Logical Output

On exit: if a singular value decomposition has been performed,

svd = .TRUE.

, otherwise

svd = .FALSE.

11: $irank$ – Integer Output

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) array Input/Output

On entry: must be array p as output by g02daf, g02def or g02eef, or a previous call to g02ddf.

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 are unchanged, 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) array Workspace

15: $ifail$ – Integer Input/Output

On entry: ifail must be set to

0

- 1

1

to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of

0

causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of

- 1

means that an error message is printed while a value of

1

means that it is not.

If halting is not appropriate, the value

- 1

1

is recommended. If message printing is undesirable, then the value

1

is recommended. Otherwise, the value

0

is recommended. 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 7 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 399$: 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.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface 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 parameters are then calculated by g02ddf and the results printed.

g02dd: FL CL CPP AD

NAG FL Interfaceg02ddf (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

NAG FL Interface
g02ddf (linregm_update)