NAG Library Routine Document

G12AAF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     N – INTEGERInput

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

Constraint: $\mathbf{N}\ge 2$.

2:     T(N) – REAL (KIND=nag_wp) arrayInput

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

3:     IC(N) – INTEGER arrayInput

On entry: $\mathbf{IC}\left(\mathit{i}\right)$ contains the censoring code of the $\mathit{i}$th observation, for $\mathit{i}=1,2,\dots ,\mathbf{N}$.

$\mathbf{IC}\left(i\right)=0$

The $i$th observation is a failure time.

$\mathbf{IC}\left(i\right)=1$

The $i$th observation is right-censored.

Constraint: $\mathbf{IC}\left(\mathit{i}\right)=0$ or $1$, for $\mathit{i}=1,2,\dots ,\mathbf{N}$.

4:     FREQ – CHARACTER(1)Input

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

$\mathbf{FREQ}=\text{'F'}$

Frequencies are provided for each failure and censored time.

$\mathbf{FREQ}=\text{'S'}$

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

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

5:     IFREQ($*$) – INTEGER arrayInput

Note: the dimension of the array IFREQ must be at least $\mathbf{N}$ if $\mathbf{FREQ}=\text{'F'}$ and at least $1$ if $\mathbf{FREQ}=\text{'S'}$.

On entry: if $\mathbf{FREQ}=\text{'F'}$, $\mathbf{IFREQ}\left(i\right)$ must contain the frequency of the $i$th observation.

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

Constraint: if $\mathbf{FREQ}=\text{'F'}$, $\mathbf{IFREQ}\left(\mathit{i}\right)\ge 0$, for $\mathit{i}=1,2,\dots ,\mathbf{N}$.

6:     ND – INTEGEROutput

On exit: the number of distinct failure times, $n_d$.

7:     TP(N) – REAL (KIND=nag_wp) arrayOutput

On exit: $\mathbf{TP}\left(\mathit{i}\right)$ contains the $\mathit{i}$th ordered distinct failure time, $t_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n_{\mathrm{d}}$.

8:     P(N) – REAL (KIND=nag_wp) arrayOutput

On exit: $\mathbf{P}\left(\mathit{i}\right)$ contains the Kaplan–Meier estimate of the survival probability, $\hat{S}\left(t\right)$, for time $\mathbf{TP}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,n_d$.

9:     PSIG(N) – REAL (KIND=nag_wp) arrayOutput

On exit: $\mathbf{PSIG}\left(\mathit{i}\right)$ contains an estimate of the standard deviation of $\mathbf{P}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,n_d$.

10:   IWK(N) – INTEGER arrayWorkspace

11:   IFAIL – INTEGERInput/Output

On entry: IFAIL must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is $0$. When the value $-\mathbf{1}\text{ or }\mathbf{1}$ is used it is essential to test the value of IFAIL on exit.

On exit: $\mathbf{IFAIL}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and Warnings

$\mathbf{IFAIL}=1$

On entry,

$\mathbf{N}<2$.

$\mathbf{IFAIL}=2$

On entry,

$\mathbf{FREQ}\ne \text{'F'}$ or $\text{'S'}$.

$\mathbf{IFAIL}=3$

On entry,

$\mathbf{IC}\left(i\right)\ne 0$ or $1$, for some $i=1,2,\dots ,\mathbf{N}$.

$\mathbf{IFAIL}=4$

On entry,

$\mathbf{FREQ}=\text{'F'}$ and $\mathbf{IFREQ}\left(i\right)<0$, for some $i=1,2,\dots ,\mathbf{N}$.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (g12aafe.f90)

9.2  Program Data

Program Data (g12aafe.d)

9.3  Program Results

Program Results (g12aafe.r)