# Generate and/or plot a sample from the prior distribution of M-spline hazard curves

Source:`R/priors.R`

`prior_sample_hazard.Rd`

Generates and/or plots the hazard curves (as functions of time) implied by a prior mean for the spline coefficients (a constant hazard by default) and particular priors for the baseline log hazard and smoothness standard deviation.

## Usage

```
prior_sample_hazard(
knots = NULL,
df = 10,
degree = 3,
bsmooth = TRUE,
coefs_mean = NULL,
prior_hsd = p_gamma(2, 1),
prior_hscale = NULL,
smooth_model = "exchangeable",
prior_loghr = NULL,
formula = NULL,
cure = NULL,
nonprop = NULL,
newdata = NULL,
newdata0 = NULL,
prior_hrsd = NULL,
tmin = 0,
tmax = 10,
nsim = 10
)
plot_prior_hazard(
knots = NULL,
df = 10,
degree = 3,
bsmooth = TRUE,
coefs_mean = NULL,
prior_hsd = p_gamma(2, 1),
prior_hscale = p_normal(0, 20),
smooth_model = "exchangeable",
prior_loghr = NULL,
formula = NULL,
cure = NULL,
nonprop = NULL,
newdata = NULL,
prior_hrsd = p_gamma(2, 1),
tmin = 0,
tmax = NULL,
nsim = 10
)
```

## Arguments

- knots
Vector of knot locations. If not supplied,

`df`

has to be specified. One of two rules is then used to choose the knot locations. If`bknots`

is specified, a set of equally spaced knots between zero and`bknots`

is used. Otherwise if`obstimes`

is supplied, the knots are chosen as equally spaced quantiles of`obstimes`

.The number of knots (excluding zero) is

`df - degree + 1`

if`bsmooth`

is`TRUE`

, or`df - degree - 1`

otherwise.- df
Desired number of basis terms, or "degrees of freedom" in the spline. If

`knots`

is not supplied, the number of knots is then chosen to satisfy this.- degree
Spline polynomial degree. Can only be changed from the default of 3 if

`bsmooth`

is`FALSE`

.- bsmooth
If

`TRUE`

then the function is constrained to also have zero derivative and second derivative at the boundary.- coefs_mean
Spline basis coefficients that define the prior mean for the hazard function. By default, these are set to values that define a constant hazard function (see

`mspline_constant_coefs`

). They are normalised to sum to 1 internally (if they do not already).- prior_hsd
Gamma prior for the standard deviation that controls the variability over time (or smoothness) of the hazard function. This should be a call to

`p_gamma()`

. The default is`p_gamma(2,1)`

. See`prior_haz_sd`

for a way to calibrate this to represent a meaningful belief.- prior_hscale
Prior for the baseline log hazard scale parameter (

`alpha`

or`log(eta)`

). This should be a call to a prior constructor function, such as`p_normal(0,1)`

or`p_t(0,2,2)`

. Supported prior distribution families are normal (parameters mean and SD) and t distributions (parameters location, scale and degrees of freedom). The default is a normal distribution with mean 0 and standard deviation 20.Note that

`eta`

is not in itself a hazard, but it is proportional to the hazard (see the vignette for the full model specification)."Baseline" is defined by the continuous covariates taking a value of zero and factor covariates taking their reference level. To use a different baseline, the data should be transformed appropriately beforehand, so that a value of zero has a different meaning. For continuous covariates, it helps for both computation and interpretation to define the value of zero to denote a typical value in the data, e.g. the mean.

- smooth_model
The default

`"exchangeable"`

uses independent logistic priors on the multinomial-logit spline coefficients, conditionally on a common smoothing variance parameter.The alternative,

`"random_walk"`

, specifies a second-order random walk for the multinomial-logit spline coefficients, based on logistic distributions with a common smoothing variance. See the methods vignette for full details.In non-proportional hazards models, setting

`smooth_model`

also determines whether an exchangeable or random walk model is used for the non-proportionality parameters (\(\delta\)).- prior_loghr
Priors for log hazard ratios. This should be a call to

`p_normal()`

or`p_t()`

. A list of calls can also be provided, to give different priors to different coefficients, where the name of each list component matches the name of the coefficient, e.g.`list("age45-59" = p_normal(0,1), "age60+" = p_t(0,2,3))`

The default is

`p_normal(0,2.5)`

for all coefficients.- formula
A survival formula in standard R formula syntax, with a call to

`Surv()`

on the left hand side.Covariates included on the right hand side of the formula with be modelled with proportional hazards, or if

`nonprop`

is`TRUE`

then a non-proportional hazards is used.If

`data`

is omitted, so that the model is being fitted to external aggregate data alone, without individual data, then the formula should not include a`Surv()`

call. The left-hand side of the formula will then be empty, and the right hand side specifies the covariates as usual. For example,`formula = ~1`

if there are no covariates.- cure
If

`TRUE`

, a mixture cure model is used, where the "uncured" survival is defined by the M-spline model, and the cure probability is estimated.- nonprop
Non-proportional hazards model specification. This is achieved by modelling the spline basis coefficients in terms of the covariates. See the methods vignette for more details.

If

`TRUE`

, then all covariates are modelled with non-proportional hazards, using the same model formula as`formula`

.If this is a formula, then this is assumed to define a model for the dependence of the basis coefficients on the covariates.

IF this is

`NULL`

or`FALSE`

(the default) then any covariates are modelled with proportional hazards.- newdata
A data frame with one row, containing variables in the model formulae. Samples will then be drawn, for any covariate-dependent parameters, with covariates set to the values given here.

- newdata0
A data frame with one row, containing "reference" values of variables in the model formulae. The hazard ratio between the hazards at

`newdata`

and`newdata0`

will be returned.- prior_hrsd
Prior for the standard deviation parameters that smooth the non-proportionality effects over time in non-proportional hazards models. This should be a call to

`p_gamma()`

or a list of calls to`p_gamma()`

with one component per covariate, as in`prior_loghr`

. See`prior_hr_sd`

for a way to calibrate this to represent a meaningful belief.- tmin
Minimum plotting time. Defaults to zero.

- tmax
Maximum plotting time. Defaults to the highest knot.

- nsim
Number of simulations to draw