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

C Header Interface

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

3 Description

A survivor function,

S (t)

, is the probability of surviving to at least time

t

with

S (t) = 1 - F (t)

, where

F (t)

is the cumulative distribution function of the failure times. The Kaplan–Meier or product limit estimator provides an estimate of

S (t)

\hat{S} (t)

, 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}

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}

t_{i + 1}

is given by

\hat{S} (t) = \prod_{j = 1}^{i} (\frac{n_{j} - d_{j}}{n_{j}}),

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,

\hat{var} (\hat{S} (t))

, using Greenwood's formula,

\hat{var} (\hat{S} (t)) = \hat{S} {(t)}^{2} \sum_{j = 1}^{i} \frac{d_{j}}{n_{j} (n_{j} - d_{j})} .

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 Arguments

1: $n$ – Integer Input

On entry: the number of failure and censored times given in t.

Constraint:

n \geq 2

2: $t (n)$ – Real (Kind=nag_wp) array Input

On entry: the failure and censored times; these need not be ordered.

3: $ic (n)$ – Integer array Input

On entry:

ic (i)

contains the censoring code of the

i

th observation, for

i = 1, 2, \dots, n

$ic (i) = 0$: The $i$ th observation is a failure time.
$ic (i) = 1$: The $i$ th observation is right-censored.

Constraint:

ic (i) = 0

1

, for

i = 1, 2, \dots, n

4: $freq$ – Character(1) Input

On entry: indicates whether frequencies are provided for each time point.

$freq ='F'$: Frequencies are provided for each failure and censored time.
$freq ='S'$: The failure and censored times are considered as single observations, i.e., a frequency of $1$ is assumed.

Constraint:

freq ='F'

'S'

5: $ifreq (*)$ – Integer array Input

Note: the dimension of the array ifreq must be at least

n

freq ='F'

and at least

1

freq ='S'

On entry: if

freq ='F'

ifreq (i)

must contain the frequency of the

i

th observation.

ifreq ='S'

, a frequency of

1

is assumed and ifreq is not referenced.

Constraint: if

freq ='F'

ifreq (i) \geq 0

, for

i = 1, 2, \dots, n

6: $nd$ – Integer Output

On exit: the number of distinct failure times,

n_{d}

7: $tp (n)$ – Real (Kind=nag_wp) array Output

On exit:

tp (i)

contains the

i

th ordered distinct failure time,

t_{i}

, for

i = 1, 2, \dots, n_{d}

8: $p (n)$ – Real (Kind=nag_wp) array Output

On exit:

p (i)

contains the Kaplan–Meier estimate of the survival probability,

\hat{S} (t)

, for time

tp (i)

, for

i = 1, 2, \dots, n_{d}

9: $psig (n)$ – Real (Kind=nag_wp) array Output

On exit:

psig (i)

contains an estimate of the standard deviation of

p (i)

, for

i = 1, 2, \dots, n_{d}

10: $iwk (n)$ – Integer array Workspace

11: $ifail$ – Integer Input/Output

On entry: ifail must be set to

0

−1

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

1

is recommended. If message printing is undesirable, then the value

1

is recommended. Otherwise, the value

0

is recommended. When the value $- 1$ or $1$ is used it is essential to test the value of ifail on exit.

On exit:

ifail = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

ifail = 0

−1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = 1$: On entry, $n = ⟨ value ⟩$ .
Constraint: $n \geq 2$ .

$ifail = 2$: On entry, $freq = ⟨ value ⟩$ .
Constraint: $freq ='F'$ or $'S'$ .

$ifail = 3$: On entry, $i = ⟨ value ⟩$ and $ic (i) = ⟨ value ⟩$ .
Constraint: $ic (i) = 0$ or $1$ .

$ifail = 4$: On entry, $i = ⟨ value ⟩$ and $ifreq (i) = ⟨ value ⟩$ .
Constraint: $ifreq (i) \geq 0$ .

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

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

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

The computations are believed to be stable.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.

g12aaf is not threaded in any implementation.

9 Further Comments

If there are no censored observations,

\hat{S} (t)

reduces to the ordinary binomial estimate of the probability of survival at time

t

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

g12aa: FL CL CPP AD PY MB

NAG FL Interfaceg12aaf (kaplanmeier)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG FL Interface
g12aaf (kaplanmeier)