NAG C Library Function Document

nag_regsn_mult_linear_est_func (g02dnc)

1
Purpose

nag_regsn_mult_linear_est_func (g02dnc) gives the estimate of an estimable function along with its standard error.

2
Specification

#include <nag.h>
#include <nagg02.h>
void  nag_regsn_mult_linear_est_func (Integer ip, Integer rank, const double b[], const double cov[], const double p[], const double f[], Nag_Boolean *est, double *stat, double *sestat, double *t, double tol, NagError *fail)

3
Description

This function computes the estimates of an estimable function for a general linear regression model which is not of full rank. It is intended for use after a call to nag_regsn_mult_linear (g02dac) or nag_regsn_mult_linear_upd_model (g02ddc). An estimable function is a linear combination of the arguments such that it has a unique estimate. For a full rank model all linear combinations of arguments are estimable.
In the case of a model not of full rank the functions use a singular value decomposition (SVD) to find the parameter estimates, β ^ , and their variance-covariance matrix. Given the upper triangular matrix R  obtained from the QR  decomposition of the independent variables the SVD gives:
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 leads to a 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 , Q * 1  being the first k  columns of Q *  and c 1  being the first p  elements of c .
Details of the SVD are made available, in the form of the matrix P * :
P * = D -1 P1T P0T  
as given by nag_regsn_mult_linear (g02dac) and nag_regsn_mult_linear_upd_model (g02ddc).
A linear function of the arguments, F = fT β , can be tested to see if it is estimable by computing ζ = P0T f . If ζ  is zero, then the function is estimable, if not, the function is not estimable. In practice ζ  is tested against some small quantity η .
Given that F  is estimable it can be estimated by fT β ^  and its standard error calculated from the variance-covariance matrix of β ^ , C β , as
seF = fT C β f  
Also a t -statistic:
t = fT β ^ seF ,  
can be computed. The t -statistic will have a Student's t -distribution with degrees of freedom as given by the degrees of freedom for the residual sum of squares for the model.

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:     ip IntegerInput
On entry: the number of terms in the linear model, p .
Constraint: ip1 .
2:     rank IntegerInput
On entry: the rank of the independent variables, k .
Constraint: 1 rank ip .
3:     b[ip] const doubleInput
On entry: the ip values of the estimates of the arguments of the model, β ^ .
4:     cov[ip×ip+1/2] const doubleInput
On entry: the upper triangular part of the variance-covariance matrix of the ip 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.
5:     p[ip×ip+2×ip] const doubleInput
6:     f[ip] const doubleInput
On entry: the linear function to be estimated, f .
7:     est Nag_Boolean *Output
On exit: est indicates if the function was estimable.
est=Nag_TRUE
The function is estimable.
est=Nag_FALSE
The function is not estimable and stat, sestat and t are not set.
8:     stat double *Output
On exit: if est=Nag_TRUE , stat contains the estimate of the function, fT β ^ .
9:     sestat double *Output
On exit: if est=Nag_TRUE , sestat contains the standard error of the estimate of the function, seF .
10:   t double *Output
On exit: if est=Nag_TRUE , t contains the t -statistic for the test of the function being equal to zero.
11:   tol doubleInput
On entry: tol is the tolerance value used in the check for estimability, η . If tol0.0 , machine precision  is used instead.
12:   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_GT
On entry, ip=value  while rank=value . These arguments must satisfy rankip .
NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_INT_ARG_LT
On entry, ip=value.
Constraint: ip1.
On entry, rank=value.
Constraint: rank1.
NE_RANK_EQ_IP
On entry, rank=ip . In this case, the boolean variable est is returned as Nag_TRUE and all statistics are calculated.
NE_STDES_ZERO
se F = 0.0  probably due to rounding error or due to incorrectly specified inputs cov and f.

7
Accuracy

The computations are believed to be stable.

8
Parallelism and Performance

nag_regsn_mult_linear_est_func (g02dnc) is not threaded in any implementation.

9
Further Comments

The value of estimable functions is independent of the solution chosen from the many possible solutions. While nag_regsn_mult_linear_est_func (g02dnc) may be used to estimate functions of the arguments of the model as computed by nag_regsn_mult_linear_tran_model (g02dkc), β c , these must be expressed in terms of the original arguments, β . The relation between the two sets of arguments may not be straightforward.

10
Example

Data from an experiment with four treatments and three observations per treatment are read in. A model, with a mean term, is fitted by nag_regsn_mult_linear (g02dac). The number of functions to be tested is read in, then the linear functions themselves are read in and tested with nag_regsn_mult_linear_est_func (g02dnc). The results of nag_regsn_mult_linear_est_func (g02dnc) are printed.

10.1
Program Text

Program Text (g02dnce.c)

10.2
Program Data

Program Data (g02dnce.d)

10.3
Program Results

Program Results (g02dnce.r)