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,

\hat{β}

, and their variance-covariance matrix. Given the upper triangular matrix

R

obtained from the

Q R

decomposition of the independent variables the SVD gives:

R = Q_{*} (\begin{matrix} D & 0 \\ 0 & 0 \end{matrix}) 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 leads to a 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})

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

as given by nag_regsn_mult_linear (g02dac) and nag_regsn_mult_linear_upd_model (g02ddc).

A linear function of the arguments,

F = f^{T} β

, can be tested to see if it is estimable by computing

ζ = P_{0}^{T} 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

f^{T} \hat{β}

and its standard error calculated from the variance-covariance matrix of

\hat{β}

C_{β}

, as

se (F) = \sqrt{f^{T} C_{β} f}

Also a

t

-statistic:

t = \frac{f^{T} \hat{β}}{se (F)},

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:

ip \geq 1

2: $rank$ – IntegerInput

On entry: the rank of the independent variables,

k

Constraint:

1 \leq rank \leq ip

3: $b [ip]$ – const doubleInput

On entry: the ip values of the estimates of the arguments of the model,

\hat{β}

4: $cov [ip \times (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]

j \geq i

, is stored in

cov [j (j + 1) / 2 + i]

, for

i = 0, 1, \dots, ip - 1

and

j = i, \dots, ip - 1

5: $p [ip \times ip + 2 \times ip]$ – const doubleInput

On entry: p as returned by nag_regsn_mult_linear (g02dac) or nag_regsn_mult_linear_upd_model (g02ddc).

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,

f^{T} \hat{β}

9: $sestat$ – double *Output

On exit: if

est = Nag_TRUE

, sestat contains the standard error of the estimate of the function,

se (F)

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

tol \leq 0.0

\sqrt{machine precision}

is used instead.

12: $fail$ – NagError *Input/Output

The NAG error argument (see Section 2.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 $rank \leq ip$ .
NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_INT_ARG_LT: On entry, $ip = 〈value〉$ .
Constraint: $ip \geq 1$ .

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

NAG Library Function Documentnag_regsn_mult_linear_est_func (g02dnc)

▸▿ 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 Library Function Document

nag_regsn_mult_linear_est_func (g02dnc)