# NAG CL Interfaceg12aac (kaplanmeier)

## 1Purpose

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

## 2Specification

 #include
 void g12aac (Integer n, const double t[], const Integer ic[], const Integer freq[], Integer *nd, double tp[], double p[], double psig[], NagError *fail)
The function may be called by the names: g12aac, nag_surviv_kaplanmeier or nag_prod_limit_surviv_fn.

## 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=1 i n j - d j n j$
where ${d}_{j}$ is the number of failures occurring at time ${t}_{j}$.
g12aac 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=1 i d j n j n j - d j .$

## 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]$const double Input
On entry: the failure and censored times; these need not be ordered.
3: $\mathbf{ic}\left[{\mathbf{n}}\right]$const Integer Input
On entry: ${\mathbf{ic}}\left[\mathit{i}-1\right]$ contains the censoring code of the $\mathit{i}$th observation, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
${\mathbf{ic}}\left[i-1\right]=0$
The $i$th observation is a failure time.
${\mathbf{ic}}\left[i-1\right]=1$
The $i$th observation is right-censored.
Constraint: ${\mathbf{ic}}\left[i-1\right]=0$ or $1$, for $i=1,2,\dots ,{\mathbf{n}}$.
4: $\mathbf{freq}\left[{\mathbf{n}}\right]$const Integer Input
On entry: indicates whether frequencies are provided for each failure and censored time point. If frequencies are provided then freq must be dimensioned at least n. If the failure and censored times are to be considered as single observations, i.e., a frequency of 1 is to be assumed then freq must be set to NULL.
Constraint: either ${\mathbf{freq}}=\left(\mathrm{Integer}*\right)0$ or ${\mathbf{freq}}\left[\mathit{i}-1\right]\ge 0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
5: $\mathbf{nd}$Integer * Output
On exit: the number of distinct failure times, ${n}_{d}$.
6: $\mathbf{tp}\left[{\mathbf{n}}\right]$double Output
On exit: ${\mathbf{tp}}\left[\mathit{i}-1\right]$ contains the $\mathit{i}$th ordered distinct failure time, ${t}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{n}_{d}$.
7: $\mathbf{p}\left[{\mathbf{n}}\right]$double Output
On exit: ${\mathbf{p}}\left[i-1\right]$ contains the Kaplan–Meier estimate of the survival probability, $\stackrel{^}{S}\left(t\right)$, for time ${\mathbf{tp}}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,{n}_{d}$.
8: $\mathbf{psig}\left[{\mathbf{n}}\right]$double Output
On exit: ${\mathbf{psig}}\left[\mathit{i}-1\right]$ contains an estimate of the standard deviation of ${\mathbf{p}}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,{n}_{d}$.
9: $\mathbf{fail}$NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

## 6Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_INT_ARG_LT
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 2$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_INVALID_CENSOR_CODE
On entry, ${\mathbf{ic}}\left[〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$. The censor code for an observation must be either 0 or 1.
NE_INVALID_FREQ
On entry, ${\mathbf{freq}}\left[〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$. The value of frequency for an observation must be $\ge 0$.

## 7Accuracy

The computations are believed to be stable.

## 8Parallelism and Performance

g12aac 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 (g12aace.c)

### 10.2Program Data

Program Data (g12aace.d)

### 10.3Program Results

Program Results (g12aace.r)