NAG Library Routine Document

G02GPF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     ERRFN – CHARACTER(1)Input

On entry: indicates the distribution used to model the dependent variable, $y$.

$\mathbf{ERRFN}=\text{'B'}$

The binomial distribution is used.

$\mathbf{ERRFN}=\text{'G'}$

The gamma distribution is used.

$\mathbf{ERRFN}=\text{'N'}$

The Normal (Gaussian) distribution is used.

$\mathbf{ERRFN}=\text{'P'}$

The Poisson distribution is used.

Constraint: $\mathbf{ERRFN}=\text{'B'}$, $\text{'G'}$, $\text{'N'}$ or $\text{'P'}$.

2:     LINK – CHARACTER(1)Input

On entry: indicates which link function to be used.

$\mathbf{LINK}=\text{'C'}$

A complementary log-log link is used.

$\mathbf{LINK}=\text{'E'}$

An exponent link is used.

$\mathbf{LINK}=\text{'G'}$

A logistic link is used.

$\mathbf{LINK}=\text{'I'}$

An identity link is used.

$\mathbf{LINK}=\text{'L'}$

A log link is used.

$\mathbf{LINK}=\text{'P'}$

A probit link is used.

$\mathbf{LINK}=\text{'R'}$

A reciprocal link is used.

$\mathbf{LINK}=\text{'S'}$

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}=\text{'B'}$, $\mathbf{LINK}=\text{'C'}$, $\text{'G'}$ or $\text{'P'}$;
• otherwise $\mathbf{LINK}=\text{'E'}$, $\text{'I'}$, $\text{'L'}$, $\text{'R'}$ or $\text{'S'}$.

3:     MEAN – CHARACTER(1)Input

On entry: indicates if a mean term is to be included.

$\mathbf{MEAN}=\text{'M'}$

A mean term, intercept, will be included in the model.

$\mathbf{MEAN}=\text{'Z'}$

The model will pass through the origin, zero-point.

Constraint: $\mathbf{MEAN}=\text{'M'}$ or $\text{'Z'}$.

4:     OFFSET – CHARACTER(1)Input

On entry: indicates if an offset is required.

$\mathbf{OFFSET}=\text{'Y'}$

An offset must be supplied in OFF.

$\mathbf{OFFSET}=\text{'N'}$

OFF is not referenced.

Constraint: $\mathbf{OFFSET}=\text{'Y'}$ or $\text{'N'}$.

5:     WEIGHT – CHARACTER(1)Input

On entry: if $\mathbf{VFOBS}=\mathrm{.TRUE.}$ indicates if weights are used, otherwise WEIGHT is not referenced.

$\mathbf{WEIGHT}=\text{'U'}$

No weights are used.

$\mathbf{WEIGHT}=\text{'W'}$

Weights are used and must be supplied in WT.

Constraint: if $\mathbf{VFOBS}=\mathrm{.TRUE.}$, $\mathbf{WEIGHT}=\text{'U'}$ or $\text{'W'}$.

6:     N – INTEGERInput

On entry: $n$, the number of observations.

Constraint: $\mathbf{N}\ge 1$.

7:     X(LDX,M) – REAL (KIND=nag_wp) arrayInput

On entry: $\mathbf{X}\left(\mathit{i},\mathit{j}\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}$.

8:     LDX – INTEGERInput

On entry: the first dimension of the array X as declared in the (sub)program from which G02GPF is called.

Constraint: $\mathbf{LDX}\ge \mathbf{N}$.

9:     M – INTEGERInput

On entry: $m$, the total number of independent variables.

Constraint: $\mathbf{M}\ge 1$.

10:   ISX(M) – INTEGER arrayInput

On entry: indicates which independent variables are to be included in the model.

If $\mathbf{ISX}\left(j\right)>0$, the $j$th independent variable is included in the regression model.

Constraints:

• $\mathbf{ISX}\left(j\right)\ge 0$, for $\mathit{i}=1,2,\dots ,\mathbf{M}$;
• if $\mathbf{MEAN}=\text{'M'}$, exactly $\mathbf{IP}-1$ values of ISX must be $>0$;
• if $\mathbf{MEAN}=\text{'Z'}$, exactly IP values of ISX must be $>0$.

11:   IP – INTEGERInput

On entry: the number of independent variables in the model, including the mean or intercept if present.

Constraint: $\mathbf{IP}>0$.

12:   T($*$) – REAL (KIND=nag_wp) arrayInput

Note: the dimension of the array must be at least $\mathbf{N}$ if $\mathbf{ERRFN}=\text{'B'}$, and at least $1$ otherwise.

On entry: if $\mathbf{ERRFN}=\text{'B'}$, $\mathbf{T}\left(i\right)$ must contain the binomial denominator, $t_i$, for the $i$th observation.

Otherwise T is not referenced.

Constraint: if $\mathbf{ERRFN}=\text{'B'}$, $\mathbf{T}\left(\mathit{i}\right)\ge 0.0$, for $\mathit{i}=1,2,\dots ,n$.

13:   OFF($*$) – REAL (KIND=nag_wp) arrayInput

Note: the dimension of the array must be at least $\mathbf{N}$ if $\mathbf{OFFSET}=\text{'Y'}$, and at least $1$ otherwise.

On entry: if $\mathbf{OFFSET}=\text{'Y'}$, $\mathbf{OFF}\left(i\right)$ must contain the offset $o_i$, for the $i$th observation.

Otherwise OFF is not referenced.

14:   WT($*$) – REAL (KIND=nag_wp) arrayInput

Note: the dimension of the array must be at least $\mathbf{N}$ if $\mathbf{WEIGHT}=\text{'W'}$ and $\mathbf{VFOBS}=\mathrm{.TRUE.}$, and at least $1$ otherwise.

On entry: if $\mathbf{WEIGHT}=\text{'W'}$ and $\mathbf{VFOBS}=\mathrm{.TRUE.}$, $\mathbf{WT}\left(i\right)$ must contain the weight, $w_i$, for the $i$th observation.

If the variance of future observations is not included in the standard error of the predicted variable, WT is not referenced.

Constraint: if $\mathbf{VFOBS}=\mathrm{.TRUE.}$ and $\mathbf{WEIGHT}=\text{'W'}$, $\mathbf{WT}\left(\mathit{i}\right)\ge 0$., for $\mathit{i}=1,2,\dots ,\mathit{i}$.

15:   S – REAL (KIND=nag_wp)Input

On entry: if $\mathbf{ERRFN}=\text{'N'}$ or $\text{'G'}$ and $\mathbf{VFOBS}=\mathrm{.TRUE.}$, the scale parameter, $\varphi$.

Otherwise S is not referenced and $\varphi =1$.

Constraint: if $\mathbf{ERRFN}=\text{'N'}$ or $\text{'G'}$ and $\mathbf{VFOBS}=\mathrm{.TRUE.}$, $\mathbf{S}>0.0$.

16:   A – REAL (KIND=nag_wp)Input

On entry: if $\mathbf{LINK}=\text{'E'}$, A must contain the power of the exponential.

If $\mathbf{LINK}\ne \text{'E'}$, A is not referenced.

Constraint: if $\mathbf{LINK}=\text{'E'}$, $\mathbf{A}\ne 0.0$.

17:   B(IP) – REAL (KIND=nag_wp) arrayInput

On entry: the model parameters, $\beta$.

If $\mathbf{MEAN}=\text{'M'}$, $\mathbf{B}\left(1\right)$ must contain the mean parameter and $\mathbf{B}\left(i+1\right)$ the coefficient of the variable contained in the $j$th independent X, where $\mathbf{ISX}\left(j\right)$ is the $i$th positive value in the array ISX.

If $\mathbf{MEAN}=\text{'Z'}$, $\mathbf{B}\left(i\right)$ must contain the coefficient of the variable contained in the $j$th independent X, where $\mathbf{ISX}\left(j\right)$ is the $i$th positive value in the array ISX.

18:   COV($\mathbf{IP}\times \left(\mathbf{IP}+1\right)/2$) – REAL (KIND=nag_wp) arrayInput

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\right)$ and $\mathbf{B}\left(j\right)$, should be supplied in $\mathbf{COV}\left(\mathit{j}\times \left(\mathit{j}-1\right)/2+\mathit{i}\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.

19:   VFOBS – LOGICALInput

On entry: if $\mathbf{VFOBS}=\mathrm{.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$.

20:   ETA(N) – REAL (KIND=nag_wp) arrayOutput

On exit: the linear predictor, $\eta$.

21:   SEETA(N) – REAL (KIND=nag_wp) arrayOutput

On exit: the standard error of the linear predictor, $\mathrm{se}\left(\eta \right)$.

22:   PRED(N) – REAL (KIND=nag_wp) arrayOutput

On exit: the predicted value, $\hat{y}$.

23:   SEPRED(N) – REAL (KIND=nag_wp) arrayOutput

On exit: the standard error of the predicted value, $\mathrm{se}\left(\hat{y}\right)$. If $\mathbf{PRED}\left(i\right)$ could not be calculated, then G02GPF returns $\mathbf{IFAIL}=\mathbf{22}$, and $\mathbf{SEPRED}\left(i\right)$ is set to $-99.0$.

24:   IFAIL – INTEGERInput/Output

On entry: IFAIL must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, because for this routine the values of the output parameters may be useful even if $\mathbf{IFAIL}\ne \mathbf{0}$ on exit, the recommended value is $-1$. When the value $-\mathbf{1}\text{ or }1$ is used it is essential to test the value of IFAIL on exit.

On exit: $\mathbf{IFAIL}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and Warnings

$\mathbf{IFAIL}=1$

On entry, $\mathbf{ERRFN}\ne \text{'B'}$, $\text{'P'}$, $\text{'G'}$ or $\text{'N'}$.

$\mathbf{IFAIL}=2$

On entry, $\mathbf{ERRFN}=\text{'B'}$ and $\mathbf{LINK}\ne \text{'G'}$, $\text{'P'}$ or $\text{'C'}$ or $\mathbf{ERRFN}\ne \text{'B'}$ and $\mathbf{LINK}\ne \text{'E'}$, $\text{'I'}$, $\text{'L'}$, $\text{'R'}$ or $\text{'S'}$.

$\mathbf{IFAIL}=3$

On entry, $\mathbf{MEAN}\ne \text{'M'}$ or $\text{'Z'}$.

$\mathbf{IFAIL}=4$

On entry, $\mathbf{OFFSET}\ne \text{'Y'}$ or $\text{'N'}$.

$\mathbf{IFAIL}=5$

On entry, $\mathbf{VFOBS}=\mathrm{.TRUE.}$ and $\mathbf{WEIGHT}\ne \text{'U'}$ or $\text{'W'}$.

$\mathbf{IFAIL}=6$

On entry, $\mathbf{N}<1$.

$\mathbf{IFAIL}=8$

On entry, $\mathbf{LDX}<\mathbf{N}$.

$\mathbf{IFAIL}=9$

On entry, $\mathbf{M}\le 0$.

$\mathbf{IFAIL}=10$

On entry, number of nonzero elements in ISX is not consistent with IP.

$\mathbf{IFAIL}=11$

On entry, $\mathbf{IP}<1$.

$\mathbf{IFAIL}=12$

On entry, $\mathbf{ERRFN}=\text{'B'}$ and $\mathbf{T}\left(i\right)<0.0$ for at least one $i=1,2,\dots ,n$.

$\mathbf{IFAIL}=14$

On entry, $\mathbf{VFOBS}=\mathrm{.TRUE.}$, $\mathbf{WEIGHT}=\text{'W'}$ and $\mathbf{WT}\left(i\right)<0.0$ for at least one $i=1,2,\dots ,n$.

$\mathbf{IFAIL}=15$

On entry, $\mathbf{VFOBS}=\mathrm{.TRUE.}$, $\mathbf{ERRFN}=\text{'G'}$ or $\text{'N'}$ and $\mathbf{S}\le 0.0$.

$\mathbf{IFAIL}=16$

On entry, $\mathbf{LINK}=\text{'E'}$ and $\mathbf{A}=0.0$.

$\mathbf{IFAIL}=18$

On entry, supplied covariance matrix has at least one diagonal element $<0.0$.

$\mathbf{IFAIL}=22$

On exit, at least one predicted value could not be calculated as required. SEPRED is set to $-99.0$ for affected predicted values.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (g02gpfe.f90)

9.2  Program Data

Program Data (g02gpfe.d)

9.3  Program Results

Program Results (g02gpfe.r)