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)

Purpose

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

Syntax

[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)

Description

A survivor function, S(t)S(t), is the probability of surviving to at least time tt with S(t) = 1F(t)S(t)=1-F(t), where F(t)F(t) is the cumulative distribution function of the failure times. The Kaplan–Meier or product limit estimator provides an estimate of S(t)S(t), (t)S^(t), from sample of failure times which may be progressively right-censored.
Let titi, i = 1,2,,ndi=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 titi be nini. If a failure and a loss (censored observation) occur at the same time titi, then the failure is treated as if it had occurred slightly before time titi and the loss as if it had occurred slightly after titi.
The Kaplan–Meier estimate of the survival probabilities is a step function which in the interval titi to ti + 1ti+1 is given by
i
(t) = ((njdj)/(nj)),
j = 1
S^(t)=j=1i (nj-djnj) ,
where djdj is the number of failures occurring at time tjtj.
nag_surviv_kaplanmeier (g12aa) computes the Kaplan–Meier estimates and the corresponding estimates of the variances, var^((t))var^(S^(t)), using Greenwood's formula,
i
var̂((t)) = (t)2(dj)/(nj(njdj)).
j = 1
var^(S^(t))=S^ (t) 2j=1idjnj(nj-dj) .

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

Parameters

Compulsory Input Parameters

1:     t(n) – double array
n, the dimension of the array, must satisfy the constraint n2n2.
The failure and censored times; these need not be ordered.
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.
Constraint: ic(i) = 0ici=0 or 11, for i = 1,2,,ni=1,2,,n.
3:     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'.
4:     ifreq( : :) – int64int32nag_int array
Note: the dimension of the array ifreq must be at least nn if freq = 'F'freq='F' and at least 11 if freq = 'S'freq='S'.
If freq = 'F'freq='F', ifreq(i)ifreqi must contain the frequency of the iith observation.
If ifreq = 'S'ifreq='S', 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.

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: n2n2.

Input Parameters Omitted from the MATLAB Interface

iwk

Output Parameters

1:     nd – int64int32nag_int scalar
The number of distinct failure times, ndnd.
2:     tp(n) – double array
tp(i)tpi contains the iith ordered distinct failure time, titi, for i = 1,2,,ndi=1,2,,nd.
3:     p(n) – double array
p(i)pi contains the Kaplan–Meier estimate of the survival probability, (t)S^(t), for time tp(i)tpi, for i = 1,2,,ndi=1,2,,nd.
4:     psig(n) – double array
psig(i)psigi contains an estimate of the standard deviation of p(i)pi, for i = 1,2,,ndi=1,2,,nd.
5:     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
On entry,n < 2n<2.
  ifail = 2ifail=2
On entry,freq'F'freq'F' or 'S''S'.
  ifail = 3ifail=3
On entry,ic(i)0ici0 or 11, for some i = 1,2,,ni=1,2,,n.
  ifail = 4ifail=4
On entry,freq = 'F'freq='F' and ifreq(i) < 0ifreqi<0, for some i = 1,2,,ni=1,2,,n.

Accuracy

The computations are believed to be stable.

Further Comments

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

Example

function nag_surviv_kaplanmeier_example
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 = [int64(1);3;1;1;1;1;1;1;1;1;1;1;1;1;1;2;1;1];
[nd, tp, p, psig, ifail] = nag_surviv_kaplanmeier(t, ic, freq, ifreq)
 

nd =

                    7


tp =

     6
     7
    10
    13
    16
    22
    23
     0
     0
     0
     0
     0
     0
     0
     0
     0
     0
     0


p =

    0.8571
    0.8067
    0.7529
    0.6902
    0.6275
    0.5378
    0.4482
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0


psig =

    0.0764
    0.0869
    0.0963
    0.1068
    0.1141
    0.1282
    0.1346
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0


ifail =

                    0


function g12aa_example
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 = [int64(1);3;1;1;1;1;1;1;1;1;1;1;1;1;1;2;1;1];
[nd, tp, p, psig, ifail] = g12aa(t, ic, freq, ifreq)
 

nd =

                    7


tp =

     6
     7
    10
    13
    16
    22
    23
     0
     0
     0
     0
     0
     0
     0
     0
     0
     0
     0


p =

    0.8571
    0.8067
    0.7529
    0.6902
    0.6275
    0.5378
    0.4482
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0


psig =

    0.0764
    0.0869
    0.0963
    0.1068
    0.1141
    0.1282
    0.1346
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0


ifail =

                    0



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