Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_correg_linregm_estfunc (g02dn)

## Purpose

nag_correg_linregm_estfunc (g02dn) gives the estimate of an estimable function along with its standard error.

## Syntax

[est, stat, sestat, t, ifail] = g02dn(irank, b, cov, p, f, tol, 'ip', ip)
[est, stat, sestat, t, ifail] = nag_correg_linregm_estfunc(irank, b, cov, p, f, tol, 'ip', ip)

## Description

nag_correg_linregm_estfunc (g02dn) 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_correg_linregm_fit (g02da) or nag_correg_linregm_update (g02dd). An estimable function is a linear combination of the parameters such that it has a unique estimate. For a full rank model all linear combinations of parameters 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$R$ obtained from the QR$QR$ decomposition of the independent variables the SVD gives
R = Q*
 ( D 0 ) 0 0
PT,
$R=Q* D 0 0 0 PT,$
where D$D$ is a k$k$ by k$k$ diagonal matrix with nonzero diagonal elements, k$k$ being the rank of R$R$, and Q*${Q}_{*}$ and P$P$ are p$p$ by p$p$ orthogonal matrices. This gives the solution
 β̂ = P1D − 1Q*1Tc1, $β^=P1D-1Q*1Tc1,$
P1${P}_{1}$ being the first k$k$ columns of P$P$, i.e., P = (P1P0)$P=\left({P}_{1}{P}_{0}\right)$, Q*1${Q}_{{*}_{1}}$ being the first k$k$ columns of Q*${Q}_{*}$, and c1${c}_{1}$ being the first p$p$ elements of c$c$.
Details of the SVD are made available in the form of the matrix P*${P}^{*}$:
P* =
 ( D − 1 P1T ) P0T
,
$P*= D-1 P1T P0T ,$
as given by nag_correg_linregm_fit (g02da) and nag_correg_linregm_update (g02dd).
A linear function of the parameters, F = fTβ$F={f}^{\mathrm{T}}\beta$, can be tested to see if it is estimable by computing ζ = P0T f$\zeta ={P}_{0}^{\mathrm{T}}f$. If ζ$\zeta$ is zero, then the function is estimable; if not, the function is not estimable. In practice |ζ|$|\zeta |$ is tested against some small quantity η$\eta$.
Given that F$F$ is estimable it can be estimated by fTβ̂${f}^{\mathrm{T}}\stackrel{^}{\beta }$ and its standard error calculated from the variance-covariance matrix of β̂$\stackrel{^}{\beta }$, Cβ${C}_{\beta }$, as
 se(F) = sqrt(fTCβf). $se(F)=fTCβf.$
Also a t$t$-statistic,
 t = (fTβ̂)/(se(F)), $t=fTβ^ se(F) ,$
can be computed. The t$t$-statistic will have a Student's t$t$-distribution with degrees of freedom as given by the degrees of freedom for the residual sum of squares for the model.

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

## Parameters

### Compulsory Input Parameters

1:     irank – int64int32nag_int scalar
k$k$, the rank of the independent variables.
Constraint: 1irankip$1\le {\mathbf{irank}}\le {\mathbf{ip}}$.
2:     b(ip) – double array
ip, the dimension of the array, must satisfy the constraint ip1${\mathbf{ip}}\ge 1$.
The ip values of the estimates of the parameters of the model, β̂$\stackrel{^}{\beta }$.
3:     cov(ip × (ip + 1) / 2${\mathbf{ip}}×\left({\mathbf{ip}}+1\right)/2$) – double array
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)${\mathbf{b}}\left(i\right)$ and the parameter estimate given in b(j)${\mathbf{b}}\left(j\right)$, ji$j\ge i$, is stored in cov((j × (j1) / 2 + i))${\mathbf{cov}}\left(\left(j×\left(j-1\right)/2+i\right)\right)$.
4:     p(ip × ip + 2 × ip${\mathbf{ip}}×{\mathbf{ip}}+2×{\mathbf{ip}}$) – double array
5:     f(ip) – double array
ip, the dimension of the array, must satisfy the constraint ip1${\mathbf{ip}}\ge 1$.
f$f$, the linear function to be estimated.
6:     tol – double scalar
η$\eta$, the tolerance value used in the check for estimability.
tol0.0${\mathbf{tol}}\le 0.0$
sqrt(ε)$\sqrt{\epsilon }$, where ε$\epsilon$ is the machine precision, is used instead.

### Optional Input Parameters

1:     ip – int64int32nag_int scalar
Default: The dimension of the arrays b, f. (An error is raised if these dimensions are not equal.)
p$p$, the number of terms in the linear model.
Constraint: ip1${\mathbf{ip}}\ge 1$.

wk

### Output Parameters

1:     est – logical scalar
Indicates if the function was estimable.
est = true${\mathbf{est}}=\mathbf{true}$
The function is estimable.
est = false${\mathbf{est}}=\mathbf{false}$
The function is not estimable and stat, sestat and t are not set.
2:     stat – double scalar
If est = true${\mathbf{est}}=\mathbf{true}$, stat contains the estimate of the function, fTβ̂${f}^{\mathrm{T}}\stackrel{^}{\beta }$.
3:     sestat – double scalar
If est = true${\mathbf{est}}=\mathbf{true}$, sestat contains the standard error of the estimate of the function, se(F)$\mathrm{se}\left(F\right)$.
4:     t – double scalar
If est = true${\mathbf{est}}=\mathbf{true}$, t contains the t$t$-statistic for the test of the function being equal to zero.
5:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Note: nag_correg_linregm_estfunc (g02dn) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

ifail = 1${\mathbf{ifail}}=1$
 On entry, ip < 1${\mathbf{ip}}<1$, or irank < 1${\mathbf{irank}}<1$, or ${\mathbf{irank}}>{\mathbf{ip}}$.
W ifail = 2${\mathbf{ifail}}=2$
 On entry, ${\mathbf{irank}}={\mathbf{ip}}$. In this case est is returned as true and all statistics are calculated.
ifail = 3${\mathbf{ifail}}=3$
Standard error of statistic = 0.0$\text{}=0.0$; this may be due to rounding errors if the standard error is very small or due to mis-specified inputs cov and f.

## Accuracy

The computations are believed to be stable.

The value of estimable functions is independent of the solution chosen from the many possible solutions. While nag_correg_linregm_estfunc (g02dn) may be used to estimate functions of the parameters of the model as computed by nag_correg_linregm_constrain (g02dk), βc${\beta }_{c}$, these must be expressed in terms of the original parameters, β$\beta$. The relation between the two sets of parameters may not be straightforward.

## Example

```function nag_correg_linregm_estfunc_example
irank = int64(4);
b = [30.55666666666667;
5.446666666666673;
6.743333333333336;
11.04666666666667;
7.32];
covar = [0.1481786666666657;
0.03704466666666638;
0.7038486666666622;
0.03704466666666652;
-0.222268;
0.7038486666666626;
0.03704466666666648;
-0.222268;
-0.222268;
0.7038486666666621;
0.03704466666666641;
-0.222268;
-0.222268;
-0.222268;
0.7038486666666622];
p = [1.135198279858991;
1.13078348304906;
1.234006904805161;
1.228003039942231;
1.263332232672042;
3.872983346207417;
1.732050807568878;
1.732050807568878;
1.732050807568877;
1.64780261914309e-16;
0.2309401076758503;
8.35089227579159e-18;
-1.238223776129407e-17;
7.900875770685859e-17;
-0.447213595499958;
0.0577350269189626;
0.2871305767251709;
0.2022129403845741;
-0.3559016137228031;
0.447213595499958;
0.05773502691896256;
0.03726461792122844;
0.271286303307133;
0.4183480487454616;
0.447213595499958;
0.05773502691896257;
0.1515575558927682;
-0.4677758485215264;
0.0906424999201606;
0.447213595499958;
0.05773502691896258;
-0.4759527505391677;
-0.005723395170180857;
-0.153088934942819;
0.4472135954999578];
f = [1;
1;
0;
0;
0];
tol = 1e-05;
[est, stat, sestat, t, ifail] = nag_correg_linregm_estfunc(irank, b, covar, p, f, tol)
```
```

est =

1

stat =

36.0033

sestat =

0.9623

t =

37.4119

ifail =

0

```
```function g02dn_example
irank = int64(4);
b = [30.55666666666667;
5.446666666666673;
6.743333333333336;
11.04666666666667;
7.32];
covar = [0.1481786666666657;
0.03704466666666638;
0.7038486666666622;
0.03704466666666652;
-0.222268;
0.7038486666666626;
0.03704466666666648;
-0.222268;
-0.222268;
0.7038486666666621;
0.03704466666666641;
-0.222268;
-0.222268;
-0.222268;
0.7038486666666622];
p = [1.135198279858991;
1.13078348304906;
1.234006904805161;
1.228003039942231;
1.263332232672042;
3.872983346207417;
1.732050807568878;
1.732050807568878;
1.732050807568877;
1.64780261914309e-16;
0.2309401076758503;
8.35089227579159e-18;
-1.238223776129407e-17;
7.900875770685859e-17;
-0.447213595499958;
0.0577350269189626;
0.2871305767251709;
0.2022129403845741;
-0.3559016137228031;
0.447213595499958;
0.05773502691896256;
0.03726461792122844;
0.271286303307133;
0.4183480487454616;
0.447213595499958;
0.05773502691896257;
0.1515575558927682;
-0.4677758485215264;
0.0906424999201606;
0.447213595499958;
0.05773502691896258;
-0.4759527505391677;
-0.005723395170180857;
-0.153088934942819;
0.4472135954999578];
f = [1;
1;
0;
0;
0];
tol = 1e-05;
[est, stat, sestat, t, ifail] = g02dn(irank, b, covar, p, f, tol)
```
```

est =

1

stat =

36.0033

sestat =

0.9623

t =

37.4119

ifail =

0

```