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)

▸▿ Contents

1 Purpose

2 Syntax

3 Description

4 References

▸▿ 5 Parameters

5.1 Compulsory Input Parameters

5.2 Optional Input Parameters

5.3 Output Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

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)

, is the probability of surviving to at least time

t

. Given a series of

n

failure or right-censored times from

g

groups nag_surviv_logrank (g12ab) calculates a rank statistic for testing the null hypothesis

$H_{0} : S_{1} (t) = S_{2} (t) = \dots = S_{g} (t), \forall t \leq τ$

where

τ

is the largest observed time, against the alternative hypothesis

$H_{1} :$ at least one of the $S_{i} (t)$ differ, for some $t \leq τ$ .

Let

t_{i}

, for

i = 1, 2, \dots, n_{d}

, denote the list of distinct failure times across all

g

groups and

w_{i}

a series of

n_{d}

weights. Let

d_{i j}

denote the number of failures at time

t_{i}

in group

j

and

n_{i j}

denote the number of observations in the group

j

that are known to have not failed prior to time

t_{i}

, i.e., the size of the risk set for group

j

at time

t_{i}

. If a censored observation occurs at time

t_{i}

then that observation is treated as if the censoring had occurred slightly after

t_{i}

and therefore the observation is counted as being part of the risk set at time

t_{i}

. Finally let

d_{i} = \sum_{j = 1}^{g} d_{i j} and n_{i} = \sum_{j = 1}^{g} n_{i j} .

The (weighted) number of observed failures in the

j

th group,

O_{j}

, is therefore given by

O_{j} = \sum_{i = 1}^{n_{d}} w_{i} d_{i j}

and the (weighted) number of expected failures in the

j

th group,

E_{j}

, by

E_{j} = \sum_{i = 1}^{n_{d}} w_{i} \frac{n_{i j} d_{i}}{n_{i}} .

x

denotes the vector of differences

x = (O_{1} - E_{1}, O_{2} - E_{2}, \dots, O_{g} - E_{g})

and

V_{j k} = \sum_{i = 1}^{n_{d}} w_{i}^{2} (\frac{d_{i} (n_{i} - d_{i}) (n_{i} n_{i k} I_{j k} - n_{i j} n_{i k})}{n_{i}^{2} (n_{i} - 1)})

where

I_{j k} = 1

j = k

and

0

otherwise, then the rank statistic,

T

, is calculated as

T = x V^{-} x^{T}

where

V^{-}

denotes a generalized inverse of the matrix

V

. Under the null hypothesis,

T \sim χ_{ν}^{2}

where the degrees of freedom,

ν

, is taken as the rank of the matrix

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

The observed failure and censored times; these need not be ordered.

Constraint:

t (i) \neq t (j)

for at least one

i \neq j

, for

i = 1, 2, \dots, n

and

j = 1, 2, \dots, n

2: $ic (n)$ – int64int32nag_int array

ic (i)

contains the censoring code of the

i

th observation, for

i = 1, 2, \dots, n

$ic (i) = 0$: the $i$ th observation is a failure time.
$ic (i) = 1$: the $i$ th observation is right-censored.

Constraints:

$ic (i) = 0$ or $1$ , for $i = 1, 2, \dots, n$ ;
$ic (i) = 0$ for at least one $i$ .

3: $grp (n)$ – int64int32nag_int array

grp (i)

contains a flag indicating which group the

i

th observation belongs in, for

i = 1, 2, \dots, n

Constraints:

$1 \leq grp (i) \leq ngrp$ , for $i = 1, 2, \dots, n$ ;
each group must have at least one observation.

4: $ngrp$ – int64int32nag_int scalar

g

, the number of groups.

Constraint:

2 \leq ngrp \leq n

5: $freq$ – string (length ≥ 1)

Indicates whether frequencies are provided for each time point.

$freq ='F'$: Frequencies are provided for each failure and censored time.
$freq ='S'$: The failure and censored times are considered as single observations, i.e., a frequency of $1$ is assumed.

Constraint:

freq ='F'

'S'

6: $weight$ – string (length ≥ 1)

Indicates if weights are to be used.

$weight ='U'$: All weights are assumed to be $1$ .
$weight ='W'$: The weights, $w_{i}$ are supplied in wt.

Constraint:

weight ='U'

'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$ , the number of failure and censored times.

Constraint: $n \geq 2$ .
2: $ifreq (:)$ – int64int32nag_int array: The dimension of the array ifreq must be at least $n$ if $freq ='F'$

If $freq ='F'$ , $ifreq (i)$ must contain the frequency (number of observations) to which each entry in t corresponds.
If $freq ='S'$ , each entry in t is assumed to correspond to a single observation, i.e., a frequency of $1$ is assumed, and ifreq is not referenced.

Constraint: if $freq ='F'$ , $ifreq (i) \geq 0$ , for $i = 1, 2, \dots, n$ .
3: $wt (:)$ – double array: The dimension of the array wt must be at least $ldn$ if $weight ='W'$

If $weight ='W'$ , wt must contain the $n_{d}$ weights, $w_{i}$ , where $n_{d}$ is the number of distinct failure times.
If $weight ='U'$ , wt is not referenced and $w_{i} = 1$ for all $i$ .

Constraint: if $weight ='W'$ , $wt (i) \geq 0.0$ , for $i = 1, 2, \dots, n_{d}$ .
4: $ldn$ – int64int32nag_int scalar: Default: $n$
The size of arrays di and ni. As $n_{d} \leq n$ , if $n_{d}$ is not known a priori then a value of n can safely be used for ldn.

Constraint: $ldn \geq n_{d}$ , the number of unique failure times.

Output Parameters

1: $ts$ – double scalar: $T$ , the test statistic.
2: $df$ – int64int32nag_int scalar: $ν$ , the degrees of freedom.
3: $p$ – double scalar: $P (X \geq T)$ , when $X \sim χ_{ν}^{2}$ , i.e., the probability associated with ts.
4: $obsd (ngrp)$ – double array: $O_{i}$ , the observed number of failures in each group.
5: $expt (ngrp)$ – double array: $E_{i}$ , the expected number of failures in each group.
6: $nd$ – int64int32nag_int scalar: $n_{d}$ , the number of distinct failure times.
7: $di (ldn)$ – int64int32nag_int array: The first nd elements of di contain $d_{i}$ , the number of failures, across all groups, at time $t_{i}$ .
8: $ni (ldn)$ – int64int32nag_int array: The first nd elements of ni contain $n_{i}$ , the size of the risk set, across all groups, at time $t_{i}$ .
9: $ifail$ – int64int32nag_int scalar: $ifail = 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$: Constraint: $n \geq 2$ .

$ifail = 2$: On entry, all the times in t are the same.

$ifail = 3$: Constraint: $ic (i) = 0$ or $1$ .

$ifail = 4$: Constraint: $1 \leq grp (i) \leq ngrp$ .

$ifail = 5$: Constraint: $2 \leq ngrp \leq n$ .

$ifail = 6$: On entry, freq had an illegal value.

$ifail = 7$: Constraint: $ifreq (i) \geq 0$ .

$ifail = 8$: On entry, weight had an illegal value.

$ifail = 9$: Constraint: $wt (i) \geq 0.0$ .

$ifail = 11$: The degrees of freedom are zero.

$ifail = 18$: ldn is too small.

$ifail = 31$: On entry, all observations are censored.

$ifail = 41$: On entry, group $_$ has no observations.

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$ifail = - 999$: Dynamic memory allocation failed.

Accuracy

Not applicable.

Further Comments

The use of different weights in the formula given in Description leads to different rank statistics being calculated. The logrank test has

w_{i} = 1

, for all

i

, which is the equivalent of calling nag_surviv_logrank (g12ab) when

weight ='U'

. Other rank statistics include Wilcoxon (

w_{i} = n_{i}

), Tarone–Ware (

w_{i} = \sqrt{n_{i}}

) and Peto–Peto (

w_{i} = \tilde{S} (t_{i})

where

\tilde{S} (t_{i}) = \prod_{t_{j} \leq t_{i}} \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

n_{i}

and

d_{i}

to facilitate in the computation of the required weights, and once to calculate the test statistic itself.

Example

This example compares the time to death for

51

adults with two different types of recurrent gliomas (brain tumour), astrocytoma and glioblastoma, using a logrank test. For further details on the data see Rostomily et al. (1994).

Open in the MATLAB editor: g12ab_example

function g12ab_example


fprintf('g12ab example results\n\n');

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];
n = numel(t);

ic   = zeros(n,1,'int64');
ic(5)  = 1; ic(8)  = 1; ic(13:15) = 1;
ic(18) = 1; ic(37) = 1; ic(42)    = 1;
ic(45) = 1;

grp = ones(n,1,'int64');
grp(21:end) = 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('           Observed  Expected\n');
for i=1:ngrp
  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);

g12ab example results

           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