parsnip (version 0.1.1)

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 set_engine(). 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)
# S3 method for surv_reg
update(object, parameters = NULL, dist = NULL, 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.

object

A survival regression model specification.

parameters

A 1-row tibble or named list with main parameters to update. If the individual arguments are used, these will supersede the values in parameters. Also, using engine arguments in this object will result in an error.

fresh

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

...

Not used for update().

Engine Details

Engines may have pre-set default arguments when executing the model fit call. For this type of model, the template of the fit calls are below.

flexsurv

surv_reg() %>% 
  set_engine("flexsurv") %>% 
  set_mode("regression") %>% 
  translate()

## Parametric Survival Regression Model Specification (regression)
## 
## Computational engine: flexsurv 
## 
## Model fit template:
## flexsurv::flexsurvreg(formula = missing_arg(), data = missing_arg(), 
##     weights = missing_arg())

survival

surv_reg() %>% 
  set_engine("survival") %>% 
  set_mode("regression") %>% 
  translate()

## Parametric Survival Regression Model Specification (regression)
## 
## Computational engine: survival 
## 
## Model fit template:
## survival::survreg(formula = missing_arg(), data = missing_arg(), 
##     weights = missing_arg(), model = TRUE)

Note that model = TRUE is needed to produce quantile predictions when there is a stratification variable and can be overridden in other cases.

Parameter translations

The standardized parameter names in parsnip can be mapped to their original names in each engine that has main parameters:

parsnip	flexsurv	survival
dist	dist	dist

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

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

For surv_reg(), the mode will always be "regression".

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

• R: "flexsurv", "survival" (the default)

References

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

See Also

fit(), survival::Surv()

Examples

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

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