Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_contab_condl_logistic (g11ca)

## Purpose

nag_contab_condl_logistic (g11ca) returns parameter estimates for the conditional logistic analysis of stratified data, for example, data from case-control studies and survival analyses.

## Syntax

[dev, b, se, sc, cov, nca, nct, ifail] = g11ca(ns, z, isz, ic, isi, b, tol, maxit, 'n', n, 'm', m, 'ip', ip, 'iprint', iprint)
[dev, b, se, sc, cov, nca, nct, ifail] = nag_contab_condl_logistic(ns, z, isz, ic, isi, b, tol, maxit, 'n', n, 'm', m, 'ip', ip, 'iprint', iprint)

## Description

In the analysis of binary data, the logistic model is commonly used. This relates the probability of one of the outcomes, say y = 1$y=1$, to p$p$ explanatory variates or covariates by
 Prob(y = 1) = (exp(α + zTβ))/(1 + exp(α + zTβ)), $Prob(y=1)=exp(α+zTβ) 1+exp(α+zTβ) ,$
where β$\beta$ is a vector of unknown coefficients for the covariates z$z$ and α$\alpha$ is a constant term. If the observations come from different strata or groups, α$\alpha$ would vary from strata to strata. If the observed outcomes are independent then the y$y$s follow a Bernoulli distribution, i.e., a binomial distribution with sample size one and the model can be fitted as a generalized linear model with binomial errors.
In some situations the number of observations for which y = 1$y=1$ may not be independent. For example, in epidemiological research, case-control studies are widely used in which one or more observed cases are matched with one or more controls. The matching is based on fixed characteristics such as age and sex, and is designed to eliminate the effect of such characteristics in order to more accurately determine the effect of other variables. Each case-control group can be considered as a stratum. In this type of study the binomial model is not appropriate, except if the strata are large, and a conditional logistic model is used. This considers the probability of the cases having the observed vectors of covariates given the set of vectors of covariates in the strata. In the situation of one case per stratum, the conditional likelihood for ns${n}_{\mathrm{s}}$ strata can be written as
 ns L = ∏ (exp(ziTβ))/([∑l ∈ Siexp(zlTβ)]), i = 1
$L=∏i=1nsexp(ziTβ) [∑l∈Siexp(zlTβ)] ,$
(1)
where Si${S}_{i}$ is the set of observations in the i$i$th stratum, with associated vectors of covariates zl${z}_{l}$, lSi$l\in {S}_{i}$, and zi${z}_{i}$ is the vector of covariates of the case in the i$i$th stratum. In the general case of ci${c}_{i}$ cases per strata then the full conditional likelihood is
 ns L = ∏ (exp(siTβ))/([∑l ∈ Ciexp(slTβ)]), i = 1
$L=∏i=1nsexp(siTβ) [∑l∈Ciexp(slTβ)] ,$
(2)
where si${s}_{i}$ is the sum of the vectors of covariates for the cases in the i$i$th stratum and sl${s}_{l}$, lCi$l\in {C}_{i}$ refer to the sum of vectors of covariates for all distinct sets of ci${c}_{i}$ observations drawn from the i$i$th stratum. The conditional likelihood can be maximized by a Newton–Raphson procedure. The covariances of the parameter estimates can be estimated from the inverse of the matrix of second derivatives of the logarithm of the conditional likelihood, while the first derivatives provide the score function, Uj(β)${U}_{\mathit{j}}\left(\beta \right)$, for j = 1,2,,p$\mathit{j}=1,2,\dots ,p$, which can be used for testing the significance of parameters.
If the strata are not small, Ci${C}_{i}$ can be large so to improve the speed of computation, the algorithm in Howard (1972) and described by Krailo and Pike (1984) is used.
A second situation in which the above conditional likelihood arises is in fitting Cox's proportional hazard model (see nag_surviv_coxmodel (g12ba)) in which the strata refer to the risk sets for each failure time and where the failures are cases. When ties are present in the data nag_surviv_coxmodel (g12ba) uses an approximation. For an exact estimate, the data can be expanded using nag_surviv_coxmodel_risksets (g12za) to create the risk sets/strata and nag_contab_condl_logistic (g11ca) used.

## References

Cox D R (1972) Regression models in life tables (with discussion) J. Roy. Statist. Soc. Ser. B 34 187–220
Cox D R and Hinkley D V (1974) Theoretical Statistics Chapman and Hall
Howard S (1972) Remark on the paper by Cox, D R (1972): Regression methods J. R. Statist. Soc. B 34 and life tables 187–220
Krailo M D and Pike M C (1984) Algorithm AS 196. Conditional multivariate logistic analysis of stratified case-control studies Appl. Statist. 33 95–103
Smith P G, Pike M C, Hill P, Breslow N E and Day N E (1981) Algorithm AS 162. Multivariate conditional logistic analysis of stratum-matched case-control studies Appl. Statist. 30 190–197

## Parameters

### Compulsory Input Parameters

1:     ns – int64int32nag_int scalar
The number of strata, ns${n}_{s}$.
Constraint: ns1${\mathbf{ns}}\ge 1$.
2:     z(ldz,m) – double array
ldz, the first dimension of the array, must satisfy the constraint ldzn$\mathit{ldz}\ge {\mathbf{n}}$.
The i$i$th row must contain the covariates which are associated with the i$i$th observation.
3:     isz(m) – int64int32nag_int array
m, the dimension of the array, must satisfy the constraint m1${\mathbf{m}}\ge 1$.
Indicates which subset of covariates are to be included in the model.
If isz(j)1${\mathbf{isz}}\left(j\right)\ge 1$, the j$j$th covariate is included in the model.
If isz(j) = 0${\mathbf{isz}}\left(j\right)=0$, the j$j$th covariate is excluded from the model and not referenced.
Constraint: isz(j)0${\mathbf{isz}}\left(j\right)\ge 0$ and at least one value must be nonzero.
4:     ic(n) – int64int32nag_int array
n, the dimension of the array, must satisfy the constraint n2${\mathbf{n}}\ge 2$.
Indicates whether the i$i$th observation is a case or a control.
If ic(i) = 0${\mathbf{ic}}\left(i\right)=0$, indicates that the i$i$th observation is a case.
If ic(i) = 1${\mathbf{ic}}\left(i\right)=1$, indicates that the i$i$th observation is a control.
Constraint: ic(i) = 0${\mathbf{ic}}\left(\mathit{i}\right)=0$ or 1$1$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
5:     isi(n) – int64int32nag_int array
n, the dimension of the array, must satisfy the constraint n2${\mathbf{n}}\ge 2$.
Stratum indicators which also allow data points to be excluded from the analysis.
If isi(i) = k${\mathbf{isi}}\left(i\right)=k$, indicates that the i$i$th observation is from the k$k$th stratum, where k = 1,2,,ns$k=1,2,\dots ,{\mathbf{ns}}$.
If isi(i) = 0${\mathbf{isi}}\left(i\right)=0$, indicates that the i$i$th observation is to be omitted from the analysis.
Constraint: 0isi(i)ns$0\le {\mathbf{isi}}\left(\mathit{i}\right)\le {\mathbf{ns}}$ and more than ip values of isi(i) > 0${\mathbf{isi}}\left(\mathit{i}\right)>0$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
6:     b(ip) – double array
ip, the dimension of the array, must satisfy the constraint ip1${\mathbf{ip}}\ge 1$ and ip = ${\mathbf{ip}}=\text{}$ number of nonzero values of isz .
Initial estimates of the covariate coefficient parameters β$\beta$. b(j)${\mathbf{b}}\left(j\right)$ must contain the initial estimate of the coefficent of the covariate in z corresponding to the j$j$th nonzero value of isz.
7:     tol – double scalar
Indicates the accuracy required for the estimation. Convergence is assumed when the decrease in deviance is less than tol × (1.0 + CurrentDeviance)${\mathbf{tol}}×\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: tol10 × machine precision.
8:     maxit – int64int32nag_int scalar
The maximum number of iterations required for computing the estimates. If maxit is set to 0$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: maxit0${\mathbf{maxit}}\ge 0$.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the arrays ic, isi and the first dimension of the array z. (An error is raised if these dimensions are not equal.)
n$n$, the number of observations.
Constraint: n2${\mathbf{n}}\ge 2$.
2:     m – int64int32nag_int scalar
Default: The dimension of the array isz and the second dimension of the array z. (An error is raised if these dimensions are not equal.)
The number of covariates in array z.
Constraint: m1${\mathbf{m}}\ge 1$.
3:     ip – int64int32nag_int scalar
Default: The dimension of the array b.
p$p$, the number of covariates included in the model as indicated by isz.
Constraint: ip1${\mathbf{ip}}\ge 1$ and ip = ${\mathbf{ip}}=\text{}$ number of nonzero values of isz .
4:     iprint – int64int32nag_int scalar
Indicates if the printing of information on the iterations is required.
iprint0${\mathbf{iprint}}\le 0$
No printing.
iprint1${\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 nag_file_set_unit_advisory (x04ab)).
Default: 0$0$

ldz wk lwk

### Output Parameters

1:     dev – double scalar
The deviance, that is, 2 × $-2×\text{}$, (maximized log marginal likelihood).
2:     b(ip) – double array
b(j)${\mathbf{b}}\left(j\right)$ contains the estimate β̂i${\stackrel{^}{\beta }}_{i}$ of the coefficient of the covariate stored in the i$i$th column of z where i$i$ is the j$j$th nonzero value in the array isz.
3:     se(ip) – double array
se(j)${\mathbf{se}}\left(\mathit{j}\right)$ is the asymptotic standard error of the estimate contained in b(j)${\mathbf{b}}\left(\mathit{j}\right)$ and score function in sc(j)${\mathbf{sc}}\left(\mathit{j}\right)$, for j = 1,2,,ip$\mathit{j}=1,2,\dots ,{\mathbf{ip}}$.
4:     sc(ip) – double array
sc(j)${\mathbf{sc}}\left(j\right)$ is the value of the score function Uj(β)${U}_{j}\left(\beta \right)$ for the estimate contained in b(j)${\mathbf{b}}\left(j\right)$.
5:     cov(ip × (ip + 1) / 2${\mathbf{ip}}×\left({\mathbf{ip}}+1\right)/2$) – double array
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 b(i)${\mathbf{b}}\left(i\right)$ and b(j)${\mathbf{b}}\left(j\right)$, ji$j\ge i$, is given in cov(j(j1) / 2 + i)${\mathbf{cov}}\left(j\left(j-1\right)/2+i\right)$.
6:     nca(ns) – int64int32nag_int array
nca(i)${\mathbf{nca}}\left(\mathit{i}\right)$ contains the number of cases in the i$\mathit{i}$th stratum, for i = 1,2,,ns$\mathit{i}=1,2,\dots ,{\mathbf{ns}}$.
7:     nct(ns) – int64int32nag_int array
nct(i)${\mathbf{nct}}\left(\mathit{i}\right)$ contains the number of controls in the i$\mathit{i}$th stratum, for i = 1,2,,ns$\mathit{i}=1,2,\dots ,{\mathbf{ns}}$.
8:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

ifail = 1${\mathbf{ifail}}=1$
 On entry, m < 1${\mathbf{m}}<1$, or n < 2${\mathbf{n}}<2$, or ns < 1${\mathbf{ns}}<1$, or ip < 1${\mathbf{ip}}<1$, or ldz < n$\mathit{ldz}<{\mathbf{n}}$, or tol < 10 × machine precision, or maxit < 0${\mathbf{maxit}}<0$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, isz(i) < 0${\mathbf{isz}}\left(i\right)<0$, for some i$i$, or the value of ip is incompatible with isz, or ic(i) ≠ 1${\mathbf{ic}}\left(i\right)\ne 1$ or 0$0$. or isi(i) < 0${\mathbf{isi}}\left(i\right)<0$ or isi(i) > ns${\mathbf{isi}}\left(i\right)>{\mathbf{ns}}$, or the number of values of isz(i) > 0${\mathbf{isz}}\left(i\right)>0$ is greater than or equal to n0${n}_{0}$, the number of observations excluding any with isi(i) = 0${\mathbf{isi}}\left(i\right)=0$.
ifail = 3${\mathbf{ifail}}=3$
The value of lwk is too small.
ifail = 4${\mathbf{ifail}}=4$
Overflow has been detected. Try using different starting values.
ifail = 5${\mathbf{ifail}}=5$
The matrix of second partial derivatives is singular. Try different starting values or include fewer covariates.
W ifail = 6${\mathbf{ifail}}=6$
Convergence has not been achieved in maxit 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.

## Accuracy

The accuracy is specified by tol.

The other models described in Section [Description] can be fitted using the generalized linear modelling functions nag_correg_glm_binomial (g02gb) and nag_correg_glm_poisson (g02gc).
The case with one case per stratum can be analysed by having a dummy response variable y$y$ such that y = 1$y=1$ for a case and y = 0$y=0$ for a control, and fitting a Poisson generalized linear model with a log link and including a factor with a level for each strata. These models can be fitted by using nag_correg_glm_poisson (g02gc).
nag_contab_condl_logistic (g11ca) uses mean centering, which involves subtracting the means from the covariables prior to computation of any statistics. This helps to minimize the effect of outlying observations and accelerates convergence. In order to reduce the risk of the sums computed by Howard's algorithm becoming too large, the scaling factor described in Krailo and Pike (1984) is used.
If the initial estimates are poor then there may be a problem with overflow in calculating exp(βTzi)$\mathrm{exp}\left({\beta }^{\mathrm{T}}{z}_{i}\right)$ or there may be non-convergence. Reasonable estimates can often be obtained by fitting an unconditional model.

## Example

```function nag_contab_condl_logistic_example
ns = int64(2);
z = [0, 1;
1, 2;
0, 1;
1, 3;
0, 1;
1, 0;
0, 2];
isz = [int64(1);1];
ic = [int64(0);0;1;1;0;1;1];
isi = [int64(1);1;1;1;2;2;2];
b = [0;
0];
tol = 1e-05;
maxit = int64(10);
[dev, bOut, se, sc, covar, nca, nct, ifail] = ...
nag_contab_condl_logistic(ns, z, isz, ic, isi, b, tol, maxit)
```
```

dev =

5.4749

bOut =

-0.5223
-0.2674

se =

1.3901
0.8473

sc =

1.0e-05 *

-0.4794
-0.7901

covar =

1.9325
-0.2317
0.7180

nca =

2
1

nct =

2
2

ifail =

0

```
```function g11ca_example
ns = int64(2);
z = [0, 1;
1, 2;
0, 1;
1, 3;
0, 1;
1, 0;
0, 2];
isz = [int64(1);1];
ic = [int64(0);0;1;1;0;1;1];
isi = [int64(1);1;1;1;2;2;2];
b = [0;
0];
tol = 1e-05;
maxit = int64(10);
[dev, bOut, se, sc, covar, nca, nct, ifail] = g11ca(ns, z, isz, ic, isi, b, tol, maxit)
```
```

dev =

5.4749

bOut =

-0.5223
-0.2674

se =

1.3901
0.8473

sc =

1.0e-05 *

-0.4794
-0.7901

covar =

1.9325
-0.2317
0.7180

nca =

2
1

nct =

2
2

ifail =

0

```