Restricted mean survival time

Compute the restricted mean survival time from a model fitted with survextrap. Defined as the integral of the fitted survival curve up to a specified time. This relies on numerical integration, which is done for every parameter in the MCMC sample, so it may be slow.

Usage

rmst(
  x,
  t,
  newdata = NULL,
  newdata0 = NULL,
  wane_period = NULL,
  wane_nt = 10,
  disc_rate = 0,
  niter = NULL,
  summ_fns = NULL,
  sample = FALSE
)

Arguments

x

A fitted model object as returned by survextrap

t

Vector of times. The restricted mean survival time up to each one of these times will be computed.

newdata

Data frame of covariate values to compute the output for. If there are covariates in the model and this is not supplied, the following default is used:

(a) if the only covariate is one factor variable, then the output is computed for each level of this factor.

(b) if there are multiple covariates, or any numeric covariates, then the output is computed at the mean of each numeric covariate in the original data, and at the baseline level of each factor covariate.

Note caution is required about how treatment groups (for example) are stored in your data. If these are coded as numeric (0/1), then if newdata is not specified only one output will be shown, which relates to the average value of this numeric variable over the data, which doesn't correspond to either of the treatment groups. To avoid this, a treatment group should be stored as a factor.

newdata0

Data frame of covariate values defining the "untreated" group for use in treatment waning models. See Survmspline_wane.

wane_period

Vector of two numbers, defining the time period over which the hazard is interpolated between the hazard of the "treated" group (taken from newdata) and the hazard of the "untreated" group (taken from newdata0). Optional - if this is not supplied, then no waning is assumed.

wane_nt

Number of intervals defining the piecewise constant approximation to the hazard during the waning period.

disc_rate

Discounting rate used to calculate the discounted mean or restricted mean survival time, using an exponential discounting function.

niter

Number of MCMC iterations to use to compute credible intervals. Set to a low value to make this function quicker, at the cost of some approximation error (which may not be important for plotting or model development).

summ_fns

A list of functions to use to summarise the posterior sample. This is passed to posterior::summarise_draws. By default this is list(median=median, ~quantile(.x, probs=c(0.025, 0.975))). If the list is named, then the names will be used for the columns of the output.

sample

If TRUE then an MCMC sample is returned from the posterior of the output, rather than summary statistics.

Value

A data frame (tibble) with each row containing posterior summary statistics for a particular time and covariate value.

Or if sample=TRUE, an array with dimensions length(t), niter, nrow(newdata), giving the RMST evaluated at different times, MCMC iterations and covariate values respectively.

Examples

mod <- survextrap(Surv(years, status) ~ rx, data=colons, fit_method="opt")
rmst(mod, t=3, niter=100)
#> # A tibble: 3 × 6
#>   variable rx          t median lower upper
#>   <chr>    <chr>   <dbl>  <dbl> <dbl> <dbl>
#> 1 rmst     Obs         3   1.97  1.68  2.25
#> 2 rmst     Lev         3   2.22  1.83  2.45
#> 3 rmst     Lev+5FU     3   2.41  2.06  2.58
rmst(mod, t=3, summ_fns=list(mean=mean), niter=100)
#> # A tibble: 3 × 4
#>   variable rx          t  mean
#>   <chr>    <chr>   <dbl> <dbl>
#> 1 rmst     Obs         3  1.97
#> 2 rmst     Lev         3  2.21
#> 3 rmst     Lev+5FU     3  2.38