NAG Library Function Document

1Purpose

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

2Specification

 #include #include
 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)

3Description

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, $\stackrel{^}{\beta }$, 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=\left({P}_{1}{P}_{0}\right)$, ${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={f}^{\mathrm{T}}\beta$, can be tested to see if it is estimable by computing $\zeta ={P}_{0}^{\mathrm{T}}f$. If $\zeta$ is zero, then the function is estimable, if not, the function is not estimable. In practice $\left|\zeta \right|$ is tested against some small quantity $\eta$.
Given that $F$ is estimable it can be estimated by ${f}^{\mathrm{T}}\stackrel{^}{\beta }$ and its standard error calculated from the variance-covariance matrix of $\stackrel{^}{\beta }$, ${C}_{\beta }$, 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.
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

5Arguments

1:    $\mathbf{ip}$IntegerInput
On entry: the number of terms in the linear model, $p$.
Constraint: ${\mathbf{ip}}\ge 1$.
2:    $\mathbf{rank}$IntegerInput
On entry: the rank of the independent variables, $k$.
Constraint: $1\le {\mathbf{rank}}\le {\mathbf{ip}}$.
3:    $\mathbf{b}\left[{\mathbf{ip}}\right]$const doubleInput
On entry: the ip values of the estimates of the arguments of the model, $\stackrel{^}{\beta }$.
4:    $\mathbf{cov}\left[{\mathbf{ip}}×\left({\mathbf{ip}}+1\right)/2\right]$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 ${\mathbf{b}}\left[\mathit{i}\right]$ and the parameter estimate given in ${\mathbf{b}}\left[\mathit{j}\right]$, $\mathit{j}\ge \mathit{i}$, is stored in ${\mathbf{cov}}\left[\mathit{j}\left(\mathit{j}+1\right)/2+\mathit{i}\right]$, for $\mathit{i}=0,1,\dots ,{\mathbf{ip}}-1$ and $\mathit{j}=\mathit{i},\dots ,{\mathbf{ip}}-1$.
5:    $\mathbf{p}\left[{\mathbf{ip}}×{\mathbf{ip}}+2×{\mathbf{ip}}\right]$const doubleInput
6:    $\mathbf{f}\left[{\mathbf{ip}}\right]$const doubleInput
On entry: the linear function to be estimated, $f$.
7:    $\mathbf{est}$Nag_Boolean *Output
On exit: est indicates if the function was estimable.
${\mathbf{est}}=\mathrm{Nag_TRUE}$
The function is estimable.
${\mathbf{est}}=\mathrm{Nag_FALSE}$
The function is not estimable and stat, sestat and t are not set.
8:    $\mathbf{stat}$double *Output
On exit: if ${\mathbf{est}}=\mathrm{Nag_TRUE}$, stat contains the estimate of the function, ${f}^{\mathrm{T}}\stackrel{^}{\beta }$.
9:    $\mathbf{sestat}$double *Output
On exit: if ${\mathbf{est}}=\mathrm{Nag_TRUE}$, sestat contains the standard error of the estimate of the function, $\mathrm{se}\left(F\right)$.
10:  $\mathbf{t}$double *Output
On exit: if ${\mathbf{est}}=\mathrm{Nag_TRUE}$, t contains the $t$-statistic for the test of the function being equal to zero.
11:  $\mathbf{tol}$doubleInput
On entry: tol is the tolerance value used in the check for estimability, $\eta$. If ${\mathbf{tol}}\le 0.0$,  is used instead.
12:  $\mathbf{fail}$NagError *Input/Output
The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6Error Indicators and Warnings

NE_2_INT_ARG_GT
On entry, ${\mathbf{ip}}=〈\mathit{\text{value}}〉$ while ${\mathbf{rank}}=〈\mathit{\text{value}}〉$. These arguments must satisfy ${\mathbf{rank}}\le {\mathbf{ip}}$.
NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_INT_ARG_LT
On entry, ${\mathbf{ip}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ip}}\ge 1$.
On entry, ${\mathbf{rank}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{rank}}\ge 1$.
NE_RANK_EQ_IP
On entry, ${\mathbf{rank}}={\mathbf{ip}}$. In this case, the boolean variable est is returned as Nag_TRUE and all statistics are calculated.
NE_STDES_ZERO
se$\left(F\right)=0.0$ probably due to rounding error or due to incorrectly specified inputs cov and f.

7Accuracy

The computations are believed to be stable.

8Parallelism and Performance

nag_regsn_mult_linear_est_func (g02dnc) is not threaded in any implementation.

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), ${\beta }_{c}$, these must be expressed in terms of the original arguments, $\beta$. The relation between the two sets of arguments may not be straightforward.

10Example

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.1Program Text

Program Text (g02dnce.c)

10.2Program Data

Program Data (g02dnce.d)

10.3Program Results

Program Results (g02dnce.r)

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