parsnip (version 0.0.0.9001)

surv_reg: General Interface for Parametric Survival Models

Description

surv_reg is a way to generate a specification of a model before fitting and allows the model to be created using R. The main argument for the model is:

• dist: The probability distribution of the outcome.

This argument is converted to its specific names at the time that the model is fit. Other options and argument can be set using the others argument. If left to its default here (NULL), the value is taken from the underlying model functions.

If parameters need to be modified, this function can be used in lieu of recreating the object from scratch.

Usage

surv_reg(mode = "regression", dist = NULL, others = list(), ...)
# S3 method for surv_reg
update(object, dist = NULL, others = list(),
  fresh = FALSE, ...)

Arguments

mode

A single character string for the type of model. The only possible value for this model is "regression".

dist

A character string for the outcome distribution. "weibull" is the default.

others

A named list of arguments to be used by the underlying models (e.g., flexsurv::flexsurvreg). These are not evaluated until the model is fit and will be substituted into the model fit expression.

...

Used for S3 method consistency. Any arguments passed to the ellipses will result in an error. Use others instead.

object

A survival regression model specification.

fresh

A logical for whether the arguments should be modified in-place of or replaced wholesale.

Value

An updated model specification.

Details

The data given to the function are not saved and are only used to determine the mode of the model. For surv_reg,the mode will always be "regression".

Since survival models typically involve censoring (and require the use of survival::Surv() objects), the fit() function will require that the survival model be specified via the formula or recipes interfaces.

For recipes, right censoring indicators should be specified using the "censoring var" role (see examples below). Also, for the engine that uses flexsurv::flexsurvfit, extra roles can be used for non-location parameters (e.g. sigma or sdlog) so that other distributional parameters can be functions or covariates. See the example below as well as Jackson (2016).

Also, for the flexsurv::flexsurvfit engine, the typical strata function cannot be used. To achieve the same effect, the extra parameter roles can be used (as described above).

The model can be created using the fit() function using the following engines:

• R: "flexsurv"

References

Jackson, C. (2016). flexsurv: A Platform for Parametric Survival Modeling in R. Journal of Statistical Software, 70(8), 1 - 33.

See Also

varying(), fit(), survival::Surv()

Examples

# NOT RUN {
surv_reg()
# Parameters can be represented by a placeholder:
surv_reg(dist = varying())

# Examples of using recipes with the `fit` function

library(dplyr)
library(recipes)
library(survival)
data(lung)

surv_rec <- recipe(time ~ ., data = lung) %>%
  add_role(status, new_role = "censoring var") %>%
  # exclude some vars from being in the model
  add_role(inst, sex, ph.karno, pat.karno, meal.cal, wt.loss,
           new_role = "other variables")

log_normal_mod <- surv_reg(dist = "lnorm")

fit(log_normal_mod, recipe = surv_rec, data = lung, engine = "flexsurv")

# make the normal variance be a function of gender:

strata_model <- surv_rec %>%
  add_role(sex, new_role = "sdlog")

fit(log_normal_mod, recipe = strata_model, data = lung, engine = "flexsurv")

model <- surv_reg(dist = "weibull")
model
update(model, dist = "lnorm")
# }