hesim (version 0.2.0)

params_surv: Parameters of a survival model

Description

Create a list containing the parameters of a single fitted parametric or flexibly 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 from the posterior distribution of the regression coefficients used to predict a given parameter.

dist

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

aux

Auxiliary arguments used with splines or fractional polynomials. See "Details".

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 list may also contain aux if a spline or fractional polynomial model is fit.

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

• 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 GammaDist.

• lnorm Lognormal distribution. The first element of coef is the meanlog parameter (i.e., the mean on the log scale) and the second element is the sdlog parameter (i.e., the standard deviation on the log scale). The parameterization is that same as in Lognormal.

• 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 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 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 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 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 minus 1. See below for details on the auxiliary arguments (i.e., powers).

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.

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 "sample" for randomly sampling from discrete survival probabilities.

step

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

Examples

# NOT RUN {
library("flexsurv")
fit <- flexsurvreg(Surv(futime, fustat) ~ 1, data = ovarian, dist = "weibull")
params <- params_surv(coefs = list(shape = fit$res.t["shape", "est", drop = FALSE],
                                   scale = fit$res.t["scale", "est", drop = FALSE]),
                     dist = fit$dlist$name)
print(params)
# }