Package 'timeEL' reference manual

Title:	Time to Event Analysis via Empirical Likelihood Inference
Description:	Computation of t-year survival probabilities and t-year risks with right censored survival data. The Kaplan-Meier estimator is used to provide estimates for data without competing risks and the Aalen-Johansen estimator is used when there are competing risks. Confidence intervals and p-values are obtained using either usual Wald-type inference or empirical likelihood inference, as described in Thomas and Grunkemeier (1975) <doi:10.1080/01621459.1975.10480315> and Blanche (2020) <doi:10.1007/s10985-018-09458-6>. Functions for both one-sample and two-sample inference are provided. Unlike Wald-type inference, empirical likelihood inference always leads to consistent conclusions, in terms of statistical significance, when comparing two risks (or survival probabilities) via either a ratio or a difference.
Authors:	Paul Blanche [aut, cre] , Frank Eriksson [ctb]
Maintainer:	Paul Blanche <[email protected]>
License:	GPL (>= 3)
Version:	0.9.1
Built:	2025-02-17 05:00:38 UTC
Source:	https://github.com/paulowhite/timeel

Risk estimate using the Aalen-Johansen method

Description

Computes the Aalen-Johansen estimator to estimate an (absolute) risk with right-censored competing risks data, together with a confidence interval and (possibly) a p-value (for a one-sample hypothesis test). Computation of confidence intervals and p-values is based on either Empirical Likelihood (EL) inference or Wald-type inference. Both are non-parametric approaches, which are asymptotically equivalent. See Blanche (2020) for details. For the Wald-type approach, the asymptotic normal approximation is used on the cloglog scale. See e.g. equation 4.21 in Beyersmann et al (2011).

Usage

AalenJohansen(
  time,
  cause,
  t,
  risk.H0 = NULL,
  level = 0.95,
  contr = list(tol = 1e-05, k = 3, Trace = FALSE, method = "both")
)
AalenJohansen(
  time,
  cause,
  t,
  risk.H0 = NULL,
  level = 0.95,
  contr = list(tol = 1e-05, k = 3, Trace = FALSE, method = "both")
)

Arguments

`time`	vector of times (possibly censored)
`cause`	vector of event types/causes. It should be coded 1 for main events, 2 for competing events and 0 for censored.
`t`	the time point of interest (e.g., 1 to compute a 1-year risk)
`risk.H0`	risk under the null hypothesis, if one would like to compute the correspondng p-value. Default is NULL, for which no p-value is computed.
`level`	confidence level for the confidence intervals. Default is 0.95.
`contr`	list of control parameters. tol=tolerance for numerical computation, default is 1e-5. method="EL", "Wald" or "both" indicates wether 95% CI and p-value should be computed based on Empirical Likelihood (EL) inference , Wald-type inference or both.

Value

object of class 'AalenJohansen'

Author(s)

Paul Blanche

References

Blanche, P. (2020). Confidence intervals for the cumulative incidence function via constrained NPMLE. Lifetime Data Analysis, 26(1), 45-64.

Beyersmann, Allignol, & Schumacher (2011). Competing risks and multistate models with R. Springer Science & Business Media.

Examples

x <- AalenJohansen(time=melanoma5$time, cause=melanoma5$status, t=4, level=0.95)
x

x <- AalenJohansen(time=melanoma5$time, cause=melanoma5$status, t=4, level=0.95)
x

Bone Marrow Transplant Registry

Description

The data contain observations of 408 patients treated with HLA-identical sibling bone marrow transplantation for myelodysplasia. The dataset is essentially a subset of the 'bmt' data of the 'timereg' package (minor changes were introduced to break the ties).

Usage

BMTplat
BMTplat

Format

A data frame with 408 rows and 3 variables:

time: time to event since transplant (in months)
status: event status, 1 is dead from treatment related causes, 2 is relapse , 0 is censored.
group: platelet level: 1 if more than 100 x 10^9 per L, 0 if less

Source

'timereg' package

References

Li, J., Le-Rademacher, J., & Zhang, M. J. (2014). Weighted comparison of two cumulative incidence functions with R-CIFsmry package. Computer methods and programs in biomedicine, 116(3), 205-214.

Bone Marrow Transplant Registry

Description

Usage

BMTtcell
BMTtcell

Format

A data frame with 408 rows and 3 variables:

time: time to event since transplant (in months)
status: event status, 1 is dead from treatment related causes, 2 is relapse , 0 is censored.
group: presence of T-cell depletion: 1 if present, 0 otherwise

Source

'timereg' package

References

Li, J., Le-Rademacher, J., & Zhang, M. J. (2014). Weighted comparison of two cumulative incidence functions with R-CIFsmry package. Computer methods and programs in biomedicine, 116(3), 205-214.

Acute Leukemia data from Freireich et al (1963)

Description

In this study there were 21 pairs of subjects, and within each pair one subject received 6-mercaptopurine (6-MP) and one got placebo. The data are right censored. See also Gehan (1965) and Thomas & Grunkemeier (1975) who used the data as an illustrative example (ignoring the pairing).

Usage

Freireich
Freireich

Format

A data frame with 42 rows and 3 variables:

time: time in remission (in weeks)
status: event status, 1 is relapse, 0 is censored
group: treatment group: 0 (placebo) or 1 (6-MP)

Source

Data listed in Section 5 in Thomas & Grunkemeier (1975) and Section 11 in Gehan (1965)

References

Freireich et al (1963) Blood 21(6):699-716

Gehan (1965) Biometrika 52:203-223

Thomas & Grunkemeier (1975) JASA 70(352): 865-871

Risk and survival probability estimates using the Kaplan-Meier method

Description

Computes the Kaplan-Meier estimator to estimate a risk or, equivalently, a survival probability, with right-censored data, together with a confidence interval and (possibly) a p-value (for a one-sample hypothesis test). Computation of confidence intervals and p-values is based on either Empirical Likelihood (EL) inference or Wald-type inference. Both are non-parametric approaches, which are asymptotically equivalent. See Thomas & Grunkemeier (1975) for details about the Empirical Likelihood method. For the Wald-type approach, the asymptotic normal approximation is used on the cloglog scale. See e.g. equation 4.16 in Beyersmann et al (2011).

Usage

KaplanMeier(
  time,
  status,
  t,
  risk.H0 = NULL,
  level = 0.95,
  contr = list(tol = 1e-05, k = 3, Trace = FALSE, method = "both")
)
KaplanMeier(
  time,
  status,
  t,
  risk.H0 = NULL,
  level = 0.95,
  contr = list(tol = 1e-05, k = 3, Trace = FALSE, method = "both")
)

Arguments

`time`	vector of times (possibly censored)
`status`	vector of usual survival status indicators (0 for censored observations, 1 for events)
`t`	the time point of interest (e.g. 1 to compute a 1-year risk or survival probability)
`risk.H0`	risk under the null hypothesis, if one would like to compute the correspondng p-value. Default is NULL, for which no p-value is computed.
`level`	confidence level for the confidence intervals. Default is 0.95.
`contr`	list of control parameters. tol=tolerance for numerical computation, default is 1e-5. method="EL", "Wald" or "both" indicates wether 95% CI and p-value should be computed based on Empirical Likelihood (EL) inference , Wald-type inference or both.

Value

object of class 'KaplanMeier'

Author(s)

Paul Blanche

References

Thomas & Grunkemeier (1975). Confidence interval estimation of survival probabilities for censored data. Journal of the American Statistical Association, 70(352), 865-871.

Beyersmann, Allignol, & Schumacher (2011). Competing risks and multistate models with R. Springer Science & Business Media.

Examples

# This example reproduces some results presented in Table 1 of Thomas and Grunkemeier (1975)
ResKM.1.95 <- KaplanMeier(time=Freireich$time[Freireich$group==1],
                          status=Freireich$status[Freireich$group==1],
                          t=10, level=0.95, contr=list(tol=1e-4))
ResKM.1.95

# This example reproduces some results presented in Table 1 of Thomas and Grunkemeier (1975)
ResKM.1.95 <- KaplanMeier(time=Freireich$time[Freireich$group==1],
                          status=Freireich$status[Freireich$group==1],
                          t=10, level=0.95, contr=list(tol=1e-4))
ResKM.1.95

Melanoma competing risks data

Description

These competing risks data relate to survival of patients after operation for malignant melanoma collected at Odense University Hospital between 1962 and 1977. The data are a subsample of the 'melanoma' data of the 'timereg' package (patients who had a tumor thickness of less than 5 cm).

Usage

melanoma5
melanoma5

Format

A data frame with 173 rows and 2 variables:

time: time to event (in years)
status: event status, 1 is death due to malignant melanoma, 2 is death due to another cause and 0 is censored

Source

'timereg' package

References

Andersen PK, Skovgaard LT (2010) Regression with linear predictors. Springer, Berlin

Drzewiecki K, Andersen PK (1982) Survival with malignant melanoma: a regression analysis of prognostic factors. Cancer 49:2414–2419

Print function for object of class 'AalenJohansen'

Description

Print function for object of class 'AalenJohansen'

Usage

## S3 method for class 'AalenJohansen'
print(x, digits = 4, method = NULL, ...)
## S3 method for class 'AalenJohansen'
print(x, digits = 4, method = NULL, ...)

Arguments

`x`	an object of class 'AalenJohansen'
`digits`	number of digits to print the results
`method`	either "EL", "Wald" or "both", depending on whether we want to print the results obtained when using empirical likelihood inference (EL), Wald-type inference (Wald) or both. Default is 'NULL', which means that 'method' inherits the value of the corresponding control parameter used when creating the object 'x'.
`...`	Not used

Value

no return value, called for printing only.

Author(s)

Paul Blanche

Examples

x <- AalenJohansen(time=melanoma5$time, cause=melanoma5$status, t=4, level=0.95)
print(x, digits=3, method="EL")

x <- AalenJohansen(time=melanoma5$time, cause=melanoma5$status, t=4, level=0.95)
print(x, digits=3, method="EL")

Print function for object of class 'KaplanMeier'

Description

Print function for object of class 'KaplanMeier'

Usage

## S3 method for class 'KaplanMeier'
print(x, digits = 4, type = "risk", method = NULL, ...)
## S3 method for class 'KaplanMeier'
print(x, digits = 4, type = "risk", method = NULL, ...)

Arguments

`x`	an object of class 'KaplanMeier'
`digits`	number of digits to print the results
`type`	either "surv" or "risk" (the default), depending on whether we want to print the results in terms of a survival probability or a risk (i.e., one minus the survival probability).
`method`	either "EL", "Wald" or "both", depending on whether we want to print the results obtained when using empirical likelihood inference (EL), Wald-type inference (Wald) or both. Default is 'NULL', which means that 'method' inherits the value of the corresponding control parameter used when creating the object 'x'.
`...`	Not used

Value

no return value, called for printing only.

Author(s)

Paul Blanche

Examples

# This example reproduces some results presented in Table 1 of Thomas and Grunkemeier (1975)
ResKM.1.95 <- KaplanMeier(time=Freireich$time[Freireich$group==1],
                          status=Freireich$status[Freireich$group==1],
                          t=10, level=0.95, contr=list(tol=1e-4))
print(ResKM.1.95, digits=3, type="surv", method="EL")   # EL results for survival
print(ResKM.1.95, digits=3, type="risk", method="Wald") # Wald results for risk

# This example reproduces some results presented in Table 1 of Thomas and Grunkemeier (1975)
ResKM.1.95 <- KaplanMeier(time=Freireich$time[Freireich$group==1],
                          status=Freireich$status[Freireich$group==1],
                          t=10, level=0.95, contr=list(tol=1e-4))
print(ResKM.1.95, digits=3, type="surv", method="EL")   # EL results for survival
print(ResKM.1.95, digits=3, type="risk", method="Wald") # Wald results for risk

Print function for object of class 'TwoSampleAalenJohansen'

Description

Print function for object of class 'TwoSampleAalenJohansen'

Usage

## S3 method for class 'TwoSampleAalenJohansen'
print(x, digits = 4, what = "both", method = NULL, absRisk = TRUE, ...)
## S3 method for class 'TwoSampleAalenJohansen'
print(x, digits = 4, what = "both", method = NULL, absRisk = TRUE, ...)

Arguments

`x`	an object of class 'TwoSampleAalenJohansen'
`digits`	number of digits to print the results
`what`	either "RR", "Diff" or "both" (default), depending on whether we want to print the results for the risk ratio (RR), the risk difference (Diff) or both.
`method`	either "EL", "Wald" or "both", depending on whether we want to print the results obtained when using empirical likelihood inference (EL), Wald-type inference (Wald) or both. Default is 'NULL', which means that 'method' inherits the value of the corresponding control parameter used when creating the object 'x'.
`absRisk`	Default is TRUE and this should not be changed.
`...`	Not used

Value

no return value, called for printing only.

Author(s)

Paul Blanche

Examples

## A simple example for Wald-type inference, using simulated data.
## It illustrates the possible inconsistency of Wald-type inference, in
## terms of statistical significance, when inference is based on the risk
## ratio and on the risk difference. This inconsistency cannot exist
## using an empirical likelihood approach.

ResSimA100 <- TwoSampleAalenJohansen(time=SimA100$time,
                                     cause=SimA100$status,
                                     group=SimA100$group,
                                     t=1,
                                     contr=list(method="Wald"))
print(ResSimA100, digits=3, what="Diff")
print(ResSimA100, digits=3, what="RR")


## Same example data, but now analyzed with and empirical likelihood approach. It
## takes approx 20 seconds to run.

ResSimA100 <- TwoSampleAalenJohansen(time=SimA100$time,
                                     cause=SimA100$status,
                                     group=SimA100$group,
                                     t=1)
print(ResSimA100, digits=3, what="Diff",  method="EL")

## A simple example for Wald-type inference, using simulated data.
## It illustrates the possible inconsistency of Wald-type inference, in
## terms of statistical significance, when inference is based on the risk
## ratio and on the risk difference. This inconsistency cannot exist
## using an empirical likelihood approach.

ResSimA100 <- TwoSampleAalenJohansen(time=SimA100$time,
                                     cause=SimA100$status,
                                     group=SimA100$group,
                                     t=1,
                                     contr=list(method="Wald"))
print(ResSimA100, digits=3, what="Diff")
print(ResSimA100, digits=3, what="RR")


## Same example data, but now analyzed with and empirical likelihood approach. It
## takes approx 20 seconds to run.

ResSimA100 <- TwoSampleAalenJohansen(time=SimA100$time,
                                     cause=SimA100$status,
                                     group=SimA100$group,
                                     t=1)
print(ResSimA100, digits=3, what="Diff",  method="EL")

Print function for object of class 'TwoSampleKaplanMeier'

Description

Print function for object of class 'TwoSampleKaplanMeier'

Usage

## S3 method for class 'TwoSampleKaplanMeier'
print(x, digits = 4, what = "all", method = NULL, ...)
## S3 method for class 'TwoSampleKaplanMeier'
print(x, digits = 4, what = "all", method = NULL, ...)

Arguments

`x`	an object of class 'TwoSampleKaplanMeier'
`digits`	number of digits to print the results
`what`	either "SR", "RR", "Diff" or "all" (default), depending on whether we want to print the results for the survival ratio (SR), the risk ratio (RR), the risk difference (Diff) or all of them.
`method`	either "EL", "Wald" or "both", depending on whether we want to print the results obtained when using empirical likelihood inference (EL), Wald-type inference (Wald) or both. Default is 'NULL', which means that 'method' inherits the value of the corresponding control parameter used when creating the object 'x'.
`...`	Not used

Value

no return value, called for printing only.

Author(s)

Paul Blanche

Examples

# This example reproduces some results presented in Table 4 of Thomas and Grunkemeier (1975)
Res2SKM95 <- TwoSampleKaplanMeier(time=Freireich$time,
                                  status=Freireich$status,
                                  group=Freireich$group,
                                  t=10)
print(Res2SKM95, digits=3, what="SR", method="EL")

# This example reproduces some results presented in Table 4 of Thomas and Grunkemeier (1975)
Res2SKM95 <- TwoSampleKaplanMeier(time=Freireich$time,
                                  status=Freireich$status,
                                  group=Freireich$group,
                                  t=10)
print(Res2SKM95, digits=3, what="SR", method="EL")

Simulated competing risks data

Description

The data were simulated as described in Blanche & Eriksson (2023), using scenario A with sample size n=100.

Usage

SimA100
SimA100

Format

A data frame with 100 rows and 3 variables:

time: time to event
status: event status, 1 is main event, 2 is competing event, 0 is censored.
group: group (1 or 0)

Source

Simulated data

References

Blanche & Eriksson (2023). Empirical likelihood comparison of absolute risks.

Risk difference and ratio using the Aalen-Johansen method

Description

Computes an (absolute) risk difference or ratio with right-censored competing risks data, together with a confidence interval and a p-value (to test for a difference between the two risks). Pointwise estimates are computed via the Aalen-Johansen estimator. Computation of confidence intervals and p-values are based on either Empirical Likelihood (EL) inference or Wald-type inference. Both are non-parametric approaches, which are asymptotically equivalent. For the Wald-type approach, the asymptotic normal approximation is used on the log scale for the risk ratio. No transformation is used for the risk difference. See Blanche & Eriksson (2023) for details.

Usage

TwoSampleAalenJohansen(
  time,
  cause,
  group,
  t,
  RR.H0 = 1,
  Diff.H0 = 0,
  level = 0.95,
  contr = list(tol = 1e-05, algo = 2, k = 3, Trace = FALSE, method = "both")
)
TwoSampleAalenJohansen(
  time,
  cause,
  group,
  t,
  RR.H0 = 1,
  Diff.H0 = 0,
  level = 0.95,
  contr = list(tol = 1e-05, algo = 2, k = 3, Trace = FALSE, method = "both")
)

Arguments

`time`	vector of times (possibly censored)
`cause`	vector of event types/causes. It should be coded 1 for main events, 2 for competing events and 0 for censored.
`group`	vector of binary group indicator. The reference group should be coded 0, the other 1.
`t`	the time point of interest (e.g. 1 to compute a 1-year risk ratio)
`RR.H0`	the risk ratio under the null hypothesis, to compute a p-value. Default is 1.
`Diff.H0`	the risk difference under the null hypothesis, to compute a p-value. Default is 0.
`level`	confidence level for the confidence intervals. Default is 0.95.
`contr`	list of control parameters. tol=tolerance for numerical computation, default is 1e-5. method="EL", "Wald" or "both" indicates wether 95% CI and the p-value should be computed based on Empirical Likelihood (EL) inference, Wald-type inference or both. algo=2 (default) or 1, depending on which computational method should be used to maximize the empirical likelihood (method 1 or 2, as described in Blanche & Eriksson (2023))

Value

an object of class 'TwoSampleAalenJohansen'

Author(s)

Paul Blanche

References

Blanche & Eriksson (2023). Empirical likelihood comparison of absolute risks.

Examples

## A simple example for Wald-type inference, using simulated data.
## It illustrates the possible inconsistency of Wald-type inference, in
## terms of statistical significance, when inference is based on the risk
## ratio and on the risk difference. This inconsistency cannot exist
## using an empirical likelihood approach.

ResSimA100 <- TwoSampleAalenJohansen(time=SimA100$time,
                                     cause=SimA100$status,
                                     group=SimA100$group,
                                     t=1,
                                     contr=list(method="Wald"))
ResSimA100


## Same example data, but now analyzed with and empirical likelihood approach. It
## takes approx 20 seconds to run.

ResSimA100 <- TwoSampleAalenJohansen(time=SimA100$time,
                                     cause=SimA100$status,
                                     group=SimA100$group,
                                     t=1)
ResSimA100


## A simple example for Wald-type inference, using simulated data.
## It illustrates the possible inconsistency of Wald-type inference, in
## terms of statistical significance, when inference is based on the risk
## ratio and on the risk difference. This inconsistency cannot exist
## using an empirical likelihood approach.

ResSimA100 <- TwoSampleAalenJohansen(time=SimA100$time,
                                     cause=SimA100$status,
                                     group=SimA100$group,
                                     t=1,
                                     contr=list(method="Wald"))
ResSimA100


## Same example data, but now analyzed with and empirical likelihood approach. It
## takes approx 20 seconds to run.

ResSimA100 <- TwoSampleAalenJohansen(time=SimA100$time,
                                     cause=SimA100$status,
                                     group=SimA100$group,
                                     t=1)
ResSimA100

Risk difference and risk ratio using the Kaplan-Meier method

Description

Computes a risk difference, risk ratio or survival ratio with right-censored data, together with a confidence interval and a p-value (to test for a difference between two groups). Pointwise estimates are computed via the Kaplan-Meier estimator. Computation of confidence intervals and p-values are based on either Empirical Likelihood (EL) inference or Wald-type inference. Both are non-parametric approaches, which are asymptotically equivalent. See Thomas & Grunkemeier (1975) for details about the Empirical Likelihood method. For the Wald-type approach, the asymptotic normal approximation is used on the log scale for the risk ratio or survival ratio. No transformation is used for the risk or survival difference.

Usage

TwoSampleKaplanMeier(
  time,
  status,
  group,
  t,
  SR.H0 = 1,
  RR.H0 = 1,
  Diff.H0 = 0,
  level = 0.95,
  contr = list(tol = 1e-05, algo = 2, k = 3, Trace = FALSE, method = "both")
)
TwoSampleKaplanMeier(
  time,
  status,
  group,
  t,
  SR.H0 = 1,
  RR.H0 = 1,
  Diff.H0 = 0,
  level = 0.95,
  contr = list(tol = 1e-05, algo = 2, k = 3, Trace = FALSE, method = "both")
)

Arguments

`time`	vector of times (possibly censored)
`status`	vector of usual survival status indicators (0 for censored observations, 1 otherwise)
`group`	vector of binary group indicator. The reference group should be coded 0, the other 1.
`t`	the time point of interest (e.g. 1 to compute 1-year risk ratio)
`SR.H0`	the survival ratio under the null hypothesis, to compute a p-value. Default is 1.
`RR.H0`	the risk ratio under the null hypothesis, to compute a p-value. Default is 1.
`Diff.H0`	the risk difference under the null hypothesis, to compute a p-value. Default is 0.
`level`	confidence level for the confidence intervals. Default is 0.95.
`contr`	list of control parameters. tol=tolerance for numerical computation, default is 1e-5. method="EL", "Wald" or "both" indicates wether 95% CI and the p-value should be computed based on Empirical Likelihood inference, Wald-type inference or both. algo=2 is currently the only option that is implemented.

Value

an object of class 'TwoSampleKaplanMeier'

Author(s)

Paul Blanche

References

Thomas & Grunkemeier (1975). Confidence interval estimation of survival probabilities for censored data. Journal of the American Statistical Association, 70(352), 865-871.

Examples

# This example reproduces some results presented in Table 4 of Thomas and Grunkemeier (1975)
Res2SKM95 <- TwoSampleKaplanMeier(time=Freireich$time,
                                  status=Freireich$status,
                                  group=Freireich$group,
                                  t=10)
Res2SKM95


# This example reproduces some results presented in Table 4 of Thomas and Grunkemeier (1975)
Res2SKM95 <- TwoSampleKaplanMeier(time=Freireich$time,
                                  status=Freireich$status,
                                  group=Freireich$group,
                                  t=10)
Res2SKM95

Package 'timeEL'

Help Index

Risk estimate using the Aalen-Johansen method

Description

Usage

Arguments

Value

Author(s)

References

Examples

Bone Marrow Transplant Registry

Description

Usage

Format

Source

References

Bone Marrow Transplant Registry

Description

Usage

Format

Source

References

Acute Leukemia data from Freireich et al (1963)

Description

Usage

Format

Source

References

Risk and survival probability estimates using the Kaplan-Meier method

Description

Usage

Arguments

Value

Author(s)

References

Examples

Melanoma competing risks data

Description

Usage

Format

Source

References

Print function for object of class 'AalenJohansen'

Description

Usage

Arguments

Value

Author(s)

Examples

Print function for object of class 'KaplanMeier'

Description

Usage

Arguments

Value

Author(s)

Examples

Print function for object of class 'TwoSampleAalenJohansen'

Description

Usage

Arguments

Value

Author(s)

Examples

Print function for object of class 'TwoSampleKaplanMeier'

Description

Usage

Arguments

Value

Author(s)

Examples

Simulated competing risks data

Description

Usage

Format

Source

References

Risk difference and ratio using the Aalen-Johansen method

Description

Usage

Arguments