# NAG FL Interfaceg12aaf (kaplanmeier)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

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

## 2Specification

Fortran Interface
 Subroutine g12aaf ( n, t, ic, freq, nd, tp, p, psig, iwk,
 Integer, Intent (In) :: n, ic(n), ifreq(*) Integer, Intent (Inout) :: ifail Integer, Intent (Out) :: nd, iwk(n) Real (Kind=nag_wp), Intent (In) :: t(n) Real (Kind=nag_wp), Intent (Out) :: tp(n), p(n), psig(n) Character (1), Intent (In) :: freq
#include <nag.h>
 void g12aaf_ (const Integer *n, const double t[], const Integer ic[], const char *freq, const Integer ifreq[], Integer *nd, double tp[], double p[], double psig[], Integer iwk[], Integer *ifail, const Charlen length_freq)
The routine may be called by the names g12aaf or nagf_surviv_kaplanmeier.

## 3Description

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=1idjnj(nj-dj) .$

## 4References

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

## 5Arguments

1: $\mathbf{n}$Integer Input
On entry: the number of failure and censored times given in t.
Constraint: ${\mathbf{n}}\ge 2$.
2: $\mathbf{t}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Input
On entry: the failure and censored times; these need not be ordered.
3: $\mathbf{ic}\left({\mathbf{n}}\right)$Integer array Input
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: $\mathbf{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: $\mathbf{ifreq}\left(*\right)$Integer array Input
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: $\mathbf{nd}$Integer Output
On exit: the number of distinct failure times, ${n}_{d}$.
7: $\mathbf{tp}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Output
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: $\mathbf{p}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Output
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: $\mathbf{psig}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Output
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: $\mathbf{iwk}\left({\mathbf{n}}\right)$Integer array Workspace
11: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ 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).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-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}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 2$.
${\mathbf{ifail}}=2$
On entry, ${\mathbf{freq}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{freq}}=\text{'F'}$ or $\text{'S'}$.
${\mathbf{ifail}}=3$
On entry, $i=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ic}}\left(i\right)=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ic}}\left(i\right)=0$ or $1$.
${\mathbf{ifail}}=4$
On entry, $i=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ifreq}}\left(i\right)=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ifreq}}\left(i\right)\ge 0$.
${\mathbf{ifail}}=-99$
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

The computations are believed to be stable.

## 8Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
g12aaf is not threaded in any implementation.

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

## 10Example

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

### 10.1Program Text

Program Text (g12aafe.f90)

### 10.2Program Data

Program Data (g12aafe.d)

### 10.3Program Results

Program Results (g12aafe.r)