G02GPF (PDF version)
G02 Chapter Contents
G02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G02GPF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

 Contents

    1  Purpose
    7  Accuracy

1  Purpose

G02GPF allows prediction from a generalized linear model fit via G02GAF, G02GBF, G02GCF or G02GDF.

2  Specification

SUBROUTINE G02GPF ( ERRFN, LINK, MEAN, OFFSET, WEIGHT, N, X, LDX, M, ISX, IP, T, OFF, WT, S, A, B, COV, VFOBS, ETA, SEETA, PRED, SEPRED, IFAIL)
INTEGER  N, LDX, M, ISX(M), IP, IFAIL
REAL (KIND=nag_wp)  X(LDX,*), T(*), OFF(*), WT(*), S, A, B(IP), COV(IP*(IP+1)/2), ETA(N), SEETA(N), PRED(N), SEPRED(N)
LOGICAL  VFOBS
CHARACTER(1)  ERRFN, LINK, MEAN, OFFSET, WEIGHT

3  Description

A generalized linear model consists of the following elements:
(i) A suitable distribution for the dependent variable y.
(ii) A linear model, with linear predictor η=Xβ, where X is a matrix of independent variables and β a column vector of p parameters.
(iii) A link function g. between the expected value of y and the linear predictor, that is Ey=μ=gη.
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 β and their associated variance-covariance matrix, C. Suitable values for β and C are usually estimated by first fitting the prediction model to a training dataset with known responses, using for example G02GAF, G02GBF, G02GCF or G02GDF. The predicted variable, and its standard error can then be obtained from:
y^ = g-1η ,   se y^ = δg-1x δx η seη + Ifobs Vary  
where
η=o+Xβ ,   seη = diagXCXT ,  
o is a vector of offsets and Ifobs=0, if the variance of future observations is not taken into account, and 1 otherwise. Here diagA indicates the diagonal elements of matrix A.
If required, the variance for the ith future observation, Varyi, can be calculated as:
Varyi = ϕ Vθ wi  
where wi is a weight, ϕ is the scale (or dispersion) parameter, and Vθ is the variance function. Both the scale parameter and the variance function depend on the distribution used for the y, with:
Poisson Vθ=μi, ϕ=1
binomial Vθ=μiti-μiti, ϕ=1
Normal Vθ=1
gamma Vθ=μi2
In the cases of a Normal and gamma error structure, the scale parameter (ϕ), is supplied by you. This value is usually obtained from the routine used to fit the prediction model. In many cases, for a Normal error structure, ϕ=σ^2, i.e., the estimated variance.

4  References

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

5  Arguments

1:     ERRFN – CHARACTER(1)Input
On entry: indicates the distribution used to model the dependent variable, y.
ERRFN='B'
The binomial distribution is used.
ERRFN='G'
The gamma distribution is used.
ERRFN='N'
The Normal (Gaussian) distribution is used.
ERRFN='P'
The Poisson distribution is used.
Constraint: ERRFN='B', 'G', 'N' or 'P'.
On entry: indicates which link function to be used.
LINK='C'
A complementary log-log link is used.
LINK='E'
An exponent link is used.
LINK='G'
A logistic link is used.
LINK='I'
An identity link is used.
LINK='L'
A log link is used.
LINK='P'
A probit link is used.
LINK='R'
A reciprocal link is used.
LINK='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 ERRFN='B', LINK='C', 'G' or 'P';
  • otherwise LINK='E', 'I', 'L', 'R' or 'S'.
3:     MEAN – CHARACTER(1)Input
On entry: indicates if a mean term is to be included.
MEAN='M'
A mean term, intercept, will be included in the model.
MEAN='Z'
The model will pass through the origin, zero-point.
Constraint: MEAN='M' or 'Z'.
4:     OFFSET – CHARACTER(1)Input
On entry: indicates if an offset is required.
OFFSET='Y'
An offset must be supplied in OFF.
OFFSET='N'
OFF is not referenced.
Constraint: OFFSET='Y' or 'N'.
5:     WEIGHT – CHARACTER(1)Input
On entry: if VFOBS=.TRUE. indicates if weights are used, otherwise WEIGHT is not referenced.
WEIGHT='U'
No weights are used.
WEIGHT='W'
Weights are used and must be supplied in WT.
Constraint: if VFOBS=.TRUE., WEIGHT='U' or 'W'.
6:     N – INTEGERInput
On entry: n, the number of observations.
Constraint: N1.
7:     XLDX* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array X must be at least M.
On entry: Xij must contain the ith observation for the jth independent variable, for i=1,2,,N and j=1,2,,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: LDXN.
9:     M – INTEGERInput
On entry: m, the total number of independent variables.
Constraint: M1.
10:   ISXM – INTEGER arrayInput
On entry: indicates which independent variables are to be included in the model.
If ISXj>0, the jth independent variable is included in the regression model.
Constraints:
  • ISXj0, for i=1,2,,M;
  • if MEAN='M', exactly IP-1 values of ISX must be >0;
  • if MEAN='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: IP>0.
12:   T* – REAL (KIND=nag_wp) arrayInput
Note: the dimension of the array must be at least N if ERRFN='B', and at least 1 otherwise.
On entry: if ERRFN='B', Ti must contain the binomial denominator, ti, for the ith observation.
Otherwise T is not referenced.
Constraint: if ERRFN='B', Ti0.0, for i=1,2,,n.
13:   OFF* – REAL (KIND=nag_wp) arrayInput
Note: the dimension of the array must be at least N if OFFSET='Y', and at least 1 otherwise.
On entry: if OFFSET='Y', OFFi must contain the offset oi, for the ith observation.
Otherwise OFF is not referenced.
14:   WT* – REAL (KIND=nag_wp) arrayInput
Note: the dimension of the array must be at least N if WEIGHT='W' and VFOBS=.TRUE., and at least 1 otherwise.
On entry: if WEIGHT='W' and VFOBS=.TRUE., WTi must contain the weight, wi, for the ith observation.
If the variance of future observations is not included in the standard error of the predicted variable, WT is not referenced.
Constraint: if VFOBS=.TRUE. and WEIGHT='W', WTi0., for i=1,2,,i.
15:   S – REAL (KIND=nag_wp)Input
On entry: if ERRFN='N' or 'G' and VFOBS=.TRUE., the scale parameter, ϕ.
Otherwise S is not referenced and ϕ=1.
Constraint: if ERRFN='N' or 'G' and VFOBS=.TRUE., S>0.0.
16:   A – REAL (KIND=nag_wp)Input
On entry: if LINK='E', A must contain the power of the exponential.
If LINK'E', A is not referenced.
Constraint: if LINK='E', A0.0.
17:   BIP – REAL (KIND=nag_wp) arrayInput
On entry: the model parameters, β.
If MEAN='M', B1 must contain the mean parameter and Bi+1 the coefficient of the variable contained in the jth independent X, where ISXj is the ith positive value in the array ISX.
If MEAN='Z', Bi must contain the coefficient of the variable contained in the jth independent X, where ISXj is the ith positive value in the array ISX.
18:   COVIP×IP+1/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 βi and βj, that is the values stored in Bi and Bj, should be supplied in COVj×j-1/2+i, for i=1,2,,IP and j=i,,IP.
Constraint: the matrix represented in COV must be a valid variance-covariance matrix.
19:   VFOBS – LOGICALInput
On entry: if VFOBS=.TRUE., the variance of future observations is included in the standard error of the predicted variable (i.e., Ifobs=1), otherwise Ifobs=0.
20:   ETAN – REAL (KIND=nag_wp) arrayOutput
On exit: the linear predictor, η.
21:   SEETAN – REAL (KIND=nag_wp) arrayOutput
On exit: the standard error of the linear predictor, seη.
22:   PREDN – REAL (KIND=nag_wp) arrayOutput
On exit: the predicted value, y^.
23:   SEPREDN – REAL (KIND=nag_wp) arrayOutput
On exit: the standard error of the predicted value, sey^. If PREDi could not be calculated, then G02GPF returns IFAIL=22, and SEPREDi is set to -99.0.
24:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ 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 arguments may be useful even if IFAIL0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: G02GPF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
On entry, ERRFN is invalid: ERRFN=value.
IFAIL=2
On entry, ERRFN and LINK combination is invalid: ERRFN=value, LINK=value.
On entry, LINK is invalid: LINK=value.
IFAIL=3
On entry, MEAN is invalid: MEAN=value.
IFAIL=4
On entry, OFFSET is invalid: OFFSET=value.
IFAIL=5
On entry, WEIGHT is invalid: WEIGHT=value.
IFAIL=6
On entry, N=value.
Constraint: N1.
IFAIL=8
On entry, LDX=value and N=value.
Constraint: LDXN.
IFAIL=9
On entry, M=value.
Constraint: M1.
IFAIL=10
On entry, ISX not consistent with IP: value values >0, expected value.
IFAIL=11
On entry, IP=value.
Constraint: IP>0.
IFAIL=12
On entry, i=value and Ti=value.
Constraint: Ti0.0, for all i.
IFAIL=14
On entry, i=value and WTi=value.
Constraint: WTi0.0, for all i.
IFAIL=15
On entry, S=value.
Constraint: S>0.0.
IFAIL=16
On entry, A=0.0.
IFAIL=18
On entry, COVi<0.0 for at least one diagonal element: i=value, COVi=value.
IFAIL=22
At least one predicted value could not be calculated as required. SEPRED is set to -99.0 for affected predicted values.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7  Accuracy

Not applicable.

8  Parallelism and Performance

G02GPF 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 routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9  Further Comments

None.

10  Example

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

Program Text (g02gpfe.f90)

10.2  Program Data

Program Data (g02gpfe.d)

10.3  Program Results

Program Results (g02gpfe.r)


G02GPF (PDF version)
G02 Chapter Contents
G02 Chapter Introduction
NAG Library Manual

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