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

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_surviv_logrank (g12ab)

## Purpose

nag_surviv_logrank (g12ab) calculates the rank statistics, which can include the logrank test, for comparing survival curves.

## Syntax

[ts, df, p, obsd, expt, nd, di, ni, ifail] = g12ab(t, ic, grp, ngrp, freq, weight, 'n', n, 'ifreq', ifreq, 'wt', wt, 'ldn', ldn)
[ts, df, p, obsd, expt, nd, di, ni, ifail] = nag_surviv_logrank(t, ic, grp, ngrp, freq, weight, 'n', n, 'ifreq', ifreq, 'wt', wt, 'ldn', ldn)

## Description

A survivor function, S(t)$S\left(t\right)$, is the probability of surviving to at least time t$t$. Given a series of n$n$ failure or right-censored times from g$g$ groups nag_surviv_logrank (g12ab) calculates a rank statistic for testing the null hypothesis
• H0 : S1 (t) = S2 (t) = = Sg (t) , t τ ${H}_{0}:{S}_{1}\left(t\right)={S}_{2}\left(t\right)=\cdots ={S}_{g}\left(t\right),\forall t\le \tau$
where τ$\tau$ is the largest observed time, against the alternative hypothesis
• H1 : ${H}_{1}:$ at least one of the Si (t) ${S}_{i}\left(t\right)$ differ, for some t τ $t\le \tau$.
Let t i ${t}_{\mathit{i}}$, for i = 1,2,,nd$\mathit{i}=1,2,\dots ,{n}_{d}$, denote the list of distinct failure times across all g$g$ groups and wi${w}_{i}$ a series of nd${n}_{d}$ weights. Let dij${d}_{ij}$ denote the number of failures at time ti${t}_{i}$ in group j$j$ and nij${n}_{ij}$ denote the number of observations in the group j$j$ that are known to have not failed prior to time ti${t}_{i}$, i.e., the size of the risk set for group j$j$ at time ti${t}_{i}$. If a censored observation occurs at time ti${t}_{i}$ then that observation is treated as if the censoring had occurred slightly after ti${t}_{i}$ and therefore the observation is counted as being part of the risk set at time ti${t}_{i}$. Finally let
 g g di = ∑ dij   and  ni = ∑ nij . j = 1 j = 1
$di = ∑ j=1 g d ij and ni = ∑ j=1 g n ij .$
The (weighted) number of observed failures in the j$j$th group, Oj${O}_{j}$, is therefore given by
 nd Oj = ∑ wi dij i = 1
$Oj = ∑ i=1 nd wi d ij$
and the (weighted) number of expected failures in the j$j$th group, Ej${E}_{j}$, by
 nd Ej = ∑ wi ( nij di )/(ni) . i = 1
$Ej = ∑ i=1 nd wi n ij di ni .$
If x$x$ denotes the vector of differences x = (O1E1,O2E2,,OgEg) $x=\left({O}_{1}-{E}_{1},{O}_{2}-{E}_{2},\dots ,{O}_{g}-{E}_{g}\right)$ and
 nd Vjk = ∑ wi2 (( di (ni − di) (nin i k Ijk − nijnik) )/( ni2 (ni − 1) )) i = 1
$V jk = ∑ i=1 nd w i 2 ( di ( ni - di ) ( ni n i k I jk - n ij n ik ) n i 2 ( ni - 1 ) )$
where Ijk = 1 ${I}_{jk}=1$ if j = k$j=k$ and 0$0$ otherwise, then the rank statistic, T$T$, is calculated as
 T = x V− xT $T = x V- xT$
where V${V}^{-}$ denotes a generalized inverse of the matrix V$V$. Under the null hypothesis, T χν2 $T\sim {\chi }_{\nu }^{2}$ where the degrees of freedom, ν$\nu$, is taken as the rank of the matrix V$V$.

## References

Gross A J and Clark V A (1975) Survival Distributions: Reliability Applications in the Biomedical Sciences Wiley
Kalbfleisch J D and Prentice R L (1980) The Statistical Analysis of Failure Time Data Wiley
Rostomily R C, Duong D, McCormick K, Bland M and Berger M S (1994) Multimodality management of recurrent adult malignant gliomas: results of a phase II multiagent chemotherapy study and analysis of cytoreductive surgery Neurosurgery 35 378

## Parameters

### Compulsory Input Parameters

1:     t(n) – double array
n, the dimension of the array, must satisfy the constraint n2${\mathbf{n}}\ge 2$.
The observed failure and censored times; these need not be ordered.
Constraint: t(i)t(j)${\mathbf{t}}\left(\mathit{i}\right)\ne {\mathbf{t}}\left(\mathit{j}\right)$ for at least one ij$\mathit{i}\ne \mathit{j}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$ and j = 1,2,,n$\mathit{j}=1,2,\dots ,{\mathbf{n}}$.
2:     ic(n) – int64int32nag_int array
n, the dimension of the array, must satisfy the constraint n2${\mathbf{n}}\ge 2$.
ic(i)${\mathbf{ic}}\left(\mathit{i}\right)$ contains the censoring code of the i$\mathit{i}$th observation, for i = 1,2,,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
ic(i) = 0${\mathbf{ic}}\left(i\right)=0$
the i$i$th observation is a failure time.
ic(i) = 1${\mathbf{ic}}\left(i\right)=1$
the i$i$th observation is right-censored.
Constraints:
• 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}}$;
• ic(i) = 0${\mathbf{ic}}\left(i\right)=0$ for at least one i$i$.
3:     grp(n) – int64int32nag_int array
n, the dimension of the array, must satisfy the constraint n2${\mathbf{n}}\ge 2$.
grp(i)${\mathbf{grp}}\left(\mathit{i}\right)$ contains a flag indicating which group the i$\mathit{i}$th observation belongs in, for i = 1,2,,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
Constraints:
• 1grp(i)ngrp$1\le {\mathbf{grp}}\left(\mathit{i}\right)\le {\mathbf{ngrp}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$;
• each group must have at least one observation.
4:     ngrp – int64int32nag_int scalar
g$g$, the number of groups.
Constraint: 2ngrpn$2\le {\mathbf{ngrp}}\le {\mathbf{n}}$.
5:     freq – string (length ≥ 1)
Indicates whether frequencies are provided for each time point.
freq = 'F'${\mathbf{freq}}=\text{'F'}$
Frequencies are provided for each failure and censored time.
freq = 'S'${\mathbf{freq}}=\text{'S'}$
The failure and censored times are considered as single observations, i.e., a frequency of 1$1$ is assumed.
Constraint: freq = 'F'${\mathbf{freq}}=\text{'F'}$ or 'S'$\text{'S'}$.
6:     weight – string (length ≥ 1)
Indicates if weights are to be used.
weight = 'U'${\mathbf{weight}}=\text{'U'}$
All weights are assumed to be 1$1$.
weight = 'W'${\mathbf{weight}}=\text{'W'}$
The weights, wi${w}_{i}$ are supplied in wt.
Constraint: weight = 'U'${\mathbf{weight}}=\text{'U'}$ or 'W'$\text{'W'}$.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the array t and the dimension of the array ic and the dimension of the array grp. (An error is raised if these dimensions are not equal.)
n$n$, the number of failure and censored times.
Constraint: n2${\mathbf{n}}\ge 2$.
2:     ifreq( : $:$) – int64int32nag_int array
Note: the dimension of the array ifreq must be at least n${\mathbf{n}}$ if freq = 'F'${\mathbf{freq}}=\text{'F'}$.
If freq = 'F'${\mathbf{freq}}=\text{'F'}$, ifreq(i)${\mathbf{ifreq}}\left(i\right)$ must contain the frequency (number of observations) to which each entry in t corresponds.
If freq = 'S'${\mathbf{freq}}=\text{'S'}$, each entry in t is assumed to correspond to a single observation, i.e., a frequency of 1$1$ is assumed, and ifreq is not referenced.
Constraint: if freq = 'F'${\mathbf{freq}}=\text{'F'}$, ifreq(i)0${\mathbf{ifreq}}\left(\mathit{i}\right)\ge 0$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
3:     wt( : $:$) – double array
Note: the dimension of the array wt must be at least ldn${\mathbf{ldn}}$ if weight = 'W'${\mathbf{weight}}=\text{'W'}$.
If weight = 'W'${\mathbf{weight}}=\text{'W'}$, wt must contain the nd${n}_{d}$ weights, wi${w}_{i}$, where nd${n}_{d}$ is the number of distinct failure times.
If weight = 'U'${\mathbf{weight}}=\text{'U'}$, wt is not referenced and wi = 1${w}_{i}=1$ for all i$i$.
Constraint: if weight = 'W'${\mathbf{weight}}=\text{'W'}$, wt(i)0.0${\mathbf{wt}}\left(\mathit{i}\right)\ge 0.0$, for i = 1,2,,nd$\mathit{i}=1,2,\dots ,{n}_{d}$.
4:     ldn – int64int32nag_int scalar
The size of arrays di and ni. As ndn${n}_{d}\le n$, if nd${n}_{d}$ is not known a priori then a value of n can safely be used for ldn.
Default: n${\mathbf{n}}$
Constraint: ldnnd${\mathbf{ldn}}\ge {n}_{d}$, the number of unique failure times.

None.

### Output Parameters

1:     ts – double scalar
T$T$, the test statistic.
2:     df – int64int32nag_int scalar
ν$\nu$, the degrees of freedom.
3:     p – double scalar
P(XT)$P\left(X\ge T\right)$, when Xχν2$X\sim {\chi }_{\nu }^{2}$, i.e., the probability associated with ts.
4:     obsd(ngrp) – double array
Oi${O}_{i}$, the observed number of failures in each group.
5:     expt(ngrp) – double array
Ei${E}_{i}$, the expected number of failures in each group.
6:     nd – int64int32nag_int scalar
nd${n}_{d}$, the number of distinct failure times.
7:     di(ldn) – int64int32nag_int array
The first nd elements of di contain di${d}_{i}$, the number of failures, across all groups, at time ti${t}_{i}$.
8:     ni(ldn) – int64int32nag_int array
The first nd elements of ni contain ni${n}_{i}$, the size of the risk set, across all groups, at time ti${t}_{i}$.
9:     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:
ifail = 1${\mathbf{ifail}}=1$
Constraint: n2${\mathbf{n}}\ge 2$.
ifail = 2${\mathbf{ifail}}=2$
On entry, all the times in t are the same.
ifail = 3${\mathbf{ifail}}=3$
Constraint: ic(i) = 0${\mathbf{ic}}\left(i\right)=0$ or 1$1$.
ifail = 4${\mathbf{ifail}}=4$
Constraint: 1grp(i)ngrp$1\le {\mathbf{grp}}\left(i\right)\le {\mathbf{ngrp}}$.
ifail = 5${\mathbf{ifail}}=5$
Constraint: 2ngrpn$2\le {\mathbf{ngrp}}\le {\mathbf{n}}$.
ifail = 6${\mathbf{ifail}}=6$
On entry, freq had an illegal value.
ifail = 7${\mathbf{ifail}}=7$
Constraint: ifreq(i)0${\mathbf{ifreq}}\left(i\right)\ge 0$.
ifail = 8${\mathbf{ifail}}=8$
On entry, weight had an illegal value.
ifail = 9${\mathbf{ifail}}=9$
Constraint: wt(i)0.0${\mathbf{wt}}\left(i\right)\ge 0.0$.
ifail = 11${\mathbf{ifail}}=11$
The degrees of freedom are zero.
ifail = 18${\mathbf{ifail}}=18$
ldn is too small.
ifail = 31${\mathbf{ifail}}=31$
On entry, all observations are censored.
ifail = 41${\mathbf{ifail}}=41$
On entry, group _$_$ has no observations.
ifail = 999${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

Not applicable.

The use of different weights in the formula given in Section [Description] leads to different rank statistics being calculated. The logrank test has wi = 1${w}_{i}=1$, for all i$i$, which is the equivalent of calling nag_surviv_logrank (g12ab) when weight = 'U'${\mathbf{weight}}=\text{'U'}$ . Other rank statistics include Wilcoxon (wi = ni${w}_{i}={n}_{i}$), Tarone–Ware (wi = sqrt(ni)${w}_{i}=\sqrt{{n}_{i}}$) and Peto–Peto ( wi = (ti) ${w}_{i}=\stackrel{~}{S}\left({t}_{i}\right)$ where (ti) = tj ti   ( nj dj + 1 )/(nj + 1) $\stackrel{~}{S}\left({t}_{i}\right)=\prod _{{t}_{j}\le {t}_{i}}\phantom{\rule{0.25em}{0ex}}\frac{{n}_{j}-{d}_{j}+1}{{n}_{j}+1}$) amongst others.
Calculation of any test, other than the logrank test, will probably require nag_surviv_logrank (g12ab) to be called twice, once to calculate the values of ni${n}_{i}$ and di${d}_{i}$ to facilitate in the computation of the required weights, and once to calculate the test statistic itself.

## Example

```function nag_surviv_logrank_example
t = [6; 13; 21; 30; 31; 37; 38; 47; 49; 50; 63; 79; 80; 82; 82; 86; 98; ...
149; 202; 219; 10; 10; 12; 13; 14; 15; 16; 17; 18; 20; 24; 24; 25; ...
28; 30; 33; 34; 35; 37; 40; 40; 40; 46; 48; 70; 76; 81; 82; 91; 112; 181];
ic = [int64(0); 0; 0; 0; 1; 0; 0; 1; 0; 0; 0; 0; 1; 1; 1; 0; 0; 1; 0; 0; ...
0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 1; 0; 0; 0; 0; 1; 0; ...
0; 1; 0; 0; 0; 0; 0; 0];
grp = [int64(1); 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; ...
2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; ...
2; 2; 2; 2; 2; 2; 2; 2];
ngrp = int64(2);
freq = 's';
weight = 'u';

% Calculate the statistic
[ts, df, p, obsd, expt, nd, di, ni, ifail] = nag_surviv_logrank(t, ic, grp, ngrp, freq, weight);

% Display Results
fprintf('\n           Observed  Expected\n');
for i=1:2
fprintf(' Group %d %8.2f  %8.2f\n', i, obsd(i), expt(i));
end
fprintf('\n No. Unique Failure Times = %d\n\n', nd);
fprintf(' Test Statistic           = %8.4f\n', ts);
fprintf(' Degrees of Freedom       = %3d\n', df);
fprintf(' p-value                  = %8.4f\n', p);
```
```

Observed  Expected
Group 1    14.00     22.48
Group 2    28.00     19.52

No. Unique Failure Times = 36

Test Statistic           =   7.4966
Degrees of Freedom       =   1
p-value                  =   0.0062

```
```function g12ab_example
t = [6; 13; 21; 30; 31; 37; 38; 47; 49; 50; 63; 79; 80; 82; 82; 86; 98; ...
149; 202; 219; 10; 10; 12; 13; 14; 15; 16; 17; 18; 20; 24; 24; 25; ...
28; 30; 33; 34; 35; 37; 40; 40; 40; 46; 48; 70; 76; 81; 82; 91; 112; 181];
ic = [int64(0); 0; 0; 0; 1; 0; 0; 1; 0; 0; 0; 0; 1; 1; 1; 0; 0; 1; 0; 0; ...
0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 0; 1; 0; 0; 0; 0; 1; 0; ...
0; 1; 0; 0; 0; 0; 0; 0];
grp = [int64(1); 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; 1; ...
2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; 2; ...
2; 2; 2; 2; 2; 2; 2; 2];
ngrp = int64(2);
freq = 's';
weight = 'u';

% Calculate the statistic
[ts, df, p, obsd, expt, nd, di, ni, ifail] = g12ab(t, ic, grp, ngrp, freq, weight);

% Display Results
fprintf('\n           Observed  Expected\n');
for i=1:2
fprintf(' Group %d %8.2f  %8.2f\n', i, obsd(i), expt(i));
end
fprintf('\n No. Unique Failure Times = %d\n\n', nd);
fprintf(' Test Statistic           = %8.4f\n', ts);
fprintf(' Degrees of Freedom       = %3d\n', df);
fprintf(' p-value                  = %8.4f\n', p);
```
```

Observed  Expected
Group 1    14.00     22.48
Group 2    28.00     19.52

No. Unique Failure Times = 36

Test Statistic           =   7.4966
Degrees of Freedom       =   1
p-value                  =   0.0062

```

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013