years: Compute one of the life years measures

View source: R/years.R

yearsR Documentation

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,
  admin.cens,
  arg.example = FALSE,
  cause.val,
  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). the population cumulative incidence curve. Relevant only for measure='yd'. For measure='yl2013' and measure='yl2017' the estimators defined in (Andersen, 2013) and (Andersen, 2017) are used.

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'.

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.

admin.cens

if a Date is supplied, administrative censoring is taken into account at that time in the population curve. Works only if there's late entry, e.g. if the formula is Surv(start,stop,event)~1.

arg.example

temporary argument, used for checking additionalities.

cause.val

for competing risks, to be added.

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 required for the population curves. The integration precision is set with argument precision, which defaults to 30-day intervals. 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. 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)

relsurv documentation built on March 18, 2022, 5:15 p.m.

Related to years in relsurv...