hide long namesshow long names
hide short namesshow short names
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(t), is the probability of surviving to at least time tt. Given a series of nn failure or right-censored times from gg groups nag_surviv_logrank (g12ab) calculates a rank statistic for testing the null hypothesis where ττ is the largest observed time, against the alternative hypothesis
Let t i t i , for i = 1,2,,ndi=1,2,,nd, denote the list of distinct failure times across all gg groups and wiwi a series of ndnd weights. Let dijdij denote the number of failures at time titi in group jj and nijnij denote the number of observations in the group jj that are known to have not failed prior to time titi, i.e., the size of the risk set for group jj at time titi. If a censored observation occurs at time titi then that observation is treated as if the censoring had occurred slightly after titi and therefore the observation is counted as being part of the risk set at time titi. 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 jjth group, OjOj, 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 jjth group, EjEj, by
nd
Ej = wi ( nij di )/(ni) .
i = 1
Ej = i=1 nd wi n ij di ni .
If xx denotes the vector of differences x = (O1E1,O2E2,,OgEg) x = ( O1 - E1 , O2 - E2 , , Og - Eg )  and
nd
Vjk = wi2 (( di (nidi) (nin i k Ijknijnik) )/( ni2 (ni1) ))
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 = kj=k and 00 otherwise, then the rank statistic, TT, is calculated as
T = x V xT
T = x V- xT
where VV- denotes a generalized inverse of the matrix VV. Under the null hypothesis, T χν2 T χ ν 2  where the degrees of freedom, νν, is taken as the rank of the matrix VV.

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 n2n2.
The observed failure and censored times; these need not be ordered.
Constraint: t(i)t(j)titj for at least one ijij, for i = 1,2,,ni=1,2,,n and j = 1,2,,nj=1,2,,n.
2:     ic(n) – int64int32nag_int array
n, the dimension of the array, must satisfy the constraint n2n2.
ic(i)ici contains the censoring code of the iith observation, for i = 1,2,,ni=1,2,,n.
ic(i) = 0ici=0
the iith observation is a failure time.
ic(i) = 1ici=1
the iith observation is right-censored.
Constraints:
  • ic(i) = 0ici=0 or 11, for i = 1,2,,ni=1,2,,n;
  • ic(i) = 0ici=0 for at least one ii.
3:     grp(n) – int64int32nag_int array
n, the dimension of the array, must satisfy the constraint n2n2.
grp(i)grpi contains a flag indicating which group the iith observation belongs in, for i = 1,2,,ni=1,2,,n.
Constraints:
  • 1grp(i)ngrp1grpingrp, for i = 1,2,,ni=1,2,,n;
  • each group must have at least one observation.
4:     ngrp – int64int32nag_int scalar
gg, the number of groups.
Constraint: 2ngrpn2ngrpn.
5:     freq – string (length ≥ 1)
Indicates whether frequencies are provided for each time point.
freq = 'F'freq='F'
Frequencies are provided for each failure and censored time.
freq = 'S'freq='S'
The failure and censored times are considered as single observations, i.e., a frequency of 11 is assumed.
Constraint: freq = 'F'freq='F' or 'S''S'.
6:     weight – string (length ≥ 1)
Indicates if weights are to be used.
weight = 'U'weight='U'
All weights are assumed to be 11.
weight = 'W'weight='W'
The weights, wiwi are supplied in wt.
Constraint: weight = 'U'weight='U' or 'W''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.)
nn, the number of failure and censored times.
Constraint: n2n2.
2:     ifreq( : :) – int64int32nag_int array
Note: the dimension of the array ifreq must be at least nn if freq = 'F'freq='F'.
If freq = 'F'freq='F', ifreq(i)ifreqi must contain the frequency (number of observations) to which each entry in t corresponds.
If freq = 'S'freq='S', each entry in t is assumed to correspond to a single observation, i.e., a frequency of 11 is assumed, and ifreq is not referenced.
Constraint: if freq = 'F'freq='F', ifreq(i)0ifreqi0, for i = 1,2,,ni=1,2,,n.
3:     wt( : :) – double array
Note: the dimension of the array wt must be at least ldnldn if weight = 'W'weight='W'.
If weight = 'W'weight='W', wt must contain the ndnd weights, wiwi, where ndnd is the number of distinct failure times.
If weight = 'U'weight='U', wt is not referenced and wi = 1wi=1 for all ii.
Constraint: if weight = 'W'weight='W', wt(i)0.0wti0.0, for i = 1,2,,ndi=1,2,,nd.
4:     ldn – int64int32nag_int scalar
The size of arrays di and ni. As ndnndn, if ndnd is not known a priori then a value of n can safely be used for ldn.
Default: nn
Constraint: ldnndldnnd, the number of unique failure times.

Input Parameters Omitted from the MATLAB Interface

None.

Output Parameters

1:     ts – double scalar
TT, the test statistic.
2:     df – int64int32nag_int scalar
νν, the degrees of freedom.
3:     p – double scalar
P(XT)P(XT), when Xχν2Xχν2, i.e., the probability associated with ts.
4:     obsd(ngrp) – double array
OiOi, the observed number of failures in each group.
5:     expt(ngrp) – double array
EiEi, the expected number of failures in each group.
6:     nd – int64int32nag_int scalar
ndnd, the number of distinct failure times.
7:     di(ldn) – int64int32nag_int array
The first nd elements of di contain didi, the number of failures, across all groups, at time titi.
8:     ni(ldn) – int64int32nag_int array
The first nd elements of ni contain nini, the size of the risk set, across all groups, at time titi.
9:     ifail – int64int32nag_int scalar
ifail = 0ifail=0 unless the function detects an error (see [Error Indicators and Warnings]).

Error Indicators and Warnings

Errors or warnings detected by the function:
  ifail = 1ifail=1
Constraint: n2n2.
  ifail = 2ifail=2
On entry, all the times in t are the same.
  ifail = 3ifail=3
Constraint: ic(i) = 0ici=0 or 11.
  ifail = 4ifail=4
Constraint: 1grp(i)ngrp1grpingrp.
  ifail = 5ifail=5
Constraint: 2ngrpn2ngrpn.
  ifail = 6ifail=6
On entry, freq had an illegal value.
  ifail = 7ifail=7
Constraint: ifreq(i)0ifreqi0.
  ifail = 8ifail=8
On entry, weight had an illegal value.
  ifail = 9ifail=9
Constraint: wt(i)0.0wti0.0.
  ifail = 11ifail=11
The degrees of freedom are zero.
  ifail = 18ifail=18
ldn is too small.
  ifail = 31ifail=31
On entry, all observations are censored.
  ifail = 41ifail=41
On entry, group __ has no observations.
  ifail = 999ifail=-999
Dynamic memory allocation failed.

Accuracy

Not applicable.

Further Comments

The use of different weights in the formula given in Section [Description] leads to different rank statistics being calculated. The logrank test has wi = 1wi=1, for all ii, which is the equivalent of calling nag_surviv_logrank (g12ab) when weight = 'U'weight='U' . Other rank statistics include Wilcoxon (wi = niwi=ni), Tarone–Ware (wi = sqrt(ni)wi=ni) and Peto–Peto ( wi = (ti) wi = S~ (ti)  where (ti) = tj ti   ( nj dj + 1 )/(nj + 1) S~ (ti) = tj ti nj - dj + 1 nj+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 nini and didi 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