NAG Library Routine Document

g02dcf  (linregm_obs_edit)

 Contents

    1  Purpose
    7  Accuracy

1
Purpose

g02dcf adds or deletes an observation from a general regression model fitted by g02daf.

2
Specification

Fortran Interface
Subroutine g02dcf ( update, mean, weight, m, isx, q, ldq, ip, x, ix, y, wt, rss, wk, ifail)
Integer, Intent (In):: m, isx(m), ldq, ip, ix
Integer, Intent (Inout):: ifail
Real (Kind=nag_wp), Intent (In):: x(*), y, wt
Real (Kind=nag_wp), Intent (Inout):: q(ldq,ip+1), rss
Real (Kind=nag_wp), Intent (Out):: wk(3*ip)
Character (1), Intent (In):: update, mean, weight
C Header Interface
#include nagmk26.h
void  g02dcf_ ( const char *update, const char *mean, const char *weight, const Integer *m, const Integer isx[], double q[], const Integer *ldq, const Integer *ip, const double x[], const Integer *ix, const double *y, const double *wt, double *rss, double wk[], Integer *ifail, const Charlen length_update, const Charlen length_mean, const Charlen length_weight)

3
Description

g02daf fits a general linear regression model to a dataset. You may wish to change the model by either adding or deleting an observation from the dataset. g02dcf takes the results from g02daf and makes the required changes to the vector c and the upper triangular matrix R produced by g02daf. The regression coefficients, standard errors and the variance-covariance matrix of the regression coefficients can be obtained from g02ddf after all required changes to the dataset have been made.
g02daf performs a QR decomposition on the (weighted) X matrix of independent variables. To add a new observation to a model with p arguments, the upper triangular matrix R and vector c1 (the first p elements of c) are augmented by the new observation on independent variables in xT and dependent variable ynew. Givens rotations are then used to restore the upper triangular form.
R:c1 x:ynew R*:c1* 0:ynew* .  
Note:  only R and the upper part of c are updated the remainder of the Q matrix is unchanged.

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

5
Arguments

1:     update – Character(1)Input
On entry: indicates if an observation is to be added or deleted.
update='A'
The observation is added.
update='D'
The observation is deleted.
Constraint: update='A' or 'D'.
2:     mean – Character(1)Input
On entry: indicates if a mean has been used in the model.
mean='M'
A mean term or intercept will have been included in the model by g02daf.
mean='Z'
A model with no mean term or intercept will have been fitted by g02daf.
Constraint: mean='M' or 'Z'.
3:     weight – Character(1)Input
On entry: indicates if a weight is to be used.
weight='U'
The new observation is unweighted.
weight='W'
The new observation is to be weighted and the weight must be supplied in wt.
Constraint: weight='U' or 'W'.
4:     m – IntegerInput
On entry: m, the total number of independent variables in the dataset.
Constraint: m1.
5:     isxm – Integer arrayInput
On entry: if isxj is greater than 0, the value contained in xj-1×ix+1 is to be included as a value of xT, for j=1,2,,m.
Constraint: if mean='M', exactly ip-1 elements of isx must be >0 and if mean='Z', exactly ip elements of isx must be >0.
6:     qldqip+1 – Real (Kind=nag_wp) arrayInput/Output
On entry: must be array q as output by g02daf, g02def, g02dff or g02eef, or a previous call to g02dcf.
On exit: the first ip elements of the first column of q will contain c1* the upper triangular part of columns 2 to ip+1 will contain R* the remainder is unchanged.
7:     ldq – IntegerInput
On entry: the first dimension of the array q as declared in the (sub)program from which g02dcf is called.
Constraint: ldqip.
8:     ip – IntegerInput
On entry: the number of linear terms in general linear regression model (including mean if there is one).
Constraint: ip1.
9:     x* – Real (Kind=nag_wp) arrayInput
Note: the dimension of the array x must be at least m-1×ix+1 .
On entry: the ip values for the dependent variables of the new observation, xT. The positions will depend on the value of ix.
10:   ix – IntegerInput
On entry: the increment for elements of x. Two situations are common:
ix=1
The values of x are to be chosen from consecutive locations in x, i.e., x1,x2,,xm.
ix=ldx
The values of x are to be chosen from a row of a two-dimensional array with first dimension ldx, i.e., x1,xldx+1,,xm-1ldx+1.
Constraint: ix1.
11:   y – Real (Kind=nag_wp)Input
On entry: the value of the dependent variable for the new observation, ynew.
12:   wt – Real (Kind=nag_wp)Input
On entry: if weight='W', wt must contain the weight to be used with the new observation.
If wt=0.0, the observation is not included in the model.
If weight='U', wt is not referenced.
Constraint: if wt0.0, weight='W'.
13:   rss – Real (Kind=nag_wp)Input/Output
On entry: the value of the residual sums of squares for the original set of observations.
Constraint: rss0.0.
On exit: the updated values of the residual sums of squares.
Note:  this will only be valid if the model is of full rank.
14:   wk3×ip – 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, value elements of isx>0 instead of ip=value.
On entry, value elements of isx>0 instead of ip-1 (for mean) =value.
On entry, ip=value.
Constraint: ip1.
On entry, ix=value.
Constraint: ix1.
On entry, ldq=value and ip=value.
Constraint: ldqip.
On entry, mean=value.
Constraint: mean='M' or 'Z'.
On entry, rss=value.
Constraint: rss0.0.
On entry, update=value.
Constraint: update='A' or 'D'.
On entry, weight=value.
Constraint: weight='U' or 'W'.
ifail=2
On entry, wt=value.
Constraint: wt0.0.
ifail=3
The R matrix could not be updated. This may occur if an attempt is made to delete an observation which was not in the original dataset or to add an observation to a R matrix with a zero diagonal element. This error is also possible when removing an observation which reduces the rank of design matrix. In such cases the model should be recomputed using g02daf.
ifail=4
The residual sums of squares cannot be updated. This will occur if the input residual sum of squares is less than the calculated decrease in residual sum of squares when the new observation is deleted.
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

Higher accuracy is achieved by updating the R matrix rather than the traditional methods of updating XX.

8
Parallelism and Performance

g02dcf 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

Care should be taken with the use of g02dcf.
(a) It is possible to delete observations which were not included in the original model.
(b) If several additions/deletions have been performed you are advised to recompute the regression using g02daf.
(c) Adding or deleting observations can alter the rank of the model. Such changes will only be detected when a call to g02ddf has been made. g02ddf should also be used to compute the new residual sum of squares when the model is not of full rank.
g02dcf may also be used after g02def, g02dff and g02eef.

10
Example

A dataset consisting of 12 observations with four independent variables is read in and a general linear regression model fitted by g02daf and parameter estimates printed. The last observation is then dropped and the parameter estimates recalculated, using g02ddf, and printed. Finally a new observation is added and new parameter estimates computed and printed.

10.1
Program Text

Program Text (g02dcfe.f90)

10.2
Program Data

Program Data (g02dcfe.d)

10.3
Program Results

Program Results (g02dcfe.r)

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