visR (version 0.4.1)

estimate_KM: Wrapper for Kaplan-Meier Time-to-Event analysis

Description

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,
  ...
)

Value

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

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

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.

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)

## Stratified Kaplan-Meier analysis by `TRTP`
visR::estimate_KM(data = adtte, strata = "TRTP")

## Stratified Kaplan-Meier analysis by `TRTP` and `SEX`
visR::estimate_KM(data = adtte, strata = c("TRTP", "SEX"))

## Stratification with one level
visR::estimate_KM(data = adtte, strata = "PARAMCD")

## Analysis on subset of adtte
visR::estimate_KM(data = adtte[adtte$SEX == "F", ])

## Modify the default analysis by using the ellipsis
visR::estimate_KM(
  data = adtte, strata = NULL,
  type = "kaplan-meier", conf.int = FALSE, timefix = TRUE
)

## Example working with non CDISC data
head(survival::veteran[c("time", "status", "trt")])

# Using non-CDSIC data
visR::estimate_KM(data = survival::veteran, formula = Surv(time, status) ~ trt)