naginterfaces.library.surviv.logrank

naginterfaces.library.surviv.logrank(t, ic, grp, ngrp, ifreq=None, wt=None, ldn=None)

logrank calculates the rank statistics, which can include the logrank test, for comparing survival curves.

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

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

Parameters

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

The observed 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.

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

$grp[\text{i}-1]$ contains a flag indicating which group the $\text{i}$th observation belongs in, for $\text{i}=1,2,\dots ,n$.

ngrpint

$g$, the number of groups.

ifreqNone or int, array-like, shape $(:)$, optional

Note: the required length for this argument is determined as follows: if $ifreq\text{is not}None$: $n$; otherwise: $0$.

Optionally, the frequency (number of observations) that each entry in $t$ corresponds to. If $ifreq\text{is}None$ then each entry in $t$ is assumed to correspond to a single observation, i.e., a frequency of $1$ is assumed.

wtNone or float, array-like, shape $(:)$, optional

Note: the required length for this argument is determined as follows: if $wt\text{is not}None$: $ldn$; otherwise: $0$.

Optionally, the $n_d$ weights, $w_i$, where $n_d$ is the number of distinct failure times. If $wt\text{is}None$ then $w_i=1$ for all $i$.

ldnNone or int, optional

Note: if this argument is None then a default value will be used, determined as follows: $n$.

The size of arrays $di$ and $ni$. As $n_d\le n$, if $n_d$ is not known a priori then a value of $\text{n}$ can safely be used for $ldn$.

Returns

tsfloat

$T$, the test statistic.

dfint

$\nu$, the degrees of freedom.

pfloat

$P(X\ge T)$, when $X\sim {\chi }_{\nu }^2$, i.e., the probability associated with $ts$.

obsdfloat, ndarray, shape $\left(ngrp\right)$

$O_i$, the observed number of failures in each group.

exptfloat, ndarray, shape $\left(ngrp\right)$

$E_i$, the expected number of failures in each group.

ndint

$n_d$, the number of distinct failure times.

diint, ndarray, shape $\left(ldn\right)$

The first $nd$ elements of $di$ contain $d_i$, the number of failures, across all groups, at time $t_i$.

niint, ndarray, shape $\left(ldn\right)$

The first $nd$ elements of $ni$ contain $n_i$, the size of the risk set, across all groups, at time $t_i$.

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 2$.

(errno $2$)

On entry, all the times in $t$ are the same.

(errno $3$)

On entry, $ic[⟨value⟩]=⟨value⟩$.

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

(errno $4$)

On entry, $grp[⟨value⟩]=⟨value⟩$ and $ngrp=⟨value⟩$.

Constraint: $1\le grp[i-1]\le ngrp$.

(errno $5$)

On entry, $ngrp=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $2\le ngrp\le n$.

(errno $6$)

On entry, $\text{lfreq}=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $\text{lfreq}=0$ or $\text{lfreq}\ge n$.

(errno $7$)

On entry, $ifreq[⟨value⟩]=⟨value⟩$.

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

(errno $8$)

On entry, $\text{lwt}=⟨value⟩$ and $ldn=⟨value⟩$.

Constraint: $\text{lwt}=0$ or $\text{lwt}\ge ldn$.

(errno $9$)

On entry, $wt[⟨value⟩]=⟨value⟩$.

Constraint: $wt[i-1]\ge 0.0$.

(errno $11$)

The degrees of freedom are zero.

(errno $18$)

On entry, $ldn=⟨value⟩$.

Constraint: $ldn\ge ⟨value⟩$.

(errno $31$)

On entry, all observations are censored.

(errno $41$)

On entry, group $⟨value⟩$ has no observations.

Notes

A survivor function, $S\left(t\right)$, is the probability of surviving to at least time $t$. Given a series of $n$ failure or right-censored times from $g$ groups logrank calculates a rank statistic for testing the null hypothesis

$H_0:S_1\left(t\right)=S_2\left(t\right)=\cdots =S_g\left(t\right),\forall t\le \tau$

where $\tau$ is the largest observed time, against the alternative hypothesis

$H_1:$ at least one of the $S_i\left(t\right)$ differ, for some $t\le \tau$.

Let $t_{\text{i}}$, for $\text{i}=1,2,\dots ,n_d$, denote the list of distinct failure times across all $g$ groups and $w_i$ a series of $n_d$ weights. Let $d_{ij}$ denote the number of failures at time $t_i$ in group $j$ and $n_{ij}$ denote the number of observations in the group $j$ that are known to have not failed prior to time $t_i$, i.e., the size of the risk set for group $j$ at time $t_i$. If a censored observation occurs at time $t_i$ then that observation is treated as if the censoring had occurred slightly after $t_i$ and, therefore, the observation is counted as being part of the risk set at time $t_i$. Finally let

$$d_i=\sum _1^g{d}_{ij}\text{and}{n}_i=\sum _1^g{n}_{ij}\text{.}$$

The (weighted) number of observed failures in the $j$th group, $O_j$, is, therefore, given by

$$O_j=\sum _1^{n_d}{w}_i{d}_{ij}$$

and the (weighted) number of expected failures in the $j$th group, $E_j$, by

$$E_j=\sum _1^{n_d}{w}_i\frac{n_{ij}{d}_i}{n_i}\text{.}$$

If $x$ denotes the vector of differences $x=(O_1-E_1,O_2-E_2,\dots ,O_g-E_g)$ and

$$V_{jk}=\sum _1^{n_d}{w}_i^2\left(\frac{d_i(n_i-d_i)(n_i{n}_{ik}{I}_{jk}-n_{ij}{n}_{ik})}{n_i^2(n_i-1)}\right)$$

where $I_{jk}=1$ if $j=k$ and $0$ otherwise, then the rank statistic, $T$, is calculated as

$$T=x{V}^{-}{x}^T$$

where $V^{-}$ denotes a generalized inverse of the matrix $V$. Under the null hypothesis, $T\sim {\chi }_{\nu }^2$ where the degrees of freedom, $\nu$, is taken as the rank of the matrix $V$.

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

Rostomily, R C, Duong, D, McCormick, K, Bland, M and Berger, M S, 1994, Multimodality management of recurrent adult malignant gliomas: results of a phase II multiagent chemotherapy study and analysis of cytoreductive surgery, Neurosurgery (35), 378