NAG C Library Function Document

nag_regsn_mult_linear_upd_model (g02ddc)

1
Purpose

nag_regsn_mult_linear_upd_model (g02ddc) calculates the regression arguments for a general linear regression model. It is intended to be called after nag_regsn_mult_linear_addrem_obs (g02dcc), nag_regsn_mult_linear_add_var (g02dec) or nag_regsn_mult_linear_delete_var (g02dfc).

2
Specification

#include <nag.h>
#include <nagg02.h>
void  nag_regsn_mult_linear_upd_model (Integer n, Integer ip, const double q[], Integer tdq, double *rss, double *df, double b[], double se[], double cov[], Nag_Boolean *svd, Integer *rank, double p[], double tol, NagError *fail)

3
Description

A general linear regression model fitted by nag_regsn_mult_linear (g02dac) may be adjusted by adding or deleting an observation using nag_regsn_mult_linear_addrem_obs (g02dcc), adding a new independent variable using nag_regsn_mult_linear_add_var (g02dec) or deleting an existing independent variable using nag_regsn_mult_linear_delete_var (g02dfc). These functions compute the vector c  and the upper triangular matrix R . nag_regsn_mult_linear_upd_model (g02ddc) 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 β ^ = c 1 ,  
where c 1  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
β ^ = 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 * = 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 nag_regsn_mult_linear_tran_model (g02dkc) after calling nag_regsn_mult_linear_upd_model (g02ddc). Only certain linear combinations of the arguments will have unique estimates, these are known as estimable functions. These can be estimated using nag_regsn_mult_linear_est_func (g02dnc).
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: number of observations.
Constraint: n1 .
2:     ip IntegerInput
On entry: the number of terms in the regression model, p .
Constraint: ip1 .
3:     q[n×tdq] const doubleInput
Note: the i,jth element of the matrix Q is stored in q[i-1×tdq+j-1].
On entry: q must be the array q as output by nag_regsn_mult_linear_addrem_obs (g02dcc), nag_regsn_mult_linear_add_var (g02dec) or nag_regsn_mult_linear_delete_var (g02dfc). If on entry rss0.0  then all n elements of c  are needed. This is provided by functions nag_regsn_mult_linear_add_var (g02dec) or nag_regsn_mult_linear_delete_var (g02dfc).
4:     tdq IntegerInput
On entry: the stride separating matrix column elements in the array q.
Constraint: tdq ip + 1 .
5:     rss double *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 function.
On exit: if rss0.0  on entry, then on exit rss will contain the residual sum of squares as calculated by nag_regsn_mult_linear_upd_model (g02ddc).
If rss was positive on entry, then it will be unchanged.
6:     df double *Output
On exit: the degrees of freedom associated with the residual sum of squares.
7:     b[ip] doubleOutput
On exit: the estimates of the p  arguments, β ^ .
8:     se[ip] doubleOutput
On exit: the standard errors of the p  arguments given in b.
9:     cov[ip×ip+1/2] doubleOutput
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] , ji , is stored in cov[ j j+1 / 2 + i ] , for i=0,1,,ip - 1 and j=i,,ip - 1.
10:   svd Nag_Boolean *Output
On exit: if a singular value decomposition has been performed, then svd=Nag_TRUE , otherwise svd=Nag_FALSE .
11:   rank Integer *Output
On exit: the rank of the independent variables.
If svd=Nag_FALSE , rank=ip .
If svd=Nag_TRUE , rank is an estimate of the rank of the independent variables.
rank is calculated as the number of singular values greater than tol ×  (largest singular value). It is possible for the singular value decomposition to be carried out but rank to be returned as ip.
12:   p[ip×ip+2×ip] doubleOutput
On exit: p contains details of the singular value decomposition if used.
If svd=Nag_FALSE , p is not referenced.
If svd=Nag_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 rows.
13:   tol doubleInput
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 , then 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:   fail NagError *Input/Output
The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6
Error Indicators and Warnings

NE_2_INT_ARG_LT
On entry, n=value  while ip=value . These arguments must satisfy nip .
On entry, tdq=value  while ip + 1 = value. These arguments must satisfy tdq ip + 1 .
NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_DOF_LE_ZERO
The degrees of freedom for error are less than or equal to 0. In this case the estimates, β ^ , are returned but not the standard errors or covariances.
NE_INT_ARG_LT
On entry, ip=value.
Constraint: ip1.
On entry, n=value.
Constraint: n1.
NE_REAL_ARG_LT
On entry, tol must not be less than 0.0: tol=value .
NE_SVD_NOT_CONV
The singular value decomposition has failed to converge. This is an unlikely error exit.

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

nag_regsn_mult_linear_upd_model (g02ddc) is not threaded in any implementation.

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 nag_regsn_mult_linear_add_var (g02dec). The arguments are then calculated by nag_regsn_mult_linear_upd_model (g02ddc) and the results printed.

10.1
Program Text

Program Text (g02ddce.c)

10.2
Program Data

Program Data (g02ddce.d)

10.3
Program Results

Program Results (g02ddce.r)