params_surv {hesim}

Parameters of a survival model

Description

Create a list containing the parameters of a single fitted parametric or flexible parametric survival model.

Usage

params_surv(coefs, dist, aux = NULL)

Arguments

coefs

A list of length equal to the number of parameters in the survival distribution. Each element of the list is a matrix of samples of the regression coefficients under sampling uncertainty used to predict a given parameter. All parameters are expressed on the real line (e.g., after log transformation if they are defined as positive). Each element of the list may also be an object coercible to a matrix such as a data.frame or data.table.

dist

Character vector denoting the parametric distribution. See "Details".

aux

Auxiliary arguments used with splines, fractional polynomial, or piecewise exponential models. See "Details".

Details

Survival is modeled as a function of L parameters \alpha_l. Letting F(t) be the cumulative distribution function, survival at time t is given by

1 - F(t | \alpha_1(x_{1}), \ldots, \alpha_L(x_{L})).

The parameters are modeled as a function of covariates, x_l, with an inverse transformation function g^{-1}(),

\alpha_l = g^{-1}(x_{l}^T \beta_l).

g^{-1}() is typically exp() if a parameter is strictly positive and the identity function if the parameter space is unrestricted.

The types of distributions that can be specified are:

exponential or exp

Exponential distribution. coef must contain the rate parameter on the log scale and the same parameterization as in stats::Exponential.

weibull or weibull.quiet

Weibull distribution. The first element of coef is the shape parameter (on the log scale) and the second element is the scale parameter (also on the log scale). The parameterization is that same as in stats::Weibull.

weibullPH

Weibull distribution with a proportional hazards parameterization. The first element of coef is the shape parameter (on the log scale) and the second element is the scale parameter (also on the log scale). The parameterization is that same as in flexsurv::WeibullPH.

gamma

Gamma distribution. The first element of coef is the shape parameter (on the log scale) and the second element is the rate parameter (also on the log scale). The parameterization is that same as in stats::GammaDist.

lnorm

Lognormal distribution. The first element of coef is the meanlog parameter (i.e., the mean of survival on the log scale) and the second element is the sdlog parameter (i.e., the standard deviation of survival on the log scale). The parameterization is that same as in stats::Lognormal. The coefficients predicting the meanlog parameter are untransformed whereas the coefficients predicting the sdlog parameter are defined on the log scale.

gompertz

Gompertz distribution. The first element of coef is the shape parameter and the second element is the rate parameter (on the log scale). The parameterization is that same as in flexsurv::Gompertz.

llogis

Log-logistic distribution. The first element of coef is the shape parameter (on the log scale) and the second element is the scale parameter (also on the log scale). The parameterization is that same as in flexsurv::Llogis.

gengamma

Generalized gamma distribution. The first element of coef is the location parameter mu, the second element is the scale parameter sigma (on the log scale), and the third element is the shape parameter Q. The parameterization is that same as in flexsurv::GenGamma.

survspline

Survival splines. Each element of coef is a parameter of the spline model (i.e. gamma_0, gamma_1, \ldots) with length equal to the number of knots (including the boundary knots). See below for details on the auxiliary arguments. The parameterization is that same as in flexsurv::Survspline.

fracpoly

Fractional polynomials. Each element of coef is a parameter of the fractional polynomial model (i.e. gamma_0, gamma_1, \ldots) with length equal to the number of powers plus 1. See below for details on the auxiliary arguments (i.e., powers).

pwexp

Piecewise exponential distribution. Each element of coef is rate parameter for a distinct time interval. The times at which the rates change should be specified with the auxiliary argument time (see below for more details)

.

fixed

A fixed survival time. Can be used for "non-random" number generation. coef should contain a single parameter, est, of the fixed survival times.

Auxiliary arguments for spline models should be specified as a list containing the elements:

knots

A numeric vector of knots.

scale

The survival outcome to be modeled as a spline function. Options are "log_cumhazard" for the log cumulative hazard; "log_hazard" for the log hazard rate; "log_cumodds" for the log cumulative odds; and "inv_normal" for the inverse normal distribution function.

timescale

If "log" (the default), then survival is modeled as a spline function of log time; if "identity", then it is modeled as a spline function of time.

Auxiliary arguments for fractional polynomial models should be specified as a list containing the elements:

powers

A vector of the powers of the fractional polynomial with each element chosen from the following set: -2. -1, -0.5, 0, 0.5, 1, 2, 3.

Auxiliary arguments for piecewise exponential models should be specified as a list containing the element:

time

A vector equal to the number of rate parameters giving the times at which the rate changes.

Furthermore, when splines (with scale = "log_hazard") or fractional polynomials are used, numerical methods must be used to compute the cumulative hazard and for random number generation. The following additional auxiliary arguments can therefore be specified:

cumhaz_method

Numerical method used to compute cumulative hazard (i.e., to integrate the hazard function). Always used for fractional polynomials but only used for splines if scale = "log_hazard". Options are "quad" for adaptive quadrature and "riemann" for Riemann sum.

random_method

Method used to randomly draw from an arbitrary survival function. Options are "invcdf" for the inverse CDF and "discrete" for a discrete time approximation that randomly samples events from a Bernoulli distribution at discrete times.

step

Step size for computation of cumulative hazard with numerical integration. Only required when using "riemann" to compute the cumulative hazard or using "discrete" for random number generation.

Value

An object of class params_surv, which is a list containing coefs, dist, and n_samples. n_samples is equal to the number of rows in each element of coefs, which must be the same. The coefs element is always converted into a list of matrices. The list may also contain aux if a spline, fractional polynomial, or piecewise exponential model is used.

Examples

n <- 10
params <- params_surv(
  coefs = list(
    shape = data.frame(
      intercept = rnorm(n, .5, .23)
    ),
    scale = data.frame(
      intercept = rnorm(n, 12.39, 1.49),
      age = rnorm(n, -.09, .023)
   )
  ),
  dist = "weibull"
)
summary(params)
params