nagdmc binomial reg

NAG DMC

Binomial Regression: nagdmc binomial reg
Purposenagdmc binomial reg computes a regression model with p parameters, binomial errors and either alogit, probit or complimentary log-log link function.

Declaration#include <nagdmc.h>void nagdmc binomial reg(long rec1, long nvar, long nrec, long dblk, double data[],void (*dfun)(long, long, double [], char *, int *),char *comm, long chunksize, long nxvar, long xvar[],long yvar, double ycut, long bdvar, long iwts, long ioff,char link, double *dev, long *df, double b[], double se[],double cov[], double model[], double scale, double tol,double eps, long maxit, int *info);

Parameters1:

rec1 – long

Input

On entry: the index in the data of the first data record used in the analysis.
Constraint: rec1 ≥ 0.
2:

nvar – long

Input

On entry: the number of variables in the data.
Constraint: nvar > 1.
3:

nrec – long

Input

On entry: the number of consecutive records, beginning at rec1, used in the analysis.
Constraint: nrec > 1.
4:

dblk – long

Input

On entry: the total number of records in the data block.
Constraint: dblk ≥ rec1 + nrec.
5:

data[dblk ∗ nvar] – double

Input

On entry: the data values for the jth variable (for j = 0, 1, . . . , nvar−1) are stored in data[i∗nvar+j],
for i = 0, 1, . . . , dblk − 1. When the data function is used, data is not referenced.
6:

dfun – function supplied by user

External Procedure

On entry: the pointer to a data function supplied by the user.
Constraint: if dfun is a valid pointer, data must be 0.
The specification of dfun is:void dfun(long irec, long chunksize, double x[], char *comm, int *ierr)1:

irec – longOn entry: the index in the data of the first record returned.

Input

2:

chunksize – long
On entry: the number of consecutive records returned.

Input

3:

x[chunksize∗nvar] – double
OutputOn exit: data values for the jth variable (for j = 0, 1, . . . , nvar − 1) must be returned
in x[i ∗ nvar + j], for i = 0, 1, . . . , chunksize − 1.

nagdmc binomial reg.1

NAG DMC

nagdmc binomial reg

4:comm – char *Input
On entry: a communication parameter allowing additional information to be passed
to dfun. This parameter is passed ‘as is’ through the calling function.

5:

ierr – int *OutputOn exit: if the value pointed to by ierr on return is greater than 100, the NAG DMC
function will terminate immediately and info will point to this value.

7:

comm – char *Input
On entry: a communication parameter allowing additional information to be passed to dfun. Thisparameter is passed ‘as is’ through the calling function.

8:

chunksize – long
Input
On entry: if the data function is used, the function inputs no more than chunksize data records ata time; otherwise chunksize is not referenced.
Constraint: if dfun 6= 0, chunksize ≥ 1.

9:nxvar – long
Input
On entry: the number of independent variables. If nxvar = 0 then all variables in the data,excluding yvar and (if defined in the data) bdvar, iwts and ioff, are treated as independent variables.
Constraint: 0 ≤ nxvar < nvar.

10:

xvar[nxvar] – long
Input
On entry: the indices indicating the position in data in which values of the independent variables
are stored. If nxvar = 0 then xvar must be 0, and the indices of independent variables are given by
j = 0, 1, . . . , nvar − 1; j 6= yvar and j 6= bdvar, iwts or ioff.
Constraints: if nxvar > 0, 0 ≤ xvar[i] < nvar, for i = 0, 1, . . . , nxvar − 1; otherwise xvar must be0.

11:

yvar – long
On entry: the index in data in which values of the dependent variable are stored.
Constraints: 0 ≤ yvar < nvar; if nxvar > 0, yvar 6= xvar[i], for i = 0, 1, . . . , nxvar − 1.

12:ycut – long
Input
On entry: if ycut 6= 0, the y-variable is transformed so that values < ycut are set to zero and values≥ ycut are set to one.

13:

bdvar – long
Input
On entry: an index indicating the position in data in which the binomial denominator is stored. Ifbdvar = −1 a default value of one is used for all observations.
Constraint: −1 ≤ bdvar < nvar.

14:

iwts – long
Input
On entry: if iwts = −1, no weights are used; otherwise iwts is the index in data in which theweights are stored.
Constraints: −1 ≤ iwts < nvar; iwts 6= yvar; and if nxvar > 0, iwts 6= xvar[i], fori = 0, 1, . . . , nxvar − 1.

15:

ioff – long
Input
On entry: the index in data in which the offset values are stored. If ioff = −1, no offsets are used.
Constraint: ioff < nvar.

16:link – char
On entry: indicates which link function to use. Values of link can be upper or lower case.
‘G’ : Logit link function.
‘P’ : Probit link function.
‘C’ : Complimentary log-log link function.
Constraint: link = ‘G’, ‘g’, ‘P’, ‘p’, ‘C’ or ‘c’.

Input

Input

nagdmc binomial reg.2

NAG DMC

nagdmc binomial reg

17:

dev – double
On exit: the deviance from the fitted model.

Output18:

df – long *On exit: the degrees of freedom for the deviance.

Output19:b[p] – double
OutputOn exit: the parameter estimates. b[0] is the mean parameter. b[i] is the coefficient of the ith
variable included in the model, for i = 1, 2, . . . , p − 1. If nxvar > 0 then the order the independent
variables are added to the model is defined by xvar, otherwise the order is defined by indices in thedata.

20:

se[p] – double
On exit: the standard errors of the parameters in b.

21:

cov[p ∗ (p + 1)/2] – double
OutputOn exit: the first p ∗ (p + 1)/2 elements of cov contain the upper triangular part of the variancecovariance matrix of the p parameters in b. They are stored packed by column, i.e., the covariance
between the parameter estimate given in b[i] and the parameter estimate given in b[j], j ≥ i, isstored in cov[j(j + 1)/2 + i], for i = 0, 1, . . . , p − 1 and j = i, i + 1, . . . , p − 1.

22:

model[(3 ∗ p ∗ (p + 1))/2 + nvar + 14] – double
OutputOn exit: if not 0, information on the fitted model for use in the functions described in ‘See Also’.

23:

scale – double
InputOn entry: the scale parameter used to scale the standard errors of the parameter estimates. If
scale = 0.0, a default value of 1.0 is used.
Constraint: scale ≥ 0.0.

24:

tol – double
Input
On entry: the convergence tolerance for the training. If tol is equal to 0.0, a default value of 0.00001
is used.
Constraint: tol ≥ 0.0.

25:

eps – double
Input
On entry: the value of the criterion used for model pruning. If eps = 0.0, a default value of 1e−10
is used.
Constraint: eps ≥ 0.0.

26:

maxit – long
Input
On entry: the maximum number of iterations (passes through the data) to be used in training. Ifmaxit = 0, a default value of 10 is used.
Constraint: maxit ≥ 0.

27:

info – int *On exit: info gives information on the success of the function call:

OutputOutput−4: a model value has reached a boundary.
0: the function successfully completed its task.
i; i = 1, 2, . . . , 6, 8, 9, . . . , 16, 23, 24, 25, 26: the specification of the ith formal parameter wasincorrect.
41: invalid value for a weight.
42: invalid value for response variable.
43: invalid value for binomial denominator.
45: model has not converged.
57: there are no degrees of freedom for the error estimates.
58: the fit is exact, no error estimates.
59: more variables than observations.
98: there is an underlying computational problem (this is an unlikely error exit).
99: the function failed to allocate enough memory.
> 100: an error occurred in a function specified by the user.

nagdmc binomial reg.3

nagdmc binomial reg

NAG DMCNotation
nrecnxvar
xvar
yvar
bdvar
iwts
iofflinkb

the number of observations, n.
the number of independent variables, p − 1.
the independent variables, X, excluding the mean.
the dependent variable, y.
if bdvar ≥ 0, bdvar is the index in the data that defines the binomial denominator, t.
if iwts ≥ 0, iwts is the index in the data that defines the weights, W .
if ioff ≥ 0, ioff is the index in the data that defines the offset, o.
character flag indicating which link function g(.) to use.
the parameter estimates, β̂.

Description
nagdmc binomial reg fits a generalized linear model with binomial errors. The model consists ofthe following elements.
(a) A set of n observations, yi , from a binomial distribution!
tπ y (1 − π)t−y .
y(b) X, an n by p matrix of independent variables, In most linear regression models the firstterm is taken as a mean term or an intercept, i.e., Xi,1 = 1, for i = 1, 2, . . . , n; this is
assumed in NAG DMC.
(c) A linear model:Xη=βj xj .
(d) A link function η = g(µ), linking the linear predictor, η, and the mean of the distribution,µ = πt. The possible link functions areµ,(i) logistic link: η = log
µt −µ,(ii) probit link: η = Φ−1tµ(iii) complementary log-log link: η = log − log 1 −.
t(e) A measure of fit, the deviance:!
!#"nnXX(ti − yi )yi+ (ti − yi ) log.
dev(yi , µ̂i ) =2 yi logµ̂i(ti − µ̂i )i=1i=1The linear parameters are estimated by iterative weighted least squares. An adjusted dependent
variable, z, is formed,z = η + (y − µ)dη,dµand a working weight, w,w=dητdµ!2swhere τ =t.
µ(t − µ)At each iteration an approximation to the estimate of β, β̂, is found by the weighted least squares
regression of z on X with weights w.

nagdmc binomial reg.4

nagdmc binomial reg

NAG DMC
1

NAG DMC uses a QR decomposition of w 2 X, i.e.,
1w 2 X = QR,
where R is a p by p triangular matrix and Q is an n by p column orthogonal matrix. If R is of fullrank then β̂ is the solution to1Rβ̂ = QT w 2 z.
If R is not of full rank a solution is obtained by means of a singular value decomposition (SVD) ofR.
!
D 0
R = Q∗
PT,0 0where D is a k by k diagonal matrix with non-zero diagonal elements, k being the rank of R and
1w 2 X. This gives the solution!
10−1 Q∗β̂ = P1 D
QT w 2 z,0I
P1 being the first k columns of P , i.e., P = (P1 P0 ).
The iterations are continued until there is only a small change in the deviance.
The initial values for the algorithm are obtained by taking
η̂ = g(y).
The fit of the model can be assessed by examining and testing the deviance, in particular, bycomparing the difference in deviance between nested models, i.e., when one model is a sub-modelof the other. The difference in deviance between two nested models has, asymptotically, a χ2
distribution with degrees of freedom given by the difference in the degrees of freedom associatedwith the two deviances.
The parameter estimates, β̂, are asymptotically Normally distributed with variance-covariancematrix:T

C = R−1 R−1
C = P1 D−2 P1T .

in the full rank case, otherwise

The residuals and influence statistics can also be examined.
1

The estimated linear predictor η̂ = X β̂ can be written as Hw 2 z for an n by n matrix H. The ith
diagonal elements of H, hi , give a measure of the influence of the ith values of the independent
variables on the fitted regression model. These are known as leverages.
The fitted values are given by µ̂ = g −1 (η̂) and the deviance residuals by r:
qri = sign(yi − µ̂i ) dev(yi , µ̂i ).
An option allows prior weights, W , to be used with the model.
If part of the linear predictor can be represented by a variable with a known coefficient then thiscan be included in the model by using an offset, o:η =o+Xβj xj .

If the model is not of full rank the solution given will be only one of the possible solutions but all
solutions will give the same predicted values.

nagdmc binomial reg.5

nagdmc binomial reg

NAG DMC

References and Further Reading
Cook R D and Weisberg S (1982) Residuals and Influence in Regression Chapman and Hall.
Cox D R (1983) Analysis of Binary Data Chapman and Hall.
McCullagh P and Nelder J A (1983) Generalized Linear Models Chapman and Hall.

See Also
nagdmc extr reg
nagdmc logit reg
nagdmc predict reg
nagdmc probit reg
nagdmc predict reg
binomial reg ex.ccomputes fitted values, residuals and leverages for a regression.
simplified version of nagdmc binomial reg using a logit link and arestricted set of parameters.
computes predictions given a fitted regression model.
simplified version of nagdmc binomial reg using a probit link and a
restricted set of parameters.
computes predictions given a fitted regression model.
the example calling program.

nagdmc binomial reg.6