Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

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\left(t\right)$, is the probability of surviving to at least time t$t$ with S(t) = 1F(t)$S\left(t\right)=1-F\left(t\right)$, where F(t)$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(t)$S\left(t\right)$, (t)$\stackrel{^}{S}\left(t\right)$, from sample of failure times which may be progressively right-censored.
Let ti${t}_{i}$, i = 1,2,,nd$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 ti${t}_{i}$ be ni${n}_{i}$. If a failure and a loss (censored observation) occur at the same time ti${t}_{i}$, then the failure is treated as if it had occurred slightly before time ti${t}_{i}$ and the loss as if it had occurred slightly after ti${t}_{i}$.
The Kaplan–Meier estimate of the survival probabilities is a step function which in the interval ti${t}_{i}$ to ti + 1${t}_{i+1}$ is given by
 i Ŝ(t) = ∏ ((nj − dj)/(nj)), j = 1
$S^(t)=∏j=1i (nj-djnj) ,$
where dj${d}_{j}$ is the number of failures occurring at time tj${t}_{j}$.
nag_surviv_kaplanmeier (g12aa) computes the Kaplan–Meier estimates and the corresponding estimates of the variances, var^((t))$\stackrel{^}{\text{var}}\left(\stackrel{^}{S}\left(t\right)\right)$, using Greenwood's formula,
 i var̂(Ŝ(t)) = Ŝ(t)2 ∑ (dj)/(nj(nj − dj)). j = 1
$var^(S^(t))=S^ (t) 2∑j=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 n2${\mathbf{n}}\ge 2$.
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 n2${\mathbf{n}}\ge 2$.
ic(i)${\mathbf{ic}}\left(\mathit{i}\right)$ contains the censoring code of the i$\mathit{i}$th observation, for i = 1,2,,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
ic(i) = 0${\mathbf{ic}}\left(i\right)=0$
The i$i$th observation is a failure time.
ic(i) = 1${\mathbf{ic}}\left(i\right)=1$
The i$i$th observation is right-censored.
Constraint: ic(i) = 0${\mathbf{ic}}\left(\mathit{i}\right)=0$ or 1$1$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
3:     freq – string (length ≥ 1)
Indicates whether frequencies are provided for each time point.
freq = 'F'${\mathbf{freq}}=\text{'F'}$
Frequencies are provided for each failure and censored time.
freq = 'S'${\mathbf{freq}}=\text{'S'}$
The failure and censored times are considered as single observations, i.e., a frequency of 1$1$ is assumed.
Constraint: freq = 'F'${\mathbf{freq}}=\text{'F'}$ or 'S'$\text{'S'}$.
4:     ifreq( : $:$) – int64int32nag_int array
Note: the dimension of the array ifreq must be at least n${\mathbf{n}}$ if freq = 'F'${\mathbf{freq}}=\text{'F'}$ and at least 1$1$ if freq = 'S'${\mathbf{freq}}=\text{'S'}$.
If freq = 'F'${\mathbf{freq}}=\text{'F'}$, ifreq(i)${\mathbf{ifreq}}\left(i\right)$ must contain the frequency of the i$i$th observation.
If ifreq = 'S'${\mathbf{ifreq}}=\text{'S'}$, a frequency of 1$1$ is assumed and ifreq is not referenced.
Constraint: if freq = 'F'${\mathbf{freq}}=\text{'F'}$, ifreq(i)0${\mathbf{ifreq}}\left(\mathit{i}\right)\ge 0$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,{\mathbf{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${\mathbf{n}}\ge 2$.

iwk

### Output Parameters

1:     nd – int64int32nag_int scalar
The number of distinct failure times, nd${n}_{d}$.
2:     tp(n) – double array
tp(i)${\mathbf{tp}}\left(\mathit{i}\right)$ contains the i$\mathit{i}$th ordered distinct failure time, ti${t}_{\mathit{i}}$, for i = 1,2,,nd$\mathit{i}=1,2,\dots ,{n}_{\mathrm{d}}$.
3:     p(n) – double array
p(i)${\mathbf{p}}\left(\mathit{i}\right)$ contains the Kaplan–Meier estimate of the survival probability, (t)$\stackrel{^}{S}\left(t\right)$, for time tp(i)${\mathbf{tp}}\left(\mathit{i}\right)$, for i = 1,2,,nd$\mathit{i}=1,2,\dots ,{n}_{d}$.
4:     psig(n) – double array
psig(i)${\mathbf{psig}}\left(\mathit{i}\right)$ contains an estimate of the standard deviation of p(i)${\mathbf{p}}\left(\mathit{i}\right)$, for i = 1,2,,nd$\mathit{i}=1,2,\dots ,{n}_{d}$.
5:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:
ifail = 1${\mathbf{ifail}}=1$
 On entry, n < 2${\mathbf{n}}<2$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, freq ≠ 'F'${\mathbf{freq}}\ne \text{'F'}$ or 'S'$\text{'S'}$.
ifail = 3${\mathbf{ifail}}=3$
 On entry, ic(i) ≠ 0${\mathbf{ic}}\left(i\right)\ne 0$ or 1$1$, for some i = 1,2, … ,n$i=1,2,\dots ,{\mathbf{n}}$.
ifail = 4${\mathbf{ifail}}=4$
 On entry, freq = 'F'${\mathbf{freq}}=\text{'F'}$ and ifreq(i) < 0${\mathbf{ifreq}}\left(i\right)<0$, for some i = 1,2, … ,n$i=1,2,\dots ,{\mathbf{n}}$.

## Accuracy

The computations are believed to be stable.

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

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

```