# NAG CL Interfaceg02gpc (glm_​predict)

Settings help

CL Name Style:

## 1Purpose

g02gpc allows prediction from a generalized linear model fit via g02gac, g02gbc, g02gcc or g02gdc or a linear model fit via g02dac.

## 2Specification

 #include
 void g02gpc (Nag_Distributions errfn, Nag_Link link, Nag_IncludeMean mean, Integer n, const double x[], Integer tdx, Integer m, const Integer sx[], Integer ip, const double binom_t[], const double offset[], const double wt[], double scale, double ex_power, const double b[], const double cov[], Nag_Boolean vfobs, double eta[], double seeta[], double pred[], double sepred[], NagError *fail)
The function may be called by the names: g02gpc, nag_correg_glm_predict or nag_glm_predict.

## 3Description

A generalized linear model consists of the following elements:
1. (i)A suitable distribution for the dependent variable $y$.
2. (ii)A linear model, with linear predictor $\eta =X\beta$, where $X$ is a matrix of independent variables and $\beta$ a column vector of $p$ parameters.
3. (iii)A link function $g\left(.\right)$ between the expected value of $y$ and the linear predictor, that is $E\left(y\right)=\mu =g\left(\eta \right)$.
In order to predict from a generalized linear model, that is estimate a value for the dependent variable, $y$, given a set of independent variables $X$, the matrix $X$ must be supplied, along with values for the parameters $\beta$ and their associated variance-covariance matrix, $C$. Suitable values for $\beta$ and $C$ are usually estimated by first fitting the prediction model to a training dataset with known responses, using for example g02gac, g02gbc, g02gcc or g02gdc. The predicted variable, and its standard error can then be obtained from:
 $y^ = g-1(η) , se(y^) = ( δg-1(x) δx ) η se(η) + Ifobs Var(y)$
where
 $η=o+Xβ , se(η) = diag⁡XCXT ,$
$o$ is a vector of offsets and ${I}_{\mathrm{fobs}}=0$, if the variance of future observations is not taken into account, and $1$ otherwise. Here $\mathrm{diag}A$ indicates the diagonal elements of matrix $A$.
If required, the variance for the $i$th future observation, $\mathrm{Var}\left({y}_{i}\right)$, can be calculated as:
 $Var(yi) = ϕ V(θ) wi$
where ${w}_{i}$ is a weight, $\varphi$ is the scale (or dispersion) parameter, and $V\left(\theta \right)$ is the variance function. Both the scale parameter and the variance function depend on the distribution used for the $y$, with:
 Poisson $V\left(\theta \right)={\mu }_{i}$, $\varphi =1$ binomial $V\left(\theta \right)=\frac{{\mu }_{i}\left({t}_{i}-{\mu }_{i}\right)}{{t}_{i}}$, $\varphi =1$ Normal $V\left(\theta \right)=1$ gamma $V\left(\theta \right)={\mu }_{i}^{2}$
In the cases of a Normal and gamma error structure, the scale parameter ($\varphi$), is supplied by you. This value is usually obtained from the function used to fit the prediction model. In many cases, for a Normal error structure, $\varphi ={\stackrel{^}{\sigma }}^{2}$, i.e., the estimated variance.

## 4References

McCullagh P and Nelder J A (1983) Generalized Linear Models Chapman and Hall

## 5Arguments

1: $\mathbf{errfn}$Nag_Distributions Input
On entry: indicates the distribution used to model the dependent variable, $y$.
${\mathbf{errfn}}=\mathrm{Nag_Binomial}$
The binomial distribution is used.
${\mathbf{errfn}}=\mathrm{Nag_Gamma}$
The gamma distribution is used.
${\mathbf{errfn}}=\mathrm{Nag_Normal}$
The Normal (Gaussian) distribution is used.
${\mathbf{errfn}}=\mathrm{Nag_Poisson}$
The Poisson distribution is used.
Constraint: ${\mathbf{errfn}}=\mathrm{Nag_Binomial}$, $\mathrm{Nag_Gamma}$, $\mathrm{Nag_Normal}$ or $\mathrm{Nag_Poisson}$.
On entry: indicates which link function is to be used.
${\mathbf{link}}=\mathrm{Nag_Compl}$
A complementary log-log link is used.
${\mathbf{link}}=\mathrm{Nag_Expo}$
${\mathbf{link}}=\mathrm{Nag_Logistic}$
${\mathbf{link}}=\mathrm{Nag_Iden}$
${\mathbf{link}}=\mathrm{Nag_Log}$
${\mathbf{link}}=\mathrm{Nag_Probit}$
${\mathbf{link}}=\mathrm{Nag_Reci}$
${\mathbf{link}}=\mathrm{Nag_Sqrt}$
A square root link is used.
Details on the functional form of the different links can be found in the G02 Chapter Introduction.
Constraints:
• if ${\mathbf{errfn}}=\mathrm{Nag_Binomial}$, ${\mathbf{link}}=\mathrm{Nag_Compl}$, $\mathrm{Nag_Logistic}$ or $\mathrm{Nag_Probit}$;
• otherwise ${\mathbf{link}}=\mathrm{Nag_Expo}$, $\mathrm{Nag_Iden}$, $\mathrm{Nag_Log}$, $\mathrm{Nag_Reci}$ or $\mathrm{Nag_Sqrt}$.
3: $\mathbf{mean}$Nag_IncludeMean Input
On entry: indicates if a mean term is to be included.
${\mathbf{mean}}=\mathrm{Nag_MeanInclude}$
A mean term, intercept, will be included in the model.
${\mathbf{mean}}=\mathrm{Nag_MeanZero}$
The model will pass through the origin, zero-point.
Constraint: ${\mathbf{mean}}=\mathrm{Nag_MeanInclude}$ or $\mathrm{Nag_MeanZero}$.
4: $\mathbf{n}$Integer Input
On entry: $n$, the number of observations.
Constraint: ${\mathbf{n}}\ge 1$.
5: $\mathbf{x}\left[\mathit{dim}\right]$const double Input
Note: the dimension, dim, of the array x must be at least ${\mathbf{n}}×{\mathbf{tdx}}$.
On entry: ${\mathbf{x}}\left[\left(\mathit{i}-1\right)×{\mathbf{tdx}}+\mathit{j}-1\right]$ must contain the $\mathit{i}$th observation for the $\mathit{j}$th independent variable, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$ and $\mathit{j}=1,2,\dots ,{\mathbf{m}}$.
6: $\mathbf{tdx}$Integer Input
On entry: the stride separating matrix column elements in the array x.
Constraint: ${\mathbf{tdx}}\ge {\mathbf{m}}$
7: $\mathbf{m}$Integer Input
On entry: $m$, the total number of independent variables.
Constraint: ${\mathbf{m}}\ge 1$.
8: $\mathbf{sx}\left[{\mathbf{m}}\right]$const Integer Input
On entry: indicates which independent variables are to be included in the model.
If ${\mathbf{sx}}\left[j-1\right]>0$, the variable contained in the $j$th column of x is included in the regression model.
Constraints:
• ${\mathbf{sx}}\left[\mathit{j}\right]\ge 0$, for $\mathit{j}=0,1,\dots ,{\mathbf{m}}-1$;
• if ${\mathbf{mean}}=\mathrm{Nag_MeanInclude}$, exactly ${\mathbf{ip}}-1$ values of sx must be $\text{}>0$;
• if ${\mathbf{mean}}=\mathrm{Nag_MeanZero}$, exactly ip values of sx must be $\text{}>0$.
9: $\mathbf{ip}$Integer Input
On entry: the number of independent variables in the model, including the mean or intercept if present.
Constraint: ${\mathbf{ip}}>0$.
10: $\mathbf{binom_t}\left[\mathit{dim}\right]$const double Input
Note: the dimension, dim, of the array binom_t must be at least
• ${\mathbf{n}}$, when ${\mathbf{errfn}}=\mathrm{Nag_Binomial}$.
On entry: if ${\mathbf{errfn}}=\mathrm{Nag_Binomial}$, ${\mathbf{binom_t}}\left[i-1\right]$ must contain the binomial denominator, ${t}_{i}$, for the $i$th observation.
Otherwise binom_t is not referenced and may be NULL.
Constraint: if ${\mathbf{errfn}}=\mathrm{Nag_Binomial}$, ${\mathbf{binom_t}}\left[\mathit{i}-1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,n$.
11: $\mathbf{offset}\left[\mathit{dim}\right]$const double Input
Note: the dimension, dim, of the array offset must be at least
• ${\mathbf{n}}$, when ${\mathbf{offset}}\phantom{\rule{0.25em}{0ex}}\text{is not}\phantom{\rule{0.25em}{0ex}}\mathbf{NULL}$.
On entry: if an offset is required, then ${\mathbf{offset}}\left[i-1\right]$ must contain the value of the offset ${o}_{i}$, for the $i$th observation. Otherwise offset must be NULL.
12: $\mathbf{wt}\left[\mathit{dim}\right]$const double Input
Note: the dimension, dim, of the array wt must be at least
• ${\mathbf{n}}$, when .
On entry: if weighted estimates are required then ${\mathbf{wt}}\left[i-1\right]$ must contain the weight, ${\omega }_{i}$ for the $i$th observation. Otherwise wt must be supplied as NULL.
If ${\mathbf{wt}}\left[i-1\right]=0.0$, the $i$th observation is not included in the model, in which case the effective number of observations is the number of observations with positive weights.
If ${\mathbf{wt}}=\text{}$ NULL, the effective number of observations is $n$.
If the variance of future observations is not included in the standard error of the predicted variable, wt is not referenced.
Constraint: if ${\mathbf{wt}}\phantom{\rule{0.25em}{0ex}}\text{is not}\phantom{\rule{0.25em}{0ex}}\mathbf{NULL}$ and ${\mathbf{vfobs}}=\mathrm{Nag_TRUE}$, ${\mathbf{wt}}\left[\mathit{i}-1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
13: $\mathbf{scale}$double Input
On entry: if ${\mathbf{errfn}}=\mathrm{Nag_Normal}$ or $\mathrm{Nag_Gamma}$ and ${\mathbf{vfobs}}=\mathrm{Nag_TRUE}$, the scale parameter, $\varphi$.
Otherwise scale is not referenced and $\varphi =1$.
Constraint: if ${\mathbf{errfn}}=\mathrm{Nag_Normal}$ or $\mathrm{Nag_Gamma}$ and ${\mathbf{vfobs}}=\mathrm{Nag_TRUE}$, ${\mathbf{scale}}>0.0$.
14: $\mathbf{ex_power}$double Input
On entry: if ${\mathbf{link}}=\mathrm{Nag_Expo}$, ex_power must contain the power of the exponential.
If ${\mathbf{link}}\ne \mathrm{Nag_Expo}$, ex_power is not referenced.
Constraint: if ${\mathbf{link}}=\mathrm{Nag_Expo}$, ${\mathbf{ex_power}}\ne 0.0$.
15: $\mathbf{b}\left[{\mathbf{ip}}\right]$const double Input
On entry: the model parameters, $\beta$.
If ${\mathbf{mean}}=\mathrm{Nag_MeanInclude}$, ${\mathbf{b}}\left[0\right]$ must contain the mean parameter and ${\mathbf{b}}\left[i\right]$ the coefficient of the variable contained in the $j$th independent x, where ${\mathbf{sx}}\left[j-1\right]$ is the $i$th positive value in the array sx.
If ${\mathbf{mean}}=\mathrm{Nag_MeanZero}$, ${\mathbf{b}}\left[i-1\right]$ must contain the coefficient of the variable contained in the $j$th independent x, where ${\mathbf{sx}}\left[j-1\right]$ is the $i$th positive value in the array sx.
16: $\mathbf{cov}\left[{\mathbf{ip}}×\left({\mathbf{ip}}+1\right)/2\right]$const double Input
On entry: the upper triangular part of the variance-covariance matrix, $C$, of the model parameters. This matrix should be supplied packed by column, i.e., the covariance between parameters ${\beta }_{i}$ and ${\beta }_{j}$, that is the values stored in ${\mathbf{b}}\left[i-1\right]$ and ${\mathbf{b}}\left[j-1\right]$, should be supplied in ${\mathbf{cov}}\left[\mathit{j}×\left(\mathit{j}-1\right)/2+\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,{\mathbf{ip}}$ and $\mathit{j}=\mathit{i},\dots ,{\mathbf{ip}}$.
Constraint: the matrix represented in cov must be a valid variance-covariance matrix.
17: $\mathbf{vfobs}$Nag_Boolean Input
On entry: if ${\mathbf{vfobs}}=\mathrm{Nag_TRUE}$, the variance of future observations is included in the standard error of the predicted variable (i.e., ${I}_{\mathrm{fobs}}=1$), otherwise ${I}_{\mathrm{fobs}}=0$.
18: $\mathbf{eta}\left[{\mathbf{n}}\right]$double Output
On exit: the linear predictor, $\eta$.
19: $\mathbf{seeta}\left[{\mathbf{n}}\right]$double Output
On exit: the standard error of the linear predictor, $\mathrm{se}\left(\eta \right)$.
20: $\mathbf{pred}\left[{\mathbf{n}}\right]$double Output
On exit: the predicted value, $\stackrel{^}{y}$.
21: $\mathbf{sepred}\left[{\mathbf{n}}\right]$double Output
On exit: the standard error of the predicted value, $\mathrm{se}\left(\stackrel{^}{y}\right)$. If ${\mathbf{pred}}\left[i-1\right]$ could not be calculated, g02gpc returns ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_INVALID_PRED, and ${\mathbf{sepred}}\left[i-1\right]$ is set to $-99.0$.
22: $\mathbf{fail}$NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

## 6Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
On entry, the error type and link function combination supplied is invalid.
NE_CHARACTER
On entry, ${\mathbf{link}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{errfn}}=\mathrm{Nag_Binomial}$, ${\mathbf{link}}=\mathrm{Nag_Compl}$, $\mathrm{Nag_Logistic}$ or $\mathrm{Nag_Probit}$,
otherwise, ${\mathbf{link}}=\mathrm{Nag_Expo}$, $\mathrm{Nag_Iden}$, $\mathrm{Nag_Log}$, $\mathrm{Nag_Reci}$ or $\mathrm{Nag_Sqrt}$.
NE_INT
On entry, ${\mathbf{ip}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ip}}>0$.
On entry, ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{m}}\ge 1$.
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 1$.
NE_INT_2
On entry, ${\mathbf{tdx}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{tdx}}\ge {\mathbf{m}}$.
NE_INT_ARRAY_CONS
On entry, ${\mathbf{sx}}\left[⟨\mathit{\text{value}}⟩\right]<0$.
Constraint: ${\mathbf{sx}}\left[j-1\right]\ge 0.0$, for $j=1,2,\dots ,{\mathbf{m}}$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_INVALID_PRED
At least one predicted value could not be calculated as required. sepred is set to $-99.0$ for affected predicted values.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
NE_REAL
On entry, ${\mathbf{ex_power}}=0.0$.
Constraint: if ${\mathbf{link}}=\mathrm{Nag_Expo}$, ${\mathbf{ex_power}}\ne 0.0$.
On entry, ${\mathbf{scale}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{scale}}>0.0$.
NE_REAL_ARRAY_CONS
On entry, ${\mathbf{binom_t}}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{binom_t}}\left[i-1\right]\ge 0.0$, for all $i$.
On entry, ${\mathbf{cov}}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{cov}}\left[i\right]\ge 0.0$ for at least one diagonal element.
On entry, ${\mathbf{wt}}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{wt}}\left[i-1\right]\ge 0.0$, for all $i$.

Not applicable.

## 8Parallelism and Performance

g02gpc makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

When using g02gpc following a call to g02dac you should set ${\mathbf{errfn}}=\mathrm{Nag_Normal}$, ${\mathbf{link}}=\mathrm{Nag_Iden}$, ${\mathbf{offset}}="N"$ and ${\mathbf{scale}}=\frac{{\mathbf{rss}}}{{\mathbf{idf}}}$.

## 10Example

The model
 $y = 1 β1 + β2 x + ε$
is fitted to a training dataset with five observations. The resulting model is then used to predict the response for two new observations.

### 10.1Program Text

Program Text (g02gpce.c)

### 10.2Program Data

Program Data (g02gpce.d)

### 10.3Program Results

Program Results (g02gpce.r)