naginterfaces.library.correg.glm_​predict

naginterfaces.library.correg.glm_predict(errfn, x, isx, b, cov, vfobs, link=None, mean='M', t=None, off=None, wt=None, s=0.0, a=0.0)

glm_predict allows prediction from a generalized linear model fit via glm_normal(), glm_binomial(), glm_poisson() or glm_gamma() or a linear model fit via linregm_fit().

For full information please refer to the NAG Library document for g02gp

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g02/g02gpf.html

Parameters

errfnstr, length 1

Indicates the distribution used to model the dependent variable, $y$.

$errfn=\text{'B'}$

The binomial distribution is used.

$errfn=\text{'G'}$

The gamma distribution is used.

$errfn=\text{'N'}$

The Normal (Gaussian) distribution is used.

$errfn=\text{'P'}$

The Poisson distribution is used.

xfloat, array-like, shape $(n,m)$

$x[\text{i}-1,\text{j}-1]$ must contain the $\text{i}$th observation for the $\text{j}$th independent variable, for $\text{j}=1,2,\dots ,m$, for $\text{i}=1,2,\dots ,n$.

isxint, array-like, shape $\left(m\right)$

Indicates which independent variables are to be included in the model.

If $isx[j-1]>0$, the variable contained in the $j$th column of $x$ is included in the regression model.

bfloat, array-like, shape $\left(\text{ip}\right)$

The model parameters, $\beta$.

If $mean=\text{'M'}$, $b\left[0\right]$ must contain the mean parameter and $b\left[i\right]$ the coefficient of the variable contained in the $j$th independent $x$, where $isx[j-1]$ is the $i$th positive value in the array $isx$.

If $mean=\text{'Z'}$, $b[i-1]$ must contain the coefficient of the variable contained in the $j$th independent $x$, where $isx[j-1]$ is the $i$th positive value in the array $isx$.

covfloat, array-like, shape $(\text{ip}\times (\text{ip}+1)/2)$

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 $b[i-1]$ and $b[j-1]$, should be supplied in $cov[\text{j}\times (\text{j}-1)/2+\text{i}-1]$, for $\text{j}=\text{i},\dots ,\text{ip}$, for $\text{i}=1,2,\dots ,\text{ip}$.

vfobsbool

If $vfobs=True$, the variance of future observations is included in the standard error of the predicted variable (i.e., $I_{fobs}=1$), otherwise $I_{fobs}=0$.

linkNone or str, length 1, optional

Note: if this argument is None then a default value will be used, determined as follows: if $errfn=\text{'B'}$: $\text{'G'}$; if $errfn=\text{'G'}$: $\text{'R'}$; if $errfn=\text{'P'}$: $\text{'L'}$; otherwise: $\text{'I'}$.

Indicates which link function is to be used.

$link=\text{'C'}$

A complementary log-log link is used.

$link=\text{'E'}$

An exponent link is used.

$link=\text{'G'}$

A logistic link is used.

$link=\text{'I'}$

An identity link is used.

$link=\text{'L'}$

A log link is used.

$link=\text{'P'}$

A probit link is used.

$link=\text{'R'}$

A reciprocal link is used.

$link=\text{'S'}$

A square root link is used.

Details on the functional form of the different links can be found in the G02 Introduction.

meanstr, length 1, optional

Indicates if a mean term is to be included.

$mean=\text{'M'}$

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

$mean=\text{'Z'}$

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

tNone or float, array-like, shape $(:)$, optional

Note: the required length for this argument is determined as follows: if $errfn=\text{'B'}$: $n$; otherwise: $0$.

If $errfn=\text{'B'}$, $t[i-1]$ must contain the binomial denominator, $t_i$, for the $i$th observation.

Otherwise $t$ is not referenced and may be None.

offNone or float, array-like, shape $(:)$, optional

Note: the required length for this argument is determined as follows: if $off\text{is not}None$: $n$; otherwise: $0$.

If an offset is required, then $off[i-1]$ must contain the value of the offset $o_i$, for the $i$th observation. Otherwise $off$ must be None.

wtNone or float, array-like, shape $(:)$, optional

Note: the required length for this argument is determined as follows: if $wt\text{is not}None\text{and}vfobs=True$: $n$; otherwise: $0$.

If weighted estimates are required then $wt[i-1]$ must contain the weight, ${\omega }_i$ for the $i$th observation. Otherwise $wt$ must be supplied as None.

If $wt[i-1]=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 $wt=$ None, 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.

sfloat, optional

If $errfn=\text{'N'}$ or $\text{'G'}$ and $vfobs=True$, the scale parameter, $\varphi$.

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

afloat, optional

If $link=\text{'E'}$, $a$ must contain the power of the exponential.

If $link\ne \text{'E'}$, $a$ is not referenced.

Returns

etafloat, ndarray, shape $\left(n\right)$

The linear predictor, $\eta$.

seetafloat, ndarray, shape $\left(n\right)$

The standard error of the linear predictor, $se\left(\eta \right)$.

predfloat, ndarray, shape $\left(n\right)$

The predicted value, $\hat{y}$.

sepredfloat, ndarray, shape $\left(n\right)$

The standard error of the predicted value, $se\left(\hat{y}\right)$. If $pred[i-1]$ could not be calculated, glm_predict returns $errno$ = 22, and $sepred[i-1]$ is set to $-99.0$.

Raises

NagValueError

(errno $1$)

On entry, $errfn=⟨value⟩$.

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

(errno $2$)

On entry, $link=⟨value⟩$.

Constraint: if $errfn=\text{'B'}$, $link=\text{'C'}$, $\text{'G'}$ or $\text{'P'}$,

otherwise, $link=\text{'E'}$, $\text{'I'}$, $\text{'L'}$, $\text{'R'}$ or $\text{'S'}$.

(errno $2$)

On entry, $errfn=⟨value⟩$ and $link=⟨value⟩$.

Constraint: if $errfn=\text{'B'}$, $link=\text{'C'}$, $\text{'G'}$ or $\text{'P'}$,

otherwise, $link=\text{'E'}$, $\text{'I'}$, $\text{'L'}$, $\text{'R'}$ or $\text{'S'}$.

(errno $3$)

On entry, $mean=⟨value⟩$.

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

(errno $5$)

On entry, $\text{weight}=⟨value⟩$.

Constraint: if $vfobs=True$, $\text{weight}=\text{'U'}$ or $\text{'W'}$.

(errno $6$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $9$)

On entry, $m=⟨value⟩$.

Constraint: $m\ge 1$.

(errno $10$)

On entry, $isx[⟨value⟩]<0$.

Constraint: $isx[j-1]\ge 0.0$, for $j=1,2,\dots ,m$.

(errno $11$)

On entry, $\text{ip}=⟨value⟩$.

Constraint: $\text{ip}>0$.

(errno $12$)

On entry, $t[⟨value⟩]=⟨value⟩$.

Constraint: $t[i-1]\ge 0.0$, for all $i$.

(errno $14$)

On entry, $wt[⟨value⟩]=⟨value⟩$.

Constraint: $wt[i-1]\ge 0.0$, for all $i$.

(errno $15$)

On entry, $s=⟨value⟩$.

Constraint: $s>0.0$.

(errno $16$)

On entry, $a=0.0$.

Constraint: if $link=\text{'E'}$, $a\ne 0.0$.

(errno $18$)

On entry, $cov[⟨value⟩]=⟨value⟩$.

Constraint: $cov\left[i\right]\ge 0.0$ for at least one diagonal element.

Warns

NagAlgorithmicWarning

(errno $22$)

At least one predicted value could not be calculated as required. $sepred$ is set to $-99.0$ for affected predicted values.

Notes

A generalized linear model consists of the following elements:

1. A suitable distribution for the dependent variable $y$.

2. 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. A link function $g(.)$ 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 glm_normal(), glm_binomial(), glm_poisson() or glm_gamma(). The predicted variable, and its standard error can then be obtained from:

$$\hat{y}=g^{-1}\left(\eta \right)\text{,}se\left(\hat{y}\right)=\sqrt{{\left(\frac{\delta g^{-1}\left(x\right)}{\delta x}\right)}_{\eta }}se\left(\eta \right)+I_{fobs}Var\left(y\right)$$

where

$$\eta =o+X\beta \text{,}se\left(\eta \right)=diag\left(\sqrt{XC{X}^T}\right)\text{,}$$

$o$ is a vector of offsets and $I_{fobs}=0$, if the variance of future observations is not taken into account, and $1$ otherwise. Here $diag\left(A\right)$ indicates the diagonal elements of matrix $A$.

If required, the variance for the $i$th future observation, $Var\left(y_i\right)$, can be calculated as:

$$Var\left(y_i\right)=\frac{\varphi V\left(\theta \right)}{w_i}$$

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(t_i-{\mu }_i)}{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 ={\hat{\sigma }}^2$, i.e., the estimated variance.

References

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

See also

naginterfaces.library.examples.correg.glm_binomial_ex.main()