# NAG Library Function Document

## 1Purpose

nag_glm_est_func (g02gnc) gives the estimate of an estimable function along with its standard error from the results from fitting a generalized linear model.

## 2Specification

 #include #include
 void nag_glm_est_func (Integer ip, Integer rank, const double b[], const double cov[], const double v[], Integer tdv, const double f[], Nag_Boolean *est, double *stat, double *sestat, double *z, double tol, NagError *fail)

## 3Description

nag_glm_est_func (g02gnc) 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_glm_normal (g02gac), nag_glm_binomial (g02gbc), nag_glm_poisson (g02gcc) or nag_glm_gamma (g02gdc). 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_glm_normal (g02gac), nag_glm_binomial (g02gbc), nag_glm_poisson (g02gcc) and nag_glm_gamma (g02gdc).
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 $z$ statistic:
 $z = fT β ^ seF ,$
can be computed. The distribution of $z$ will be approximately Normal.

## 4References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
McCullagh P and Nelder J A (1983) Generalized Linear Models Chapman and Hall
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{v}\left[{\mathbf{ip}}×{\mathbf{tdv}}\right]$const doubleInput
Note: the $\left(i,j\right)$th element of the matrix $V$ is stored in ${\mathbf{v}}\left[\left(i-1\right)×{\mathbf{tdv}}+j-1\right]$.
6:    $\mathbf{tdv}$IntegerInput
On entry: the stride separating matrix column elements in the array v.
Constraint: ${\mathbf{tdv}}\ge {\mathbf{ip}}+6$.
7:    $\mathbf{f}\left[{\mathbf{ip}}\right]$const doubleInput
On entry: the linear function to be estimated, $f$.
8:    $\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 z are not set.
9:    $\mathbf{stat}$double *Output
On exit: if ${\mathbf{est}}=\mathrm{Nag_TRUE}$, stat contains the estimate of the function, ${f}^{\mathrm{T}}\stackrel{^}{\beta }$.
10:  $\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)$.
11:  $\mathbf{z}$double *Output
On exit: if ${\mathbf{est}}=\mathrm{Nag_TRUE}$, z contains the $z$ statistic for the test of the function being equal to zero.
12:  $\mathbf{tol}$doubleInput
On entry: tol is the tolerance value used in the check for estimability, $\eta$.
If ${\mathbf{tol}}\le 0.0$, then  is used instead.
13:  $\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_2_INT_ARG_LT
On entry, ${\mathbf{tdv}}=〈\mathit{\text{value}}〉$ while ${\mathbf{ip}}=〈\mathit{\text{value}}〉$. These arguments must satisfy ${\mathbf{tdv}}\ge {\mathbf{ip}}+6$.
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
sestat, the standard error of the estimate of the function, se$\left(F\right)=0.0$; probably due to rounding error or due to incorrectly specified input values of cov and f.

## 7Accuracy

The computations are believed to be stable.

## 8Parallelism and Performance

nag_glm_est_func (g02gnc) is not threaded in any implementation.

The value of estimable functions is independent of the solution chosen from the many possible solutions. While nag_glm_est_func (g02gnc) may be used to estimate functions of the arguments of the model as computed by nag_glm_tran_model (g02gkc), ${\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

A loglinear model is fitted to a 3 by 5 contingency table by nag_glm_poisson (g02gcc). The model consists of terms for for rows and columns. The table is:
 $141 67 114 79 39 131 66 143 72 35 36 14 38 28 16$
The number of functions to be tested is read in, then the linear functions themselves are read in and tested with nag_glm_est_func (g02gnc). The results of nag_glm_est_func (g02gnc) are printed.

### 10.1Program Text

Program Text (g02gnce.c)

### 10.2Program Data

Program Data (g02gnce.d)

### 10.3Program Results

Program Results (g02gnce.r)

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