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

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