NAG Library Function Document
nag_prod_limit_surviv_fn (g12aac)
1
Purpose
nag_prod_limit_surviv_fn (g12aac) computes the Kaplan–Meier, (or product-limit), estimates of survival probabilities for a sample of failure times.
2
Specification
#include <nag.h> |
#include <nagg12.h> |
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, , is the probability of surviving to at least time with , where is the cumulative distribution function of the failure times. The Kaplan–Meier or product limit estimator provides an estimate of , , from sample of failure times which may be progressively right-censored.
Let , , 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 be . If a failure and a loss (censored observation) occur at the same time , then the failure is treated as if it had occurred slightly before time and the loss as if it had occurred slightly after .
The Kaplan–Meier estimate of the survival probabilities is a step function which in the interval
to
is given by
where
is the number of failures occurring at time
.
nag_prod_limit_surviv_fn (g12aac) computes the Kaplan–Meier estimates and the corresponding estimates of the variances,
, using Greenwood's formula,
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:
– IntegerInput
-
On entry: the number of failure and censored times given in
t.
Constraint:
.
- 2:
– const doubleInput
-
On entry: the failure and censored times; these need not be ordered.
- 3:
– const IntegerInput
-
On entry:
contains the censoring code of the
th observation, for
.
- The th observation is a failure time.
- The th observation is right-censored.
Constraint:
or , for .
- 4:
– 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 or , for .
- 5:
– Integer *Output
-
On exit: the number of distinct failure times, .
- 6:
– doubleOutput
-
On exit: contains the th ordered distinct failure time, , for .
- 7:
– doubleOutput
-
On exit: contains the Kaplan–Meier estimate of the survival probability, , for time , for .
- 8:
– doubleOutput
-
On exit: contains an estimate of the standard deviation of , for .
- 9:
– NagError *Input/Output
-
The NAG error argument (see
Section 3.7 in How to Use the NAG Library and its Documentation).
6
Error Indicators and Warnings
- NE_ALLOC_FAIL
-
Dynamic memory allocation failed.
- NE_INT_ARG_LT
-
On entry, .
Constraint: .
- 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, . The censor code for an observation must be either 0 or 1.
- NE_INVALID_FREQ
-
On entry, . The value of frequency for an observation must be .
7
Accuracy
The computations are believed to be stable.
8
Parallelism and Performance
nag_prod_limit_surviv_fn (g12aac) is not threaded in any implementation.
If there are no censored observations, , reduces to the ordinary binomial estimate of the probability of survival at time .
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).
10.1
Program Text
Program Text (g12aace.c)
10.2
Program Data
Program Data (g12aace.d)
10.3
Program Results
Program Results (g12aace.r)