Skip to contents

Wrapper for Kaplan-Meier Time-to-Event analysis

Source: R/estimate_KM.R
estimate_KM.Rd

[Deprecated]

This function is a wrapper around survival::survfit.formula() to perform a Kaplan-Meier analysis, assuming right-censored data. The result is an object of class survfit which can be used in downstream functions and methods that rely on the survfit class.

The function can leverage the conventions and controlled vocabulary from CDISC ADaM ADTTE data model, and also works with standard, non-CDISC datasets through the formula argument.

Usage

estimate_KM(
  data = NULL,
  strata = NULL,
  CNSR = "CNSR",
  AVAL = "AVAL",
  formula = NULL,
  ...
)

Arguments

data

A data frame. The dataset is expected to have one record per subject per analysis parameter. Rows with missing observations included in the analysis are removed.

AVAL, CNSR, strata

These arguments are used to construct a formula to be passed to survival::survfit(formula=Surv(AVAL, 1-CNSR)~strata). These arguments' default values follow the naming conventions in CDISC.

  • AVAL Analysis value for Time-to-Event analysis. Default is "AVAL", as per CDISC ADaM guiding principles.

  • CNSR Censor for Time-to-Event analysis. Default is "CNSR", as per CDISC ADaM guiding principles. It is expected that CNSR = 1 for censoring and CNSR = 0 for the event of interest.

  • strata Character vector, representing the strata for Time-to-Event analysis. When NULL, an overall analysis is performed. Default is NULL.

formula

[Experimental] formula with Surv() on RHS and stratifying variables on the LHS. Use ~1 on the LHS for unstratified estimates. This argument will be passed to survival::survfit(formula=). When this argument is used, arguments AVAL, CNSR, and strata are ignored.

...

additional arguments passed on to the ellipsis of the call survival::survfit.formula(...). Use ?survival::survfit.formula and ?survival::survfitCI for more information.

Value

survfit object ready for downstream processing in estimation or visualization functions and methods.

Estimation of 'survfit' object

The estimate_KM() function utilizes the defaults in survival::survfit():

  • The Kaplan Meier estimate is estimated directly (stype = 1).

  • The cumulative hazard is estimated using the Nelson-Aalen estimator (ctype = 1): H.tilde = cumsum(x$n.event/x$n.risk). The MLE (H.hat(t) = -log(S.hat(t))) can't be requested.

  • A two-sided pointwise 0.95 confidence interval is estimated using a log transformation (conf.type = "log").

When strata are present, the returned survfit object is supplemented with the a named list of the stratum and associated label. To support full traceability, the data set name is captured in the named list and the call is captured within its corresponding environment.

PARAM/PARAMCD and CDISC

If the data frame includes columns PARAM/PARAMCD (part of the CDISC format), the function expects the data has been filtered on the parameter of interest.

References

https://github.com/therneau/survival

See also

survfit.formula survfitCI

Examples


## No stratification
visR::estimate_KM(data = adtte)
#> Call: ~survival::survfit(formula = survival::Surv(AVAL, 1 - CNSR) ~ 
#>     1, data = data)
#> 
#>        n events median 0.95LCL 0.95UCL
#> [1,] 254    152     51      44      70

## Stratified Kaplan-Meier analysis by `TRTP`
visR::estimate_KM(data = adtte, strata = "TRTP")
#> Call: ~survival::survfit(formula = survival::Surv(AVAL, 1 - CNSR) ~ 
#>     TRTP, data = data)
#> 
#>                            n events median 0.95LCL 0.95UCL
#> TRTP=Placebo              86     29     NA      NA      NA
#> TRTP=Xanomeline High Dose 84     61     36      25      47
#> TRTP=Xanomeline Low Dose  84     62     33      28      51

## Stratified Kaplan-Meier analysis by `TRTP` and `SEX`
visR::estimate_KM(data = adtte, strata = c("TRTP", "SEX"))
#> Call: ~survival::survfit(formula = survival::Surv(AVAL, 1 - CNSR) ~ 
#>     TRTP + SEX, data = data)
#> 
#>                                   n events median 0.95LCL 0.95UCL
#> TRTP=Placebo, SEX=F              53     19     NA      90      NA
#> TRTP=Placebo, SEX=M              33     10     NA      NA      NA
#> TRTP=Xanomeline High Dose, SEX=F 40     27     46      30      70
#> TRTP=Xanomeline High Dose, SEX=M 44     34     25      20      46
#> TRTP=Xanomeline Low Dose, SEX=F  50     34     43      29     100
#> TRTP=Xanomeline Low Dose, SEX=M  34     28     27      21      51

## Stratification with one level
visR::estimate_KM(data = adtte, strata = "PARAMCD")
#> Call: ~survival::survfit(formula = survival::Surv(AVAL, 1 - CNSR) ~ 
#>     PARAMCD, data = data)
#> 
#>        n events median 0.95LCL 0.95UCL
#> [1,] 254    152     51      44      70

## Analysis on subset of adtte
visR::estimate_KM(data = adtte[adtte$SEX == "F", ])
#> Call: ~survival::survfit(formula = survival::Surv(AVAL, 1 - CNSR) ~ 
#>     1, data = data)
#> 
#>        n events median 0.95LCL 0.95UCL
#> [1,] 143     80     64      47      96

## Modify the default analysis by using the ellipsis
visR::estimate_KM(
  data = adtte, strata = NULL,
  type = "kaplan-meier", conf.int = FALSE, timefix = TRUE
)
#> Call: ~survival::survfit(formula = survival::Surv(AVAL, 1 - CNSR) ~ 
#>     1, data = data, timefix = TRUE, type = "kaplan-meier", conf.int = FALSE)
#> 
#>        n events median
#> [1,] 254    152     51

## Example working with non CDISC data
head(survival::veteran[c("time", "status", "trt")])
#>   time status trt
#> 1   72      1   1
#> 2  411      1   1
#> 3  228      1   1
#> 4  126      1   1
#> 5  118      1   1
#> 6   10      1   1

# Using non-CDSIC data
visR::estimate_KM(data = survival::veteran, formula = Surv(time, status) ~ trt)
#> Call: ~survival::survfit(formula = Surv(time, status) ~ trt, data = data)
#> 
#>        n events median 0.95LCL 0.95UCL
#> trt=1 69     64  103.0      59     132
#> trt=2 68     64   52.5      44      95