NAG Library Function Document

nag_prod_limit_surviv_fn (g12aac)

void	nag_prod_limit_surviv_fn (Integer n, const double t[], const Integer ic[], const Integer freq[], Integer nd, double tp[], double p[], double psig[], NagError fail)

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}

nag_prod_limit_surviv_fn (g12aac) 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$ – IntegerInput

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

Constraint:

n \geq 2

2: $t [n]$ – const doubleInput

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

3: $ic [n]$ – const IntegerInput

On entry:

ic [i - 1]

contains the censoring code of the

i

th observation, for

i = 1, 2, \dots, n

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

Constraint:

ic [i - 1] = 0

1

, for

i = 1, 2, \dots, n

4: $freq [n]$ – const IntegerInput

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

freq = (Integer *) 0

freq [i - 1] \geq 0

, for

i = 1, 2, \dots, n

5: $nd$ – Integer *Output

On exit: the number of distinct failure times,

n_{d}

6: $tp [n]$ – doubleOutput

On exit:

tp [i - 1]

contains the

i

th ordered distinct failure time,

t_{i}

, for

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

7: $p [n]$ – doubleOutput

On exit:

p [i - 1]

contains the Kaplan–Meier estimate of the survival probability,

\hat{S} (t)

, for time

tp [i - 1]

, for

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

8: $psig [n]$ – doubleOutput

On exit:

psig [i - 1]

contains an estimate of the standard deviation of

p [i - 1]

, for

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

9: $fail$ – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_INT_ARG_LT: On entry, $n = 〈value〉$ .
Constraint: $n \geq 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, $ic [〈value〉] = 〈value〉$ . The censor code for an observation must be either 0 or 1.
NE_INVALID_FREQ: On entry, $freq [〈value〉] = 〈value〉$ . The value of frequency for an observation must be $\geq 0$ .

7 Accuracy

The computations are believed to be stable.

8 Parallelism and Performance

Not applicable.

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

NAG Library Function Documentnag_prod_limit_surviv_fn (g12aac)

▸▿ 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 Library Function Document

nag_prod_limit_surviv_fn (g12aac)