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_kaplanmeier (g12aa)


    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example


nag_surviv_kaplanmeier (g12aa) computes the Kaplan–Meier, (or product-limit), estimates of survival probabilities for a sample of failure times.


[nd, tp, p, psig, ifail] = g12aa(t, ic, freq, ifreq, 'n', n)
[nd, tp, p, psig, ifail] = nag_surviv_kaplanmeier(t, ic, freq, ifreq, 'n', n)


A survivor function, St, is the probability of surviving to at least time t with St=1-Ft, where Ft is the cumulative distribution function of the failure times. The Kaplan–Meier or product limit estimator provides an estimate of St, S^t, from sample of failure times which may be progressively right-censored.
Let ti, i=1,2,,nd, be the ordered distinct failure times for the sample of observed failure/censored times, and let the number of observations in the sample that have not failed by time ti be ni. If a failure and a loss (censored observation) occur at the same time ti, then the failure is treated as if it had occurred slightly before time ti and the loss as if it had occurred slightly after ti.
The Kaplan–Meier estimate of the survival probabilities is a step function which in the interval ti to ti+1 is given by
S^t=j=1i nj-djnj ,  
where dj is the number of failures occurring at time tj.
nag_surviv_kaplanmeier (g12aa) computes the Kaplan–Meier estimates and the corresponding estimates of the variances, var^S^t, using Greenwood's formula,
var^S^t=S^ t 2j=1idjnjnj-dj .  


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


Compulsory Input Parameters

1:     tn – double array
The failure and censored times; these need not be ordered.
2:     icn int64int32nag_int array
ici contains the censoring code of the ith observation, for i=1,2,,n.
The ith observation is a failure time.
The ith observation is right-censored.
Constraint: ici=0 or 1, for i=1,2,,n.
3:     freq – string (length ≥ 1)
Indicates whether frequencies are provided for each time point.
Frequencies are provided for each failure and censored time.
The failure and censored times are considered as single observations, i.e., a frequency of 1 is assumed.
Constraint: freq='F' or 'S'.
4:     ifreq: int64int32nag_int array
The dimension of the array ifreq must be at least n if freq='F' and at least 1 if freq='S'
If freq='F', ifreqi must contain the frequency of the ith observation.
If ifreq='S', a frequency of 1 is assumed and ifreq is not referenced.
Constraint: if freq='F', ifreqi0, for i=1,2,,n.

Optional Input Parameters

1:     n int64int32nag_int scalar
Default: the dimension of the arrays ic, t. (An error is raised if these dimensions are not equal.)
The number of failure and censored times given in t.
Constraint: n2.

Output Parameters

1:     nd int64int32nag_int scalar
The number of distinct failure times, nd.
2:     tpn – double array
tpi contains the ith ordered distinct failure time, ti, for i=1,2,,nd.
3:     pn – double array
pi contains the Kaplan–Meier estimate of the survival probability, S^t, for time tpi, for i=1,2,,nd.
4:     psign – double array
psigi contains an estimate of the standard deviation of pi, for i=1,2,,nd.
5:     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:
On entry,n<2.
On entry,freq'F' or 'S'.
On entry,ici0 or 1, for some i=1,2,,n.
On entry,freq='F' and ifreqi<0, for some i=1,2,,n.
An unexpected error has been triggered by this routine. Please contact NAG.
Your licence key may have expired or may not have been installed correctly.
Dynamic memory allocation failed.


The computations are believed to be stable.

Further Comments

If there are no censored observations, S^t reduces to the ordinary binomial estimate of the probability of survival at time t.


The remission times for a set of 21 leukaemia patients at 18 distinct time points are read in and the Kaplan–Meier estimate computed and printed. For further details see page 242 of Gross and Clark (1975).
function g12aa_example

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

t  = [         6;  6;  7;  9; 10; 10; 11; 13; 16;
              17; 19; 20; 22; 23; 25; 32; 34; 35];
ic = [int64(1);  0;  0;  1;  0;  1;  1;  0;  0;
               1;  1;  1;  0;  0;  1;  1;  1;  1];

freq  = 'Frequencies';
ifreq = ones(numel(t),1,'int64');
ifreq(2)  = 3;
ifreq(16) = 2;

% Calculate Kaplan-Meier statistic
[nd, tp, p, psig, ifail] = g12aa( ...
                                  t, ic, freq, ifreq);

% Display the results
fprintf('  Time   Survival    Standard\n');
fprintf('        probability  deviation\n\n');
fprintf('%6.1f%10.3f%12.3f\n', [tp(1:nd) p(1:nd) psig(1:nd)]');

fig1 = figure;
stp = [0; tp(1:nd)];
sp  = [1; p(1:nd)];
ylabel('Survival probability');
title('Kaplan Meier plot');
axis([0 tp(nd)+1 0 1.1]);

g12aa example results

  Time   Survival    Standard
        probability  deviation

   6.0     0.857       0.076
   7.0     0.807       0.087
  10.0     0.753       0.096
  13.0     0.690       0.107
  16.0     0.627       0.114
  22.0     0.538       0.128
  23.0     0.448       0.135

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–2015