NAG Library Routine Document

g11caf (condl_logistic)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:     $\mathbf{n}$ – IntegerInput

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

Constraint: $\mathbf{n}\ge 2$.

2:     $\mathbf{m}$ – IntegerInput

On entry: the number of covariates in array z.

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

3:     $\mathbf{ns}$ – IntegerInput

On entry: the number of strata, $n_s$.

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

4:     $\mathbf{z}\left(\mathbf{ldz},\mathbf{m}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the $i$th row must contain the covariates which are associated with the $i$th observation.

5:     $\mathbf{ldz}$ – IntegerInput

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

Constraint: $\mathbf{ldz}\ge \mathbf{n}$.

6:     $\mathbf{isz}\left(\mathbf{m}\right)$ – Integer arrayInput

On entry: indicates which subset of covariates are to be included in the model.

If $\mathbf{isz}\left(j\right)\ge 1$, the $j$th covariate is included in the model.

If $\mathbf{isz}\left(j\right)=0$, the $j$th covariate is excluded from the model and not referenced.

Constraint: $\mathbf{isz}\left(j\right)\ge 0$ and at least one value must be nonzero.

7:     $\mathbf{ip}$ – IntegerInput

On entry: $p$, the number of covariates included in the model as indicated by isz.

Constraint: $\mathbf{ip}\ge 1$ and $\mathbf{ip}=$ number of nonzero values of isz.

8:     $\mathbf{ic}\left(\mathbf{n}\right)$ – Integer arrayInput

On entry: indicates whether the $i$th observation is a case or a control.

If $\mathbf{ic}\left(i\right)=0$, indicates that the $i$th observation is a case.

If $\mathbf{ic}\left(i\right)=1$, indicates that the $i$th observation is a control.

Constraint: $\mathbf{ic}\left(\mathit{i}\right)=0$ or $1$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$.

9:     $\mathbf{isi}\left(\mathbf{n}\right)$ – Integer arrayInput

On entry: stratum indicators which also allow data points to be excluded from the analysis.

If $\mathbf{isi}\left(i\right)=k$, indicates that the $i$th observation is from the $k$th stratum, where $k=1,2,\dots ,\mathbf{ns}$.

If $\mathbf{isi}\left(i\right)=0$, indicates that the $i$th observation is to be omitted from the analysis.

Constraint: $0\le \mathbf{isi}\left(\mathit{i}\right)\le \mathbf{ns}$ and more than ip values of $\mathbf{isi}\left(\mathit{i}\right)>0$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$.

10:   $\mathbf{dev}$ – Real (Kind=nag_wp)Output

On exit: the deviance, that is, minus twice the maximized log-likelihood.

11:   $\mathbf{b}\left(\mathbf{ip}\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: initial estimates of the covariate coefficient parameters $\beta$. $\mathbf{b}\left(j\right)$ must contain the initial estimate of the coefficent of the covariate in z corresponding to the $j$th nonzero value of isz.

Suggested value: in many cases an initial value of zero for $\mathbf{b}\left(j\right)$ may be used. For another suggestion see Section 9.

On exit: $\mathbf{b}\left(j\right)$ contains the estimate ${\hat{\beta }}_i$ of the coefficient of the covariate stored in the $i$th column of z where $i$ is the $j$th nonzero value in the array isz.

12:   $\mathbf{se}\left(\mathbf{ip}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: $\mathbf{se}\left(\mathit{j}\right)$ is the asymptotic standard error of the estimate contained in $\mathbf{b}\left(\mathit{j}\right)$ and score function in $\mathbf{sc}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{ip}$.

13:   $\mathbf{sc}\left(\mathbf{ip}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: $\mathbf{sc}\left(j\right)$ is the value of the score function $U_j\left(\beta \right)$ for the estimate contained in $\mathbf{b}\left(j\right)$.

14:   $\mathbf{cov}\left(\mathbf{ip}\times \left(\mathbf{ip}+1\right)/2\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: the variance-covariance matrix of the parameter estimates in b stored in packed form by column, i.e., the covariance between the parameter estimates given in $\mathbf{b}\left(i\right)$ and $\mathbf{b}\left(j\right)$, $j\ge i$, is given in $\mathbf{cov}\left(j\left(j-1\right)/2+i\right)$.

15:   $\mathbf{nca}\left(\mathbf{ns}\right)$ – Integer arrayOutput

On exit: $\mathbf{nca}\left(\mathit{i}\right)$ contains the number of cases in the $\mathit{i}$th stratum, for $\mathit{i}=1,2,\dots ,\mathbf{ns}$.

16:   $\mathbf{nct}\left(\mathbf{ns}\right)$ – Integer arrayOutput

On exit: $\mathbf{nct}\left(\mathit{i}\right)$ contains the number of controls in the $\mathit{i}$th stratum, for $\mathit{i}=1,2,\dots ,\mathbf{ns}$.

17:   $\mathbf{tol}$ – Real (Kind=nag_wp)Input

On entry: indicates the accuracy required for the estimation. Convergence is assumed when the decrease in deviance is less than $\mathbf{tol}\times \left(1.0+\mathrm{CurrentDeviance}\right)$. This corresponds approximately to an absolute accuracy if the deviance is small and a relative accuracy if the deviance is large.

Constraint: $\mathbf{tol}\ge 10\times \mathit{machine precision}$.

18:   $\mathbf{maxit}$ – IntegerInput

On entry: the maximum number of iterations required for computing the estimates. If maxit is set to $0$ then the standard errors, the score functions and the variance-covariance matrix are computed for the input value of $\beta$ in b but $\beta$ is not updated.

Constraint: $\mathbf{maxit}\ge 0$.

19:   $\mathbf{iprint}$ – IntegerInput

On entry: indicates if the printing of information on the iterations is required.

$\mathbf{iprint}\le 0$

No printing.

$\mathbf{iprint}\ge 1$

The deviance and the current estimates are printed every iprint iterations. When printing occurs the output is directed to the current advisory message unit (see x04abf).

Suggested value: $\mathbf{iprint}=0$.

20:   $\mathbf{wk}\left(\mathbf{lwk}\right)$ – Real (Kind=nag_wp) arrayWorkspace

21:   $\mathbf{lwk}$ – IntegerInput

On entry: the dimension of the array wk as declared in the (sub)program from which g11caf is called.

Constraint: $\mathbf{lwk}\ge p{n}_0+\left(c_{\mathrm{m}}+1\right)\left(p+1\right)\left(p+2\right)/2+c_{\mathrm{m}}$, where $n_0$ is the number of observations included in the model, i.e., the number of observations for which $\mathbf{isi}\left(i\right)\ne 0$ and $c_{\mathrm{m}}$ is the maximum number of observations in any stratum.

22:   $\mathbf{ifail}$ – IntegerInput/Output

On entry: ifail must be set to $0$, $-1\text{ 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\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is $0$. When the value $-\mathbf{1}\text{ or }\mathbf{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{ip}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ip}\ge 1$.

On entry, $\mathbf{ldz}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ldz}\ge \mathbf{n}$.

On entry, $\mathbf{m}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{m}\ge 1$.

On entry, $\mathbf{maxit}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{maxit}\ge 0$.

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}\ge 2$.

On entry, $\mathbf{ns}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ns}\ge 1$.

On entry, $\mathbf{tol}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{tol}\ge 10\times \mathit{machine precision}$.

$\mathbf{ifail}=2$

On entry, $i=〈\mathit{\text{value}}〉$, $\mathbf{isi}\left(i\right)=〈\mathit{\text{value}}〉$ and $\mathbf{ns}=〈\mathit{\text{value}}〉$.
Constraint: $0\le \mathbf{isi}\left(i\right)\le \mathbf{ns}$.

On entry, $i=〈\mathit{\text{value}}〉$ and $\mathbf{ic}\left(i\right)=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ic}\left(i\right)=0$ or $1$.

On entry, $i=〈\mathit{\text{value}}〉$ and $\mathbf{isz}\left(i\right)<〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{isz}\left(i\right)\ge 0$.

On entry, there are not ip values of $\mathbf{isz}>0$.

On entry, too few observations included in model.

$\mathbf{ifail}=3$

On entry, lwk is too small, $\mathbf{lwk}=〈\mathit{\text{value}}〉$ minimum value $=〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=4$

Overflow in calculations. Try using different starting values.

$\mathbf{ifail}=5$

The matrix of second partial derivatives is singular. Try different starting values or include fewer covariates.

$\mathbf{ifail}=6$

Convergence not achieved in $〈\mathit{\text{value}}〉$ iterations. The progress towards convergence can be examined by using a nonzero value of iprint. Any non-convergence may be due to a linear combination of covariates being monotonic with time. Full results are returned.

$\mathbf{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.

$\mathbf{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.

$\mathbf{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

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (g11cafe.f90)

10.2

Program Data

Program Data (g11cafe.d)

10.3

Program Results

Program Results (g11cafe.r)