years {relsurv}

Compute one of the life years measures

Description

Provides an estimate for one of the following measures: years lost (Andersen, 2013), years lost/saved (Andersen, 2017), or life years difference (Manevski, Ruzic Gorenjec, Andersen, Pohar Perme, 2022).

Usage

years(
  formula = formula(data),
  data,
  measure = c("yd", "yl2017", "yl2013"),
  ratetable = relsurv::slopop,
  rmap,
  var.estimator = c("none", "bootstrap", "greenwood"),
  B = 100,
  precision = 30,
  add.times,
  na.action = stats::na.omit,
  conf.int = 0.95,
  timefix = FALSE,
  is.boot = FALSE,
  first.boot = FALSE
)

Arguments

formula

a formula object, with the response as a Surv object on the left of a ~ operator, and, ~1 specified on the right.

NOTE: The follow-up time must be in days.

data

a data.frame in which to interpret the variables named in the formula.

measure

choose which measure is used: 'yd' (life years difference; Manevski, Ruzic Gorenjec, Andersen, Pohar Perme, 2022), 'yl2017' (years lost/saved; Andersen 2017), 'yl2013' (years lost/saved; Andersen 2013).

ratetable

a table of event rates, organized as a ratetable object, such as slopop.

rmap

an optional list to be used if the variables are not organized and named in the same way as in the ratetable object. See details below.

var.estimator

Choose the estimator for the variance ('none', 'bootstrap', 'greenwood'). Default is 'none'. The 'greenwood' option is possible only for measure='yd'.

B

if var.estimator is 'bootstrap'. The number of bootstrap replications. Default is 100.

precision

precision for numerical integration of the population curve. Default is 30 (days). The value may be decreased to get a higher precision or increased to achieve a faster calculation.

add.times

specific times at which the curves should be reported.

na.action

a missing-data filter function. Default is na.omit.

conf.int

the confidence level for a two-sided confidence interval. Default is 0.95.

timefix

the timefix argument in survival::survfit.formula. Default is FALSE.

is.boot

if TRUE, the function years has been called during a bootstrap replication.

first.boot

if TRUE, this is the first bootstrap replication.

Details

The life years difference (measure='yd') is taken by default. If other measures are of interest, use the measure argument.

The follow-up time must be specified in days. The ratetable being used may have different variable names and formats than the user's data set, this is dealt with the rmap argument. For example, if age is in years in the data but in days in the ratetable object, age=age*365.241 should be used. The calendar year can be in any date format (date, Date and POSIXt are allowed), the date formats in the ratetable and in the data may differ.

Numerical integration is performed, argument precision is set with argument precision, which defaults to 30-day intervals for intergration. For higher accuracy take a smaller value (e.g. precision=1 makes the integration on a daily basis).

The observed curves are reported at event and censoring times. The population curves are reported at all times used for the numerical integration. Note that for the years lost (Andersen, 2013) measure, only the excess absolute risk is reported.

Value

A list containing the years measure, the observed and population curves (or the excess curve for Andersen 2013). The values are given as separate data.frames through time. Times are given in days, all areas are given in years. For measure='yl2017' values are reported only at the last time point. Functions plot_f and plot_years can be then used for plotting.

See Also

plot_f, plot_years

Examples

library(relsurv)
# Estimate the life years difference for the rdata dataset.
mod <- years(Surv(time, cens)~1, data=rdata, measure='yd', ratetable=slopop,
             rmap=list(age=age*365.241), var.estimator = 'none')
# Plot the absolute risk (observed and population curve):
plot_f(mod)
# Plot the life years difference estimate:
plot_years(mod, conf.int=FALSE)