cuRe (version 1.1.1)

calc.LL: Loss of lifetime estimation

Description

Function for computing mean residual lifetime and loss of lifetime estimates based on relative survival models.

Usage

calc.LL(
  object,
  newdata = NULL,
  type = c("ll", "mrl"),
  time = NULL,
  tau = 100,
  var.type = c("ci", "se", "n"),
  exp.fun = NULL,
  ratetable = cuRe::survexp.dk,
  rmap,
  smooth.exp = FALSE,
  scale = ayear,
  pars = NULL,
  n = 100
)

Value

An object of class le containing the life expectancy estimates of each individual in newdata.

Arguments

object

Fitted model to do predictions from. Possible classes are gfcm, cm, stpm2, and pstpm2.

newdata

Data frame from which to compute predictions. If empty, predictions are made on the the data which the model was fitted on.

type

Type of life expectation estimate. Possible values are ll (default) which gives the loss of lifetime, and mrl which gives the mean residual lifetime.

time

Time points at which to compute predictions. If empty, a grid of 100 time points between 0 and tau is selected.

tau

The upper limit of the integral (see details). Default is 100.

var.type

Character. Possible values are "ci" (default) for confidence intervals, "se" for standard errors, and "n" for neither.

exp.fun

Object of class list containing functions for the expected survival of each row in newdata. If not specified, the function computes the expected survival based on newdata using the survival::survexp function. If newdata is not provided, the expected survival is based on the data which the model was fitted on.

ratetable

Object of class ratetable used to compute the general population survival. Default is survexp.dk.

rmap

List to be passed to survexp from the survival package if exp.fun = NULL. Detailed documentation on this argument can be found by ?survexp.

smooth.exp

Logical. If TRUE, the general population survival function is smoothed by the function smooth.spline using the the argument all.knots = TRUE.

scale

Numeric. Passed to the survival::survexp function and defaults to 365.24. That is, the time scale is assumed to be in years.

pars

A vector of parameter values for the model given in object. Currently not used.

n

Number of knots used for the Gauss-Legendre quadrature.

Details

The mean residual lifetime function and loss of lifetime function are based on numerical integration of the area under the observed and expected conditional survival functions. If type = "ll", the function computes $$\frac{\int_t^\infty S^*(u)}{S^*(t)} - \frac{\int_t^\infty S(u)}{S(t)}.$$ If type = "mrl", the function computes $$\frac{\int_t^\infty S(u)}{S(t)},$$ for a given t. The function \(S^*(t)\) is the general population survival function and \(S(t)\) is the observed survival function. Integration to infinity is not required in studies of human mortality, so an upper limit, tau, is chosen instead. As most humans die before they 100 years, this is the default setting of the function. The integral is computed by Gauss-Legendre quadrature and the point wise variance is estimated using the delta method and numerical differentiation.

Examples

##Use data cleaned version of the colon cancer data from the rstpm2 package
data("colonDC")
set.seed(2)
colonDC <- colonDC[sample(1:nrow(colonDC), 1000), ]

##Extract general population hazards
colonDC$bhaz <- general.haz(time = "FU", rmap = list(age = "agedays", sex = "sex", year= "dx"),
                            data = colonDC, ratetable = survexp.dk)

##Spline-base cure model
#Fit cure model
fit <- rstpm2::stpm2(Surv(FUyear, status) ~ 1, data = colonDC,
                     df = 6, bhazard = colonDC$bhaz, cure = TRUE)

#Compute and plot the loss of lifetime function
res <- calc.LL(fit, time = seq(0, 20, length.out = 50),
               rmap = list(age = agedays, sex = sex, year = dx),
               var.type = "n")
plot(res)

#Compute and plot the mean residual lifetime
res <- calc.LL(fit, time = seq(0, 20, length.out = 50), type = "mrl",
               rmap = list(age = agedays, sex = sex, year = dx),
               var.type = "n")
plot(res)


#Simple parametric cure model
#Fit cure model
fit <- fit.cure.model(Surv(FUyear, status) ~ 1, data = colonDC, bhazard = "bhaz",
                      type = "mixture", dist = "weibull", link = "logit")

#Compute and plot the loss of lifetime function
res <- calc.LL(fit, time = seq(0, 20, length.out = 50),
               rmap = list(age = agedays, sex = sex, year = dx),
               var.type = "n")
plot(res)

#Compute and plot the mean residual lifetime
res <- calc.LL(fit, time = seq(0, 20, length.out = 50), type = "mrl",
               rmap = list(age = agedays, sex = sex, year = dx),
               var.type = "n")
plot(res)