Probability density, distribution, quantile, random generation, hazard, cumulative hazard, mean and restricted mean functions for the M-spline time-to-event model. This can optionally be combined with a cure probability, and / or with a known background hazard trajectory that is a piecewise-constant function of time.

## Usage

```
psurvmspline(
q,
alpha,
coefs,
knots,
degree = 3,
lower.tail = TRUE,
log.p = FALSE,
pcure = 0,
offsetH = 0,
backhaz = NULL,
bsmooth = TRUE
)
Hsurvmspline(
x,
alpha,
coefs,
knots,
degree = 3,
log = FALSE,
pcure = 0,
offsetH = 0,
backhaz = NULL,
bsmooth = TRUE
)
hsurvmspline(
x,
alpha,
coefs,
knots,
degree = 3,
log = FALSE,
pcure = 0,
offseth = 0,
backhaz = NULL,
bsmooth = TRUE
)
dsurvmspline(
x,
alpha,
coefs,
knots,
degree = 3,
log = FALSE,
pcure = 0,
offseth = 0,
offsetH = 0,
backhaz = NULL,
bsmooth = TRUE
)
qsurvmspline(
p,
alpha,
coefs,
knots,
degree = 3,
lower.tail = TRUE,
log.p = FALSE,
pcure = 0,
offsetH = 0,
backhaz = NULL,
bsmooth = TRUE
)
rsurvmspline(
n,
alpha,
coefs,
knots,
degree = 3,
pcure = 0,
offsetH = 0,
backhaz = NULL,
bsmooth = TRUE
)
rmst_survmspline(
t,
alpha,
coefs,
knots,
degree = 3,
pcure = 0,
offsetH = 0,
backhaz = NULL,
bsmooth = TRUE,
disc_rate = 0
)
mean_survmspline(
alpha,
coefs,
knots,
degree = 3,
pcure = 0,
offsetH = 0,
backhaz = NULL,
bsmooth = TRUE,
disc_rate = 0
)
```

## Arguments

- alpha
Log hazard scale parameter.

- coefs
Spline basis coefficients. These should sum to 1, otherwise they are normalised internally to sum to 1. Supplied either as a vector with one element per basis term, or a matrix with one column per basis term, and rows for alternative values of the coefficients (in vectorised usage of this function). If an array is supplied, it is collapsed into a matrix with number of columns equal to the final dimension of the array.

- 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`

.- lower.tail
logical; if

`TRUE`

(default), probabilities are \(P(X \le x)\), otherwise, \(P(X > x)\).- pcure
Probability of "cure", which defaults to zero. If this is non-zero, this defines a "mixture cure" version of the M-spline model.

- 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.- x, q, t
Vector of times.

- log, log.p
Return log density or probability.

- 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

`dsurvmspline`

gives the density, `psurvmspline`

gives the
distribution function, `hsurvmspline`

gives the hazard and
`Hsurvmspline`

gives the cumulative hazard.

`qsurvmspline`

gives the quantile function, which is computed by
numerical inversion.

`rsurvmspline`

generates random survival times by using
`qsurvmspline`

on a sample of uniform random numbers.

## Details

These are the same as the M-splines used to model survival data in `rstanarm`

, except that an
additional assumption is made that the hazard is constant beyond the boundary knots at its
value at the boundary. This gives a continuous but non-smooth function.

The "cure" model can be interpreted in two different ways. These result in identical probability distribution functions for the event time, hence they are indistinguishable from data:

(a) a model where everyone follows the same hazard trajectory that is decreasing through time, with a higher rate of decrease for higher `pcure`

.

(b) a model where a person either has a constant zero hazard at all times, or a hazard that follows a parametric model (M-spline in this case). The probability that a person has a zero hazard is `pcure`

.
This is the "mixture model" interpretation.

In the "background hazard" model, the overall hazard is defined as a sum of the background hazard and
a cause-specific hazard. The cause-specific hazard
is modelled with the M-spline model, and the background hazard is assumed
to be a known piecewise-constant function defined by `backhaz`

.

If both `backhaz`

and `pcure`

are supplied, then the cure probablity applies only to the cause-specific hazard.
That is, the cause-specific hazard decreases to zero, and the overall hazard converges towards
the background hazard, as time increases.

## References

Ramsay, J. O. (1988). Monotone regression splines in action. Statistical Science, 3(4): 425-441.

Brilleman, S. L., Elci, E. M., Novik, J. B., & Wolfe, R. (2020). Bayesian survival analysis using the rstanarm R package. arXiv preprint arXiv:2002.09633.

Wang, W., Yan, J. (2021). Shape-restricted regression splines with R package splines2. Journal of Data Science_, *19*(3), 498-517.

## Author

Christopher Jackson chris.jackson@mrc-bsu.cam.ac.uk