Skip to contents

M-spline survival distribution under treatment effect waning

Source: R/waning.R
Survmspline_wane.Rd

This defines the CDF, cumulative hazard and hazard of a survival distribution defined by combining the hazards of two different groups (e.g. "treated" and "untreated") each defined by a standard M-spline model. The log hazards of one group and the other are interpolated over a defined period of time. This may be used for models where the treatment effect wanes, over a period of time, between an estimated hazard ratio and zero.

Usage

Hsurvmspline_wane(
  x,
  alpha1,
  alpha0,
  coefs1,
  coefs0,
  knots,
  degree = 3,
  wane_period,
  wane_nt = 10,
  pcure1 = 0,
  pcure0 = 0,
  offsetH = 0,
  backhaz = NULL,
  bsmooth = TRUE,
  log = FALSE
)

psurvmspline_wane(
  q,
  alpha1,
  alpha0,
  coefs1,
  coefs0,
  knots,
  degree = 3,
  bsmooth = TRUE,
  wane_period,
  wane_nt = 10,
  lower.tail = TRUE,
  pcure1 = 0,
  pcure0 = 0,
  offsetH = 0,
  backhaz = NULL,
  log.p = FALSE
)

hsurvmspline_wane(
  x,
  alpha1,
  alpha0,
  coefs1,
  coefs0,
  knots,
  degree = 3,
  bsmooth = TRUE,
  wane_period,
  wane_nt = 10,
  pcure1 = 0,
  pcure0 = 0,
  offseth = 0,
  backhaz = NULL,
  log = FALSE
)

dsurvmspline_wane(
  x,
  alpha1,
  alpha0,
  coefs1,
  coefs0,
  knots,
  degree = 3,
  bsmooth = TRUE,
  wane_period,
  wane_nt = 10,
  pcure1 = 0,
  pcure0 = 0,
  offseth = 0,
  offsetH = 0,
  backhaz = NULL,
  log = FALSE
)

qsurvmspline_wane(
  p,
  alpha1,
  alpha0,
  coefs1,
  coefs0,
  knots,
  degree = 3,
  bsmooth = TRUE,
  lower.tail = TRUE,
  log.p = FALSE,
  pcure1 = 0,
  pcure0 = 0,
  offsetH = 0,
  backhaz = NULL,
  wane_period,
  wane_nt = 10
)

rsurvmspline_wane(
  n,
  alpha1,
  alpha0,
  coefs1,
  coefs0,
  knots,
  degree = 3,
  bsmooth = TRUE,
  pcure1 = 0,
  pcure0 = 0,
  offsetH = 0,
  backhaz = NULL,
  wane_period,
  wane_nt = 10
)

rmst_survmspline_wane(
  t,
  alpha1,
  alpha0,
  coefs1,
  coefs0,
  knots,
  degree = 3,
  pcure1 = 0,
  pcure0 = 0,
  offsetH = 0,
  backhaz = NULL,
  bsmooth = TRUE,
  wane_period,
  wane_nt = 10,
  disc_rate = 0,
  method = "gl",
  gl_nodes = 100
)

mean_survmspline_wane(
  alpha1,
  alpha0,
  coefs1,
  coefs0,
  knots,
  degree = 3,
  pcure1 = 0,
  pcure0 = 0,
  backhaz = NULL,
  bsmooth = TRUE,
  wane_period,
  wane_nt = 10,
  disc_rate = 0
)

Arguments

x, q, t

Vector of times.

alpha1, coefs1, pcure1

log hazard intercept, spline coefficients and cure probability before the start of the waning period ("treated")

alpha0, coefs0, pcure0

log hazard intercept, spline coefficients and cure probability after the end of the waning period ("untreated")

knots

Locations of knots on the axis of time, supplied in increasing order. These include the two boundary knots.

In vectorised usage of these functions, the knots and degree must be the same for all alternative times and parameter values.

degree

Spline polynomial degree. Can only be changed from the default of 3 if bsmooth is FALSE.

wane_period

vector of two components giving start and stop of waning period

wane_nt

time resolution for piecewise constant hazard approximation in the waning period. If this is not specified, defaults to dividing the waning period into 10 pieces.

offsetH

Constant to be added to the cumulative hazard.

backhaz

A data frame that defines the background hazard as a piecewise-constant function of time. This should have two columns, named "time" and "hazard". Each row gives the "background" hazard between the specified time and the next time. The first element of "time" should be 0, and the final row specifies the hazard at all times greater than the last element of "time".

bsmooth

If TRUE then the function is constrained to also have zero derivative and second derivative at the boundary.

log, log.p

Return log density or probability.

lower.tail

logical; if TRUE (default), probabilities are \(P(X \le x)\), otherwise, \(P(X > x)\).

offseth

Constant to be added to the hazard, e.g. representing a "background" risk of death from causes other than the cause of interest.

p

Vector of probabilities.

n

Number of random numbers to simulate.

disc_rate

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

method

Method of numerical integration to obtain the restricted mean survival time from the survival function.

The default is method="gl", a Gauss-Legendre method with 100 nodes between zero and the maximum of t.

method="adaptive" uses the base R integrate function, which is much slower, but potentially more robust for badly-behaved survival functions.

gl_nodes

Number of nodes for the Gauss-Legendre method.

Value

psurvmspline_wane gives the CDF, Hsurvmspline_wane gives the cumulative hazard, hsurvmspline_wane gives the hazard, dsurvmspline_wane gives the PDF, qsurvmspline_wane gives the quantiles, and rsurvmspline_wane generates random numbers from the distribution.

Details

This distribution is defined as follows.

  • Between time 0 and wane_period[1], the "treated" hazard is used, as defined by an M-spline with intercept alpha1.

  • Between wane_period[1] and wane_period[2], the log hazard is defined by linear interpolation. The waning period is divided into a number of discrete pieces in which the hazard is assumed to be constant, defined by the hazard at the start of the piece. These hazard values are obtained from the spline model, using an intercept parameter alpha (log scale parameter) defined by linearly interpolating between alpha1 and alpha0 over the waning period. The cumulative hazard at any time can then be deduced by adding up contributions on each piece.

  • After wane_period[2], the "untreated" hazard is used, as defined by an M-spline with intercept alpha0.

See the methods vignette for more details and examples.

This can be used to predict the hazard of a person treated with a treatment whose short-term effect is estimated from shorter-term data, but we wish to extrapolate this model over a longer period where the effect is assumed to diminish.

This may not work if the hazard is zero or infinite at any point in the waning period (thus the log hazard is indeterminate). This might typically happen at time 0.