G12 Chapter Contents
G12 Chapter Introduction
NAG Library Manual

# NAG Library Routine DocumentG12AAF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

## 1  Purpose

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

## 2  Specification

 SUBROUTINE G12AAF ( N, T, IC, FREQ, IFREQ, ND, TP, P, PSIG, IWK, IFAIL)
 INTEGER N, IC(N), IFREQ(*), ND, IWK(N), IFAIL REAL (KIND=nag_wp) T(N), TP(N), P(N), PSIG(N) CHARACTER(1) FREQ

## 3  Description

A survivor function, $S\left(t\right)$, is the probability of surviving to at least time $t$ with $S\left(t\right)=1-F\left(t\right)$, where $F\left(t\right)$ is the cumulative distribution function of the failure times. The Kaplan–Meier or product limit estimator provides an estimate of $S\left(t\right)$, $\stackrel{^}{S}\left(t\right)$, from sample of failure times which may be progressively right-censored.
Let ${t}_{i}$, $i=1,2,\dots ,{n}_{d}$, 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 ${t}_{i}$ be ${n}_{i}$. If a failure and a loss (censored observation) occur at the same time ${t}_{i}$, then the failure is treated as if it had occurred slightly before time ${t}_{i}$ and the loss as if it had occurred slightly after ${t}_{i}$.
The Kaplan–Meier estimate of the survival probabilities is a step function which in the interval ${t}_{i}$ to ${t}_{i+1}$ is given by
 $S^t=∏j=1i nj-djnj ,$
where ${d}_{j}$ is the number of failures occurring at time ${t}_{j}$.
G12AAF computes the Kaplan–Meier estimates and the corresponding estimates of the variances, $\stackrel{^}{\text{var}}\left(\stackrel{^}{S}\left(t\right)\right)$, using Greenwood's formula,
 $var^S^t=S^ t 2∑j=1idjnjnj-dj .$

## 4  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

## 5  Parameters

1:     N – INTEGERInput
On entry: the number of failure and censored times given in T.
Constraint: ${\mathbf{N}}\ge 2$.
2:     T(N) – REAL (KIND=nag_wp) arrayInput
On entry: the failure and censored times; these need not be ordered.
3:     IC(N) – INTEGER arrayInput
On entry: ${\mathbf{IC}}\left(\mathit{i}\right)$ contains the censoring code of the $\mathit{i}$th observation, for $\mathit{i}=1,2,\dots ,{\mathbf{N}}$.
${\mathbf{IC}}\left(i\right)=0$
The $i$th observation is a failure time.
${\mathbf{IC}}\left(i\right)=1$
The $i$th observation is right-censored.
Constraint: ${\mathbf{IC}}\left(\mathit{i}\right)=0$ or $1$, for $\mathit{i}=1,2,\dots ,{\mathbf{N}}$.
4:     FREQ – CHARACTER(1)Input
On entry: indicates whether frequencies are provided for each time point.
${\mathbf{FREQ}}=\text{'F'}$
Frequencies are provided for each failure and censored time.
${\mathbf{FREQ}}=\text{'S'}$
The failure and censored times are considered as single observations, i.e., a frequency of $1$ is assumed.
Constraint: ${\mathbf{FREQ}}=\text{'F'}$ or $\text{'S'}$.
5:     IFREQ($*$) – INTEGER arrayInput
Note: the dimension of the array IFREQ must be at least ${\mathbf{N}}$ if ${\mathbf{FREQ}}=\text{'F'}$ and at least $1$ if ${\mathbf{FREQ}}=\text{'S'}$.
On entry: if ${\mathbf{FREQ}}=\text{'F'}$, ${\mathbf{IFREQ}}\left(i\right)$ must contain the frequency of the $i$th observation.
If ${\mathbf{IFREQ}}=\text{'S'}$, a frequency of $1$ is assumed and IFREQ is not referenced.
Constraint: if ${\mathbf{FREQ}}=\text{'F'}$, ${\mathbf{IFREQ}}\left(\mathit{i}\right)\ge 0$, for $\mathit{i}=1,2,\dots ,{\mathbf{N}}$.
6:     ND – INTEGEROutput
On exit: the number of distinct failure times, ${n}_{d}$.
7:     TP(N) – REAL (KIND=nag_wp) arrayOutput
On exit: ${\mathbf{TP}}\left(\mathit{i}\right)$ contains the $\mathit{i}$th ordered distinct failure time, ${t}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{n}_{\mathrm{d}}$.
8:     P(N) – REAL (KIND=nag_wp) arrayOutput
On exit: ${\mathbf{P}}\left(\mathit{i}\right)$ contains the Kaplan–Meier estimate of the survival probability, $\stackrel{^}{S}\left(t\right)$, for time ${\mathbf{TP}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,{n}_{d}$.
9:     PSIG(N) – REAL (KIND=nag_wp) arrayOutput
On exit: ${\mathbf{PSIG}}\left(\mathit{i}\right)$ contains an estimate of the standard deviation of ${\mathbf{P}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,{n}_{d}$.
10:   IWK(N) – INTEGER arrayWorkspace
11:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to $0$, $-1\text{​ or ​}1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{​ or ​}1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is $0$. When the value $-\mathbf{1}\text{​ or ​}\mathbf{1}$ is used it is essential to test the value of IFAIL on exit.
On exit: ${\mathbf{IFAIL}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6  Error Indicators and Warnings

If on entry ${\mathbf{IFAIL}}={\mathbf{0}}$ or $-{\mathbf{1}}$, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
${\mathbf{IFAIL}}=1$
 On entry, ${\mathbf{N}}<2$.
${\mathbf{IFAIL}}=2$
 On entry, ${\mathbf{FREQ}}\ne \text{'F'}$ or $\text{'S'}$.
${\mathbf{IFAIL}}=3$
 On entry, ${\mathbf{IC}}\left(i\right)\ne 0$ or $1$, for some $i=1,2,\dots ,{\mathbf{N}}$.
${\mathbf{IFAIL}}=4$
 On entry, ${\mathbf{FREQ}}=\text{'F'}$ and ${\mathbf{IFREQ}}\left(i\right)<0$, for some $i=1,2,\dots ,{\mathbf{N}}$.

## 7  Accuracy

The computations are believed to be stable.

If there are no censored observations, $\stackrel{^}{S}\left(t\right)$ reduces to the ordinary binomial estimate of the probability of survival at time $t$.

## 9  Example

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

### 9.1  Program Text

Program Text (g12aafe.f90)

### 9.2  Program Data

Program Data (g12aafe.d)

### 9.3  Program Results

Program Results (g12aafe.r)