Package 'survELtest' reference manual

Title:	Comparing Multiple Survival Functions with Crossing Hazards
Description:	Computing the one-sided/two-sided integrated/maximally selected EL statistics for simultaneous testing, the one-sided/two-sided EL tests for pointwise testing, and an initial test that precedes one-sided testing to exclude the possibility of crossings or alternative orderings among the survival functions.
Authors:	Hsin-wen Chang [aut, cre] <[email protected]>
Maintainer:	Guo-You Lan <[email protected]>
License:	GPL (>= 2)
Version:	2.0.1
Built:	2024-10-17 03:13:28 UTC
Source:	https://github.com/news11/surveltest

Simulated survival data with crossing hazard functions from the piecewise exponential distribution

Description

The data frame hazardcross is obtained as follows. The survival time is generated from the piecewise exponential model displayed in the left column of Figure 1 in Chang and McKeague (2016). The censoring distributions (the same in each arm) is specified to be uniform with administrative censoring at $t = 10$ , and a censoring rate of $25\%$ in the first group.

Usage

hazardcross
hazardcross

Format

The hazardcross is a data frame with 100 observations of 3 variables, and has the following columns:

time the observed times to first remission and censoring times
censor the censoring indicator
group the grouping variable

References

H. Chang, I.W. McKeague, "Empirical likelihood based tests for stochastic ordering under right censorship," Electronic Journal of Statistics, Vol. 10, No. 2, pp. 2511-2536, (2016).

Simulated survival data with crossing hazard functions from the Weibull distribution

Description

The data frame hazardcross_Weibull is obtained as follows. The survival time is generated from the Weibull model displayed as the solid and dashed lines in the right panel of Figure 1 in Chang and McKeague (2019). The censoring distributions (the same in each arm) is specified to be uniform with administrative censoring at $t = 10$ , and a censoring rate of $25\%$ in the first group.

Usage

hazardcross_Weibull
hazardcross_Weibull

Format

The hazardcross_Weibull is a data frame with 100 observations of 3 variables, and has the following columns:

time the observed times to first remission and censoring times
censor the censoring indicator
group the grouping variable

References

H. Chang, I.W. McKeague, "Nonparametric testing for multiple survival functions with non-inferiority margins," Annals of Statistics, Vol. 47, No. 1, pp. 205-232, (2019).

Severe alcoholic hepatitis data

Description

The data frame hepatitis is obtained by digitizing the published Kaplan-Meier curves in Nguyen-Khac et al. (2011). The method of digitizing is described in Guyot et al. (2012). See intELtest for the application.

Usage

hepatitis
hepatitis

Format

The hepatitis is a data frame with 174 observations of 3 variables, and has the following columns:

time the observed survival and censoring times
censor the censoring indicator
group the grouping variable

Source

Nguyen-Khac et al., "Glucocorticoids plus N-Acetylcysteine in Severe Alcoholic Hepatitis," The New England Journal of Medicine, Vol. 365, No. 19, pp. 1781-1789 (2011). http://www.nejm.org/doi/full/10.1056/NEJMoa1101214#t=article

References

P. Guyot, A. E. Ades, M. J. N. M. Ouwens, and N. J. Welton, "Enhanced secondary analysis of survival data: reconstructing the data from published Kaplan-Meier survival curves," BMC Medical Research Methodology, 12(1):9. http://bmcmedresmethodol.biomedcentral.com/articles/10.1186/1471-2288-12-9

Nguyen-Khac et al., "Glucocorticoids plus N-Acetylcysteine in Severe Alcoholic Hepatitis," The New England Journal of Medicine, Vol. 365, No. 19, pp. 1781-1789 (2011). http://www.nejm.org/doi/full/10.1056/NEJMoa1101214#t=article
P. Guyot, A. E. Ades, M. J. N. M. Ouwens, and N. J. Welton, "Enhanced secondary analysis of survival data: reconstructing the data from published Kaplan-Meier survival curves," BMC Medical Research Methodology, 12(1):9. http://bmcmedresmethodol.biomedcentral.com/articles/10.1186/1471-2288-12-9

The integrated EL test

Description

intELtest gives a class of integrated EL statistics:

$\sum_{i=1}^{m}w_i\cdot \{-2\log R(t_i)\},$

where $R(t)$ is the EL ratio that compares the survival functions at each given time $t$ , $w_i$ is the weight at each $t_i$ , and $0<t_1<\ldots<t_m<\infty$ are the (ordered) observed uncensored times at which the Kaplan–Meier estimate is positive and less than $1$ for each sample.

Usage

intELtest(
  formula,
  data = NULL,
  group_order = NULL,
  t1 = 0,
  t2 = Inf,
  sided = 2,
  nboot = 1000,
  wt = "p.event",
  alpha = 0.05,
  seed = 1011,
  nlimit = 200
)
intELtest(
  formula,
  data = NULL,
  group_order = NULL,
  t1 = 0,
  t2 = Inf,
  sided = 2,
  nboot = 1000,
  wt = "p.event",
  alpha = 0.05,
  seed = 1011,
  nlimit = 200
)

Arguments

`formula`	a formula object with a `Surv` object as the response on the left of the `~` operator and the grouping variable as the term on the right. The `Surv` object involves two variables: the observed survival and censoring times, and the censoring indicator, which takes a value of $1$ if the observed time is uncensored and $0$ otherwise. The grouping variable takes different values for different groups.
`data`	an optional data frame containing the variables in the `formula`: the observed survival and censoring times, the censoring indicator, and the grouping variable. If not found in `data`, the variables in the `formula` should be already defined by the user or in attached `R` objects. The default is the data frame with three columns of variables taken from the formula: column 1 contains the observed survival and censoring times, column 2 the censoring indicator, and column 3 the grouping variable.
`group_order`	a $k$ -vector containing the values of the grouping variable, with the $j$ -th element being the group hypothesized to have the $j$ -th highest survival rates, $j=1,\ldots,k$ . The default is the vector of sorted grouping variables.
`t1`	the first endpoint of a prespecified time interval, if any, to which the comparison of the survival functions is restricted. The default value is $0$ .
`t2`	the second endpoint of a prespecified time interval, if any, to which the comparison of the survival functions is restricted. The default value is $\infty$ .
`sided`	$2$ if two-sided test, and $1$ if one-sided test. The default value is $2$ .
`nboot`	the number of bootstrap replications in calculating critical values for the tests. The default value is $1000$ .
`wt`	the name of the weight for the integrated EL statistics: `"p.event"`, `"dF"`, or `"dt"`. The default is `"p.event"`.
`alpha`	the pre-specified significance level of the tests. The default value is $0.05$ .
`seed`	the seed for the random number generator in `R`, for generating bootstrap samples needed to calculate the critical values for the tests. The default value is $1011$ .
`nlimit`	a number used to calculate `nsplit=` $m$ `/nlimit`, the number of parts into which the calculation of the `nboot` bootstrap replications is split. The use of this variable can make computation faster when the number of time points $m$ is large. The default value for `nlimit` is 200.

Details

There are three options for the weight $w_i$ :

(wt = "p.event")
This default option is an objective weight,

$w_i=\frac{d_i}{n},$

which assigns weight proportional to the number of events $d_i$ at each observed uncensored time $t_i$ . Here $n$ is the total sample size.
(wt = "dF")
Inspired by the integral-type statistics considered in Barmi and McKeague (2013), another weigth function is

$w_i= \hat{F}(t_i)-\hat{F}(t_{i-1}),$

for $i=1,\ldots,m$ , where $\hat{F}(t)=1-\hat{S}(t)$ , $\hat{S}(t)$ is the pooled KM estimator, and $t_0 \equiv 0$ . This reduces to the objective weight when there is no censoring. The resulting $I_n$ can be seen as an empirical version of the expected negative two times log EL ratio under $H_0$ .
(wt = "dt")
Inspired by the integral-type statistics considered in Pepe and Fleming (1989), another weight function is

$w_i= t_{i+1}-t_i,$

for $i=1,\ldots,m$ , where $t_{m+1} \equiv t_{m}$ . This gives more weight to the time intervals where there are fewer observed uncensored times, but can be affected by extreme observations.

Value

intELtest returns a intELtest object, a list with 15 elements:

call the function call
teststat the resulting integrated EL statistics
critval the critical value based on bootstrap
pvalue the p-value of the test
formula the value of the input argument of intELtest
data the value of the input argument of intELtest
group_order the value of the input argument of intELtest
t1 the value of the input argument of intELtest
t2 the value of the input argument of intELtest
sided the value of the input argument of intELtest
nboot the value of the input argument of intELtest
wt the value of the input argument of intELtest
alpha the value of the input argument of intELtest
seed the value of the input argument of intELtest
nlimit the value of the input argument of intELtest

Methods defined for intELtest objects are provided for print and summary.

References

H. Chang, I.W. McKeague, "Nonparametric testing for multiple survival functions with non-inferiority margins," Annals of Statistics, Vol. 47, No. 1, pp. 205-232, (2019).
M. S. Pepe and T. R. Fleming, "Weighted Kaplan-Meier Statistics: A Class of Distance Tests for Censored Survival Data," Biometrics, Vol. 45, No. 2, pp. 497-507 (1989). https://www.jstor.org/stable/2531492?seq=1#page_scan_tab_contents
H. E. Barmi and I.W. McKeague, "Empirical likelihood-based tests for stochastic ordering," Bernoulli, Vol. 19, No. 1, pp. 295-307 (2013). https://projecteuclid.org/euclid.bj/1358531751

Examples

library(survELtest)
intELtest(survival::Surv(hepatitis$time, hepatitis$censor) ~ hepatitis$group)

## OUTPUT:
## Call:
## intELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group)
## 
## Two-sided integrated EL test statistic = 1.42, p = 0.007
library(survELtest)
intELtest(survival::Surv(hepatitis$time, hepatitis$censor) ~ hepatitis$group)

## OUTPUT:
## Call:
## intELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group)
## 
## Two-sided integrated EL test statistic = 1.42, p = 0.007

The test that excludes the possibility of crossings or alternative orderings among the survival functions

Description

The test nocrossings should be used before one-sided testing via intELtest or supELtest to exclude the possibility of crossings or alternative orderings among the survival functions.

Usage

nocrossings(
  formula,
  data = NULL,
  group_order = NULL,
  t1 = 0,
  t2 = Inf,
  sided = 2,
  nboot = 1000,
  alpha = 0.05,
  seed = 1011,
  nlimit = 200
)
nocrossings(
  formula,
  data = NULL,
  group_order = NULL,
  t1 = 0,
  t2 = Inf,
  sided = 2,
  nboot = 1000,
  alpha = 0.05,
  seed = 1011,
  nlimit = 200
)

Arguments

`formula`	a formula object with a `Surv` object as the response on the left of the `~` operator and the grouping variable as the term on the right. The `Surv` object involves two variables: the observed survival and censoring times, and the censoring indicator, which takes a value of $1$ if the observed time is uncensored and $0$ otherwise. The grouping variable takes different values for different groups.
`data`	an optional data frame containing the variables in the `formula`: the observed survival and censoring times, the censoring indicator, and the grouping variable. If not found in `data`, the variables in the `formula` should be already defined by the user or in attached `R` objects. The default is the data frame with three columns of variables taken from the formula: column 1 contains the observed survival and censoring times, column 2 the censoring indicator, and column 3 the grouping variable.
`group_order`	a $k$ -vector containing the values of the grouping variable, with the $j$ -th element being the group hypothesized to have the $j$ -th highest survival rates, $j=1,\ldots,k$ . The default is the vector of sorted grouping variables.
`t1`	the first endpoint of a prespecified time interval, if any, to which the comparison of the survival functions is restricted. The default value is $0$ .
`t2`	the second endpoint of a prespecified time interval, if any, to which the comparison of the survival functions is restricted. The default value is $\infty$ .
`sided`	$2$ if two-sided test, and $1$ if one-sided test. The default value is $2$ .
`nboot`	the number of bootstrap replications in calculating critical values for the tests. The default value is $1000$ .
`alpha`	the pre-specified significance level of the tests. The default value is $0.05$ .
`seed`	the seed for the random number generator in `R`, for generating bootstrap samples needed to calculate the critical values for the tests. The default value is $1011$ .
`nlimit`	a number used to calculate `nsplit=` $m$ `/nlimit`, the number of parts into which the calculation of the `nboot` bootstrap replications is split. The use of this variable can make computation faster when the number of time points $m$ is large. The default value for `nlimit` is 200.

Value

nocrossings returns a nocrossings object, a list with 12 elements:

call the function call
decision $1$ for rejection of the null hypothesis that there are crossings or alternative orderings among the survival functions, and $0$ otherwise
formula the value of the input argument of nocrossings
data the value of the input argument of nocrossings
group_order the value of the input argument of nocrossings
t1 the value of the input argument of nocrossings
t2 the value of the input argument of nocrossings
sided the value of the input argument of nocrossings
nboot the value of the input argument of nocrossings
alpha the value of the input argument of nocrossings
seed the value of the input argument of nocrossings
nlimit the value of the input argument of nocrossings

Methods defined for nocrossings objects are provided for print and summary.

References

H. Chang, I.W. McKeague, "Empirical likelihood based tests for stochastic ordering under right censorship," Electronic Journal of Statistics, Vol. 10, No. 2, pp. 2511-2536 (2016).
H. Chang, I.W. McKeague, "Nonparametric testing for multiple survival functions with non-inferiority margins," Annals of Statistics, Vol. 47, No. 1, pp. 205-232, (2019).

Examples

library(survELtest)
nocrossings(survival::Surv(hepatitis$time, hepatitis$censor)~
    hepatitis$group, sided = 1)

## OUTPUT:
## Call:
## nocrossings(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Decision = 1
library(survELtest)
nocrossings(survival::Surv(hepatitis$time, hepatitis$censor)~
    hepatitis$group, sided = 1)

## OUTPUT:
## Call:
## nocrossings(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Decision = 1

Print an intELtest object

Description

Print the integrated EL statistics and the p-value of the test.

Usage

## S3 method for class 'intELtest'
print(x, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)
## S3 method for class 'intELtest'
print(x, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)

Arguments

`x`	the result of a call to the `intELtest` function
`digits`	significant digits to print, the default value is `max(3L, getOption("digits") - 3L)`
`quiet`	a logical indicating whether to reduce the amount of output or not, the default value is `FALSE`
`...`	for future method

Examples

library(survELtest)
result = intELtest(survival::Surv(hepatitis$time, hepatitis$censor) ~ hepatitis$group)
print(result)

## OUTPUT:
## Call:
## intELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group)
## 
## Two-sided integrated EL test statistic = 1.42, p = 0.007
library(survELtest)
result = intELtest(survival::Surv(hepatitis$time, hepatitis$censor) ~ hepatitis$group)
print(result)

## OUTPUT:
## Call:
## intELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group)
## 
## Two-sided integrated EL test statistic = 1.42, p = 0.007

Print a nocrossings object

Description

Returns the decision for rejection of the null hypothesis that there are crossings or alternative orderings among the survival functions.

Usage

## S3 method for class 'nocrossings'
print(x, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)
## S3 method for class 'nocrossings'
print(x, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)

Arguments

`x`	the result of a call to the `nocrossings` function
`digits`	significant digits to print, the default value is `max(3L, getOption("digits") - 3L)`
`quiet`	a logical indicating whether to reduce the amount of output or not, the default value is `FALSE`
`...`	for future method

Examples

library(survELtest)
result = nocrossings(survival::Surv(hepatitis$time, hepatitis$censor)~
             hepatitis$group, sided = 1)
print(result)

## OUTPUT:
## Call:
## nocrossings(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Decision = 1
library(survELtest)
result = nocrossings(survival::Surv(hepatitis$time, hepatitis$censor)~
             hepatitis$group, sided = 1)
print(result)

## OUTPUT:
## Call:
## nocrossings(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Decision = 1

Print a ptwiseELtest object

Description

Print some summary statistics for the observed uncensored time points, and the decisions, statistics, and critical values of the pointwise EL tests at those time points.

Usage

## S3 method for class 'ptwiseELtest'
print(x, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)
## S3 method for class 'ptwiseELtest'
print(x, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)

Arguments

`x`	the result of a call to the `ptwiseELtest` function
`digits`	significant digits to print, the default value is `max(3L, getOption("digits") - 3L)`
`quiet`	a logical indicating whether to reduce the amount of output or not, the default value is `FALSE`
`...`	for future method

Examples

library(survELtest)
result = ptwiseELtest(survival::Surv(hepatitis$time, hepatitis$censor)~
             hepatitis$group, sided = 1)
print(result)

## OUTPUT:
## Call:
## ptwiseELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Range of time_pts is from 5.2 to 153.1
## 30 out of 45 decisions are 1, the other 15 decisions are 0
## -----
## Summary of stat_ptwise:
##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
##   0.000   2.293   3.694   4.263   6.288  10.360 
## -----
## Summary of critval_ptwise:
##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
##   2.117   2.346   2.483   2.509   2.669   2.951
library(survELtest)
result = ptwiseELtest(survival::Surv(hepatitis$time, hepatitis$censor)~
             hepatitis$group, sided = 1)
print(result)

## OUTPUT:
## Call:
## ptwiseELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Range of time_pts is from 5.2 to 153.1
## 30 out of 45 decisions are 1, the other 15 decisions are 0
## -----
## Summary of stat_ptwise:
##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
##   0.000   2.293   3.694   4.263   6.288  10.360 
## -----
## Summary of critval_ptwise:
##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.
##   2.117   2.346   2.483   2.509   2.669   2.951

Print a supELtest object

Description

Print the maximally selected EL statistics and the p-value of the test.

Usage

## S3 method for class 'supELtest'
print(x, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)
## S3 method for class 'supELtest'
print(x, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)

Arguments

`x`	the result of a call to the `supELtest` function
`digits`	significant digits to print, the default value is `max(3L, getOption("digits") - 3L)`
`quiet`	a logical indicating whether to reduce the amount of output or not, the default value is `FALSE`
`...`	for future method

Examples

library(survELtest)
nocrossings(survival::Surv(hepatitis$time, hepatitis$censor)~
    hepatitis$group, sided = 1)

## OUTPUT:
## Call:
## nocrossings(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Decision = 1

## A decision value of 1 means the case of crossings or alternative orderings among the 
## survival functions is excluded. Thus, we can proceed to the one-sided test.

result = supELtest(survival::Surv(hepatitis$time, hepatitis$censor)~
             hepatitis$group, sided = 1)
print(result)

## OUTPUT:
## Call:
## supELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~  
##     hepatitis$group, sided = 1)
## 
## One-sided maximally selected EL test statistic = 10.36, p = 0.006
library(survELtest)
nocrossings(survival::Surv(hepatitis$time, hepatitis$censor)~
    hepatitis$group, sided = 1)

## OUTPUT:
## Call:
## nocrossings(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Decision = 1

## A decision value of 1 means the case of crossings or alternative orderings among the 
## survival functions is excluded. Thus, we can proceed to the one-sided test.

result = supELtest(survival::Surv(hepatitis$time, hepatitis$censor)~
             hepatitis$group, sided = 1)
print(result)

## OUTPUT:
## Call:
## supELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~  
##     hepatitis$group, sided = 1)
## 
## One-sided maximally selected EL test statistic = 10.36, p = 0.006

The pointwise EL testing

Description

ptwiseELtest gives pointwise EL testing to compare the survival curves at each time point.

Usage

ptwiseELtest(
  formula,
  data = NULL,
  group_order = NULL,
  t1 = 0,
  t2 = Inf,
  sided = 2,
  nboot = 1000,
  alpha = 0.05,
  seed = 1011,
  nlimit = 200
)
ptwiseELtest(
  formula,
  data = NULL,
  group_order = NULL,
  t1 = 0,
  t2 = Inf,
  sided = 2,
  nboot = 1000,
  alpha = 0.05,
  seed = 1011,
  nlimit = 200
)

Arguments

`formula`	a formula object with a `Surv` object as the response on the left of the `~` operator and the grouping variable as the term on the right. The `Surv` object involves two variables: the observed survival and censoring times, and the censoring indicator, which takes a value of $1$ if the observed time is uncensored and $0$ otherwise. The grouping variable takes different values for different groups.
`data`	an optional data frame containing the variables in the `formula`: the observed survival and censoring times, the censoring indicator, and the grouping variable. If not found in `data`, the variables in the `formula` should be already defined by the user or in attached `R` objects. The default is the data frame with three columns of variables taken from the formula: column 1 contains the observed survival and censoring times, column 2 the censoring indicator, and column 3 the grouping variable.
`group_order`	a $k$ -vector containing the values of the grouping variable, with the $j$ -th element being the group hypothesized to have the $j$ -th highest survival rates, $j=1,\ldots,k$ . The default is the vector of sorted grouping variables.
`t1`	the first endpoint of a prespecified time interval, if any, to which the comparison of the survival functions is restricted. The default value is $0$ .
`t2`	the second endpoint of a prespecified time interval, if any, to which the comparison of the survival functions is restricted. The default value is $\infty$ .
`sided`	$2$ if two-sided test, and $1$ if one-sided test. The default value is $2$ .
`nboot`	the number of bootstrap replications in calculating critical values for the tests. The default value is $1000$ .
`alpha`	the pre-specified significance level of the tests. The default value is $0.05$ .
`seed`	the seed for the random number generator in `R`, for generating bootstrap samples needed to calculate the critical values for the tests. The default value is $1011$ .
`nlimit`	a number used to calculate `nsplit=` $m$ `/nlimit`, the number of parts into which the calculation of the `nboot` bootstrap replications is split. The use of this variable can make computation faster when the number of time points $m$ is large. The default value for `nlimit` is 200.

Value

ptwiseELtest returns a ptwiseELtest object, a list with 12 elements:

call the function call
result_dataframe a dataframe with time_pts in the first column, decision in the second column, stat_ptwise in the third column and critval_ptwise in the fourth column.
- time_pts a vector containing the observed uncensored time points at which the Kaplan—Meier estimate is positive and less than $1$ for each sample.
- decision a vector containing the decisions of the pointwise EL tests at time_pts. The decision at each of time_pts is $1$ for rejection of the null hypothesis that the survival functions are the same at the specific time point, and $0$ otherwise.
- stat_ptwise a vector containing the pointwise EL statistics at time_pts.
- critval_ptwise a vector containing the critical values for pointwise EL testing at time_pts.
formula the value of the input argument of ptwiseELtest
data the value of the input argument of ptwiseELtest
group_order the value of the input argument of ptwiseELtest
t1 the value of the input argument of ptwiseELtest
t2 the value of the input argument of ptwiseELtest
sided the value of the input argument of ptwiseELtest
nboot the value of the input argument of ptwiseELtest
alpha the value of the input argument of ptwiseELtest
seed the value of the input argument of ptwiseELtest
nlimit the value of the input argument of ptwiseELtest

Methods defined for ptwiseELtest objects are provided for print and summary.

Examples

library(survELtest)
ptwiseELtest(survival::Surv(hepatitis$time, hepatitis$censor)~
    hepatitis$group, sided = 1)

## OUTPUT:
## Call:
## ptwiseELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Range of time_pts is from 5.2 to 153.1
## 30 out of 45 decisions are 1, the other 15 decisions are 0
## -----
## Summary of stat_ptwise:
##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.  
##   0.000   2.293   3.694   4.263   6.288  10.360 
## -----
## Summary of critval_ptwise:
##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.  
##   2.117   2.346   2.483   2.509   2.669   2.951 
library(survELtest)
ptwiseELtest(survival::Surv(hepatitis$time, hepatitis$censor)~
    hepatitis$group, sided = 1)

## OUTPUT:
## Call:
## ptwiseELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Range of time_pts is from 5.2 to 153.1
## 30 out of 45 decisions are 1, the other 15 decisions are 0
## -----
## Summary of stat_ptwise:
##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.  
##   0.000   2.293   3.694   4.263   6.288  10.360 
## -----
## Summary of critval_ptwise:
##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max.  
##   2.117   2.346   2.483   2.509   2.669   2.951

Summary function for intELtest object

Description

Returns a list containing the integrated EL statistics, the critical value based on bootstrap, and the p-value of the test.

Usage

## S3 method for class 'intELtest'
summary(object, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)
## S3 method for class 'intELtest'
summary(object, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)

Arguments

`object`	the result of a call to the `intELtest` function
`digits`	significant digits to print, the default value is `max(3L, getOption("digits") - 3L)`
`quiet`	a logical indicating whether to reduce the amount of output or not, the default value is `FALSE`
`...`	for future method

Value

summary.intELtest returns a list with following components:

call the statement used to create the intELtest object
teststat the resulting integrated EL statistics
critval the critical value based on bootstrap
pvalue the p-value of the test
sided the value of the input argument of intELtest
alpha the value of the input argument of intELtest

Examples

library(survELtest)
result = intELtest(survival::Surv(hepatitis$time, hepatitis$censor) ~ hepatitis$group)
summary(result)

## OUTPUT:
## Call:
## intELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group)
## 
## Two-sided integrated EL test statistic = 1.42, p = 0.007,
## critical value based on bootstrap = 0.875 at a significance level of 0.05
library(survELtest)
result = intELtest(survival::Surv(hepatitis$time, hepatitis$censor) ~ hepatitis$group)
summary(result)

## OUTPUT:
## Call:
## intELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group)
## 
## Two-sided integrated EL test statistic = 1.42, p = 0.007,
## critical value based on bootstrap = 0.875 at a significance level of 0.05

Summary function for nocrossings object

Description

Returns the decision for rejection of the null hypothesis that there are crossings or alternative orderings among the survival functions.

Usage

## S3 method for class 'nocrossings'
summary(object, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)
## S3 method for class 'nocrossings'
summary(object, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)

Arguments

`object`	the result of a call to the `nocrossings` function
`digits`	significant digits to print, the default value is `max(3L, getOption("digits") - 3L)`
`quiet`	a logical indicating whether to reduce the amount of output or not, the default value is `FALSE`
`...`	for future method

Value

summary.nocrossings returns a list with following components:

call the statement used to create the nocrossings object
decision $1$ for rejection of the null hypothesis that there are crossings or alternative orderings among the survival functions, and $0$ otherwise

Examples

library(survELtest)
result = nocrossings(survival::Surv(hepatitis$time, hepatitis$censor)~
          hepatitis$group, sided = 1)
summary(result)

## OUTPUT:
## Call:
## nocrossings(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Decision = 1
library(survELtest)
result = nocrossings(survival::Surv(hepatitis$time, hepatitis$censor)~
          hepatitis$group, sided = 1)
summary(result)

## OUTPUT:
## Call:
## nocrossings(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Decision = 1

Summary function for ptwiseELtest object

Description

Returns a list with a data frame containing the observed uncensored time points, and the decisions, statistics, and critical values of the pointwise EL tests at those time points.

Usage

## S3 method for class 'ptwiseELtest'
summary(object, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)
## S3 method for class 'ptwiseELtest'
summary(object, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)

Arguments

`object`	the result of a call to the `ptwiseELtest` function
`digits`	significant digits to print, the default value is `max(3L, getOption("digits") - 3L)`
`quiet`	a logical indicating whether to reduce the amount of output or not, the default value is `FALSE`
`...`	for future method

Value

summary.ptwiseELtest returns a list with following components:

call the statement used to create the ptwiseELtest object
result_dataframe a dataframe with time_pts in the first column, decision in the second column, stat_ptwise in the third column and critval_ptwise in the fourth column.
- time_pts a vector containing the observed uncensored time points at which the Kaplan—Meier estimate is positive and less than $1$ for each sample.
- decision a vector containing the decisions of the pointwise EL tests at time_pts. The decision at each of time_pts is $1$ for rejection of the null hypothesis that the survival functions are the same at the specific time point, and $0$ otherwise.
- stat_ptwise a vector containing the pointwise EL statistics at time_pts.
- critval_ptwise a vector containing the critical values for pointwise EL testing at time_pts.

Examples

library(survELtest)
result = ptwiseELtest(survival::Surv(hepatitis$time, hepatitis$censor)~
             hepatitis$group, sided = 1)
summary(result)

## OUTPUT:
## Call:
## ptwiseELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~  
##     hepatitis$group, sided = 1)
## 
##    time_pts decision stat_ptwise critval_ptwise
## 1       5.2        0      0.3005          2.951
## 2       9.7        0      0.0000          2.833
## 3      12.9        0      0.1627          2.748
## 4      14.0        0      0.6114          2.583
## 5      14.9        0      2.0010          2.780
## 6      15.7        1      3.7873          2.764
## 7      18.0        1      3.0722          2.652
## 8      18.9        0      1.8878          2.454
## 9      19.2        1      2.5896          2.339
## 10     19.7        0      1.6133          2.601
## 11     20.0        0      2.2393          2.383
## 12     21.7        1      3.6936          2.192
## 13     24.0        1      4.5083          2.300
## 14     24.9        1      5.3743          2.391
## 15     26.0        1      6.2879          2.253
## 16     26.9        1      9.2827          2.117
## 17     27.8        1     10.3581          2.209
## 18     28.0        1      6.9862          2.317
## 19     30.0        1      7.9190          2.346
## 20     31.2        1      6.5074          2.318
## 21     32.1        1      4.9709          2.310
## 22     34.1        1      5.7455          2.360
## 23     36.1        1      6.5627          2.244
## 24     44.9        1      5.4374          2.363
## 25     45.2        1      6.2240          2.416
## 26     47.8        1      7.0519          2.409
## 27     54.1        1      7.9198          2.427
## 28     54.9        1      6.7260          2.310
## 29     58.1        1      7.5667          2.456
## 30     59.8        1      7.2524          2.483
## 31     63.2        1      6.1770          2.511
## 32     70.4        1      5.2110          2.562
## 33     76.1        1      4.3461          2.683
## 34     80.1        1      3.5753          2.744
## 35     81.3        1      2.8926          2.467
## 36     82.1        0      2.2925          2.669
## 37     90.1        1      2.7908          2.543
## 38     92.1        0      2.2120          2.523
## 39     95.0        0      1.7079          2.755
## 40     99.0        0      2.1383          2.762
## 41    108.2        0      2.6206          2.652
## 42    109.9        1      3.1475          2.630
## 43    117.0        0      2.5398          2.646
## 44    148.8        1      3.0555          2.685
## 45    153.1        0      2.4658          2.774
library(survELtest)
result = ptwiseELtest(survival::Surv(hepatitis$time, hepatitis$censor)~
             hepatitis$group, sided = 1)
summary(result)

## OUTPUT:
## Call:
## ptwiseELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~  
##     hepatitis$group, sided = 1)
## 
##    time_pts decision stat_ptwise critval_ptwise
## 1       5.2        0      0.3005          2.951
## 2       9.7        0      0.0000          2.833
## 3      12.9        0      0.1627          2.748
## 4      14.0        0      0.6114          2.583
## 5      14.9        0      2.0010          2.780
## 6      15.7        1      3.7873          2.764
## 7      18.0        1      3.0722          2.652
## 8      18.9        0      1.8878          2.454
## 9      19.2        1      2.5896          2.339
## 10     19.7        0      1.6133          2.601
## 11     20.0        0      2.2393          2.383
## 12     21.7        1      3.6936          2.192
## 13     24.0        1      4.5083          2.300
## 14     24.9        1      5.3743          2.391
## 15     26.0        1      6.2879          2.253
## 16     26.9        1      9.2827          2.117
## 17     27.8        1     10.3581          2.209
## 18     28.0        1      6.9862          2.317
## 19     30.0        1      7.9190          2.346
## 20     31.2        1      6.5074          2.318
## 21     32.1        1      4.9709          2.310
## 22     34.1        1      5.7455          2.360
## 23     36.1        1      6.5627          2.244
## 24     44.9        1      5.4374          2.363
## 25     45.2        1      6.2240          2.416
## 26     47.8        1      7.0519          2.409
## 27     54.1        1      7.9198          2.427
## 28     54.9        1      6.7260          2.310
## 29     58.1        1      7.5667          2.456
## 30     59.8        1      7.2524          2.483
## 31     63.2        1      6.1770          2.511
## 32     70.4        1      5.2110          2.562
## 33     76.1        1      4.3461          2.683
## 34     80.1        1      3.5753          2.744
## 35     81.3        1      2.8926          2.467
## 36     82.1        0      2.2925          2.669
## 37     90.1        1      2.7908          2.543
## 38     92.1        0      2.2120          2.523
## 39     95.0        0      1.7079          2.755
## 40     99.0        0      2.1383          2.762
## 41    108.2        0      2.6206          2.652
## 42    109.9        1      3.1475          2.630
## 43    117.0        0      2.5398          2.646
## 44    148.8        1      3.0555          2.685
## 45    153.1        0      2.4658          2.774

Summary function for supELtest object

Description

Returns a list containing the maximally selected EL statistics, the critical value based on bootstrap, and the p-value of the test.

Usage

## S3 method for class 'supELtest'
summary(object, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)
## S3 method for class 'supELtest'
summary(object, digits = max(3L, getOption("digits") - 3L), quiet = FALSE, ...)

Arguments

`object`	the result of a call to the `supELtest` function
`digits`	significant digits to print, the default value is `max(3L, getOption("digits") - 3L)`
`quiet`	a logical indicating whether to reduce the amount of output or not, the default value is `FALSE`
`...`	for future method

Value

summary.supELtest returns a list with following components:

call the statement used to create the supELtest object
teststat the resulting integrated EL statistics
critval the critical value based on bootstrap
pvalue the p-value of the test
sided the value of the input argument of supELtest
alpha the value of the input argument of supELtest

Examples

library(survELtest)
nocrossings(survival::Surv(hepatitis$time, hepatitis$censor)~
    hepatitis$group, sided = 1)

## OUTPUT:
## Call:
## nocrossings(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Decision = 1

## A decision value of 1 means the case of crossings or alternative orderings among the 
## survival functions is excluded. Thus, we can proceed to the one-sided test.

result = supELtest(survival::Surv(hepatitis$time, hepatitis$censor)~
             hepatitis$group, sided = 1)
summary(result)

## OUTPUT:
## Call:
## supELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## One-sided maximally selected EL test statistic = 10.36, p = 0.006,
## critical value based on bootstrap = 6.289 at a significance level of 0.05
library(survELtest)
nocrossings(survival::Surv(hepatitis$time, hepatitis$censor)~
    hepatitis$group, sided = 1)

## OUTPUT:
## Call:
## nocrossings(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Decision = 1

## A decision value of 1 means the case of crossings or alternative orderings among the 
## survival functions is excluded. Thus, we can proceed to the one-sided test.

result = supELtest(survival::Surv(hepatitis$time, hepatitis$censor)~
             hepatitis$group, sided = 1)
summary(result)

## OUTPUT:
## Call:
## supELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## One-sided maximally selected EL test statistic = 10.36, p = 0.006,
## critical value based on bootstrap = 6.289 at a significance level of 0.05

The maximally selected EL test

Description

supELtest provides the maximally selected EL statistics that is better adapted at detecting local differences:

$\sup_{i=1,\ldots,m}\{-2\log R(t_i)\},$

where $R(t)$ is the EL ratio that compares the survival functions at each given time $t$ , and $0<t_1<\ldots<t_m<\infty$ are the (ordered) observed uncensored times at which the Kaplan–Meier estimate is positive and less than 1 for each sample.

Usage

supELtest(
  formula,
  data = NULL,
  group_order = NULL,
  t1 = 0,
  t2 = Inf,
  sided = 2,
  nboot = 1000,
  alpha = 0.05,
  seed = 1011,
  nlimit = 200
)
supELtest(
  formula,
  data = NULL,
  group_order = NULL,
  t1 = 0,
  t2 = Inf,
  sided = 2,
  nboot = 1000,
  alpha = 0.05,
  seed = 1011,
  nlimit = 200
)

Arguments

`formula`	a formula object with a `Surv` object as the response on the left of the `~` operator and the grouping variable as the term on the right. The `Surv` object involves two variables: the observed survival and censoring times, and the censoring indicator, which takes a value of $1$ if the observed time is uncensored and $0$ otherwise. The grouping variable takes different values for different groups.
`data`	an optional data frame containing the variables in the `formula`: the observed survival and censoring times, the censoring indicator, and the grouping variable. If not found in `data`, the variables in the `formula` should be already defined by the user or in attached `R` objects. The default is the data frame with three columns of variables taken from the formula: column 1 contains the observed survival and censoring times, column 2 the censoring indicator, and column 3 the grouping variable.
`group_order`	a $k$ -vector containing the values of the grouping variable, with the $j$ -th element being the group hypothesized to have the $j$ -th highest survival rates, $j=1,\ldots,k$ . The default is the vector of sorted grouping variables.
`t1`	the first endpoint of a prespecified time interval, if any, to which the comparison of the survival functions is restricted. The default value is $0$ .
`t2`	the second endpoint of a prespecified time interval, if any, to which the comparison of the survival functions is restricted. The default value is $\infty$ .
`sided`	$2$ if two-sided test, and $1$ if one-sided test. The default value is $2$ .
`nboot`	the number of bootstrap replications in calculating critical values for the tests. The default value is $1000$ .
`alpha`	the pre-specified significance level of the tests. The default value is $0.05$ .
`seed`	the seed for the random number generator in `R`, for generating bootstrap samples needed to calculate the critical values for the tests. The default value is $1011$ .
`nlimit`	a number used to calculate `nsplit=` $m$ `/nlimit`, the number of parts into which the calculation of the `nboot` bootstrap replications is split. The use of this variable can make computation faster when the number of time points $m$ is large. The default value for `nlimit` is 200.

Value

supELtest returns a supELtest object, a list with 14 elements:

call the function call
teststat the resulting integrated EL statistics
critval the critical value based on bootstrap
pvalue the p-value of the test
formula the value of the input argument of supELtest
data the value of the input argument of supELtest
group_order the value of the input argument of supELtest
t1 the value of the input argument of supELtest
t2 the value of the input argument of supELtest
sided the value of the input argument of supELtest
nboot the value of the input argument of supELtest
alpha the value of the input argument of supELtest
seed the value of the input argument of supELtest
nlimit the value of the input argument of supELtest

Methods defined for supELtest objects are provided for print and summary.

References

H. Chang, I.W. McKeague, "Empirical likelihood based tests for stochastic ordering under right censorship," Electronic Journal of Statistics, Vol. 10, No. 2, pp. 2511-2536 (2016).
H. Chang, I.W. McKeague, "Nonparametric testing for multiple survival functions with non-inferiority margins," Annals of Statistics, Vol. 47, No. 1, pp. 205-232, (2019).

Examples

library(survELtest)
nocrossings(survival::Surv(hepatitis$time, hepatitis$censor)~
    hepatitis$group, sided = 1)

## OUTPUT:
## Call:
## nocrossings(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Decision = 1

## A decision value of 1 means the case of crossings or alternative orderings among the 
## survival functions is excluded. Thus, we can proceed to the one-sided test.

supELtest(survival::Surv(hepatitis$time, hepatitis$censor)~
    hepatitis$group, sided = 1)

## OUTPUT:
## Call:
## supELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~   
##     hepatitis$group, sided = 1)
## 
## One-sided maximally selected EL test statistic = 10.36, p = 0.006
library(survELtest)
nocrossings(survival::Surv(hepatitis$time, hepatitis$censor)~
    hepatitis$group, sided = 1)

## OUTPUT:
## Call:
## nocrossings(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~ 
##     hepatitis$group, sided = 1)
## 
## Decision = 1

## A decision value of 1 means the case of crossings or alternative orderings among the 
## survival functions is excluded. Thus, we can proceed to the one-sided test.

supELtest(survival::Surv(hepatitis$time, hepatitis$censor)~
    hepatitis$group, sided = 1)

## OUTPUT:
## Call:
## supELtest(formula = survival::Surv(hepatitis$time, hepatitis$censor) ~   
##     hepatitis$group, sided = 1)
## 
## One-sided maximally selected EL test statistic = 10.36, p = 0.006

Time to first remission data

Description

The data frame threearm is obtained by resampling from perturbed time-to-remission from patients in a three-arm randomized clinical trial for the treatment of major depression. See nocrossings, ptwiseELtest and supELtest for the application.

Usage

threearm
threearm

Format

The threearm is a data frame with 664 observations of 3 variables, and has the following columns:

time the observed times to first remission and censoring times
censor the censoring indicator
group the grouping variable

Package 'survELtest'

Help Index

Simulated survival data with crossing hazard functions from the piecewise exponential distribution

Description

Usage

Format

References

See Also

Simulated survival data with crossing hazard functions from the Weibull distribution

Description

Usage

Format

References

See Also

Severe alcoholic hepatitis data

Description

Usage

Format

Source

References

See Also

The integrated EL test

Description

Usage

Arguments

Details

Value

References

See Also

Examples

The test that excludes the possibility of crossings or alternative orderings among the survival functions

Description

Usage

Arguments

Value

References

See Also

Examples

Print an intELtest object

Description

Usage

Arguments

See Also

Examples

Print a nocrossings object

Description

Usage

Arguments

See Also

Examples

Print a ptwiseELtest object

Description

Usage

Arguments

See Also

Examples

Print a supELtest object

Description

Usage

Arguments

See Also

Examples

The pointwise EL testing

Description

Usage

Arguments

Value

See Also

Examples

Summary function for intELtest object

Description

Usage

Arguments

Value

See Also

Examples

Summary function for nocrossings object

Description

Usage

Arguments