naginterfaces.library.surviv.kaplanmeier

naginterfaces.library.surviv.kaplanmeier(t, ic, freq, ifreq)

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

For full information please refer to the NAG Library document for g12aa

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g12/g12aaf.html

Parameters

tfloat, array-like, shape $\left(n\right)$

The failure and censored times; these need not be ordered.

icint, array-like, shape $\left(n\right)$

$ic[\text{i}-1]$ contains the censoring code of the $\text{i}$th observation, for $\text{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.

freqstr, length 1

Indicates whether frequencies are provided for each time point.

$freq=\text{'F'}$

Frequencies are provided for each failure and censored time.

$freq=\text{'S'}$

The failure and censored times are considered as single observations, i.e., a frequency of $1$ is assumed.

ifreqint, array-like, shape $(:)$

Note: the required length for this argument is determined as follows: if $freq=\text{'F'}$: $n$; if $freq=\text{'S'}$: $1$; otherwise: $0$.

If $freq=\text{'F'}$, $ifreq\left[i\right]$ must contain the frequency of the $i$th observation.

If $ifreq=\text{'S'}$, a frequency of $1$ is assumed and $ifreq$ is not referenced.

Returns

ndint

The number of distinct failure times, $n_d$.

tpfloat, ndarray, shape $\left(n\right)$

$tp[\text{i}-1]$ contains the $\text{i}$th ordered distinct failure time, $t_{\text{i}}$, for $\text{i}=1,2,\dots ,n_d$.

pfloat, ndarray, shape $\left(n\right)$

$p[\text{i}-1]$ contains the Kaplan–Meier estimate of the survival probability, $\hat{S}\left(t\right)$, for time $tp[\text{i}-1]$, for $\text{i}=1,2,\dots ,n_d$.

psigfloat, ndarray, shape $\left(n\right)$

$psig[\text{i}-1]$ contains an estimate of the standard deviation of $p[\text{i}-1]$, for $\text{i}=1,2,\dots ,n_d$.

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 2$.

(errno $2$)

On entry, $freq=⟨value⟩$.

Constraint: $freq=\text{'F'}$ or $\text{'S'}$.

(errno $3$)

On entry, $i=⟨value⟩$ and $ic[i-1]=⟨value⟩$.

Constraint: $ic[i-1]=0$ or $1$.

(errno $4$)

On entry, $i=⟨value⟩$ and $ifreq[i-1]=⟨value⟩$.

Constraint: $ifreq[i-1]\ge 0$.

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

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)$, $\hat{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

$$\hat{S}\left(t\right)=\prod _{j=1}^i\left(\frac{n_j-d_j}{n_j}\right)\text{,}$$

where $d_j$ is the number of failures occurring at time $t_j$.

kaplanmeier computes the Kaplan–Meier estimates and the corresponding estimates of the variances, $\widehat{\text{var}}\left(\hat{S}\left(t\right)\right)$, using Greenwood’s formula,

$$\widehat{var}\left(\hat{S}\left(t\right)\right)=\hat{S}{\left(t\right)}^2\sum _{j=1}^i\frac{d_j}{n_j(n_j-d_j)}\text{.}$$

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