mlr_learners_surv.parametric: Survival Fully Parametric Learner

In mlr-org/mlr3extralearners: Extra Learners For mlr3

Survival Fully Parametric Learner

Description

Parametric survival model. Calls survivalmodels::parametric() from package 'survivalmodels'.

Details

This learner allows you to choose a distribution and a model form to compose a predicted survival probability distribution S(t).

The predict method is implemented in survivalmodels::predict.parametric(). Our implementation is more efficient for composition to distributions than survival::predict.survreg().

The available model forms with their respective survival functions, are as follows:

• Accelerated Failure Time (aft)

  S(t) = S_0(\frac{t}{exp(lp)})

• Proportional Hazards (ph)

  S(t) = S_0(t)^{exp(lp)}

• Proportional Odds (po)

  S(t) = \frac{S_0(t)}{exp(-lp) + (1-exp(-lp)) S_0(t)}

• Tobit (tobit)

  S(t) = 1 - \Phi((t - lp)/s)

where S_0 is the estimated baseline survival distribution (in this case with a given parametric form), lp is the predicted linear predictor, \Phi is the cdf of a N(0, 1) distribution, and s is the fitted scale parameter.

Whilst any combination of distribution and model form is possible, this does not mean it will necessarily create a sensible or interpretable prediction. The following combinations are 'sensible' (we note that ones mostly used in the literature):

• dist = "gaussian"; form = "tobit";

• dist = "weibull"; form = "ph"; (fairly used)

• dist = "exponential"; form = "ph";

• dist = "weibull"; form = "aft"; (fairly used, default option)

• dist = "exponential"; form = "aft";

• dist = "loglogistic"; form = "aft"; (fairly used)

• dist = "lognormal"; form = "aft";

• dist = "loglogistic"; form = "po";

Prediction types

This learner returns three prediction types:

1. lp: a vector of linear predictors (relative risk scores), one per test observation. lp is predicted using the formula lp = X\beta where X are the variables in the test data set and \beta are the fitted coefficients.

2. crank: same as lp.

3. distr: a survival matrix in two dimensions, where observations are represented in rows and time points in columns. The distribution distr is composed using the lp predictions and specifying a model form in the form hyper-parameter, see Details. The survival matrix uses the unique time points from the training set. The parameter ntime allows to adjust the granularity of these time points to any number (e.g. 150).

Custom mlr3 parameters

• discrete determines the class of the returned survival probability distribution. If FALSE, vectorized continuous probability distributions are returned using distr6::VectorDistribution, otherwise a distr6::Matdist object, which is faster for calculating survival measures that require a distr prediction type. Default option is TRUE.

Dictionary

This Learner can be instantiated via lrn():

lrn("surv.parametric")

Meta Information

• Task type: “surv”

• Predict Types: “crank”, “distr”, “lp”

• Feature Types: “logical”, “integer”, “numeric”, “factor”

• Required Packages: mlr3, mlr3proba, mlr3extralearners, survival, pracma

Parameters

Id	Type	Default	Levels	Range
form	character	aft	aft, ph, po, tobit	-
na.action	untyped	-		-
dist	character	weibull	weibull, exponential, gaussian, lognormal, loglogistic	-
parms	untyped	-		-
init	untyped	-		-
scale	numeric	0		[0, \infty)
maxiter	integer	30		(-\infty, \infty)
rel.tolerance	numeric	1e-09		(-\infty, \infty)
toler.chol	numeric	1e-10		(-\infty, \infty)
debug	integer	0		[0, 1]
outer.max	integer	10		(-\infty, \infty)
robust	logical	FALSE	TRUE, FALSE	-
score	logical	FALSE	TRUE, FALSE	-
cluster	untyped	-		-
discrete	logical	-	TRUE, FALSE	-
ntime	integer	NULL		[1, \infty)
round_time	integer	2		[0, \infty)

Installation

Package 'survivalmodels' is not on CRAN and has to be install from GitHub via remotes::install_github("RaphaelS1/survivalmodels").

Super classes

mlr3::Learner -> mlr3proba::LearnerSurv -> LearnerSurvParametric

Methods

Public methods

• LearnerSurvParametric$new()

• LearnerSurvParametric$clone()

Inherited methods

• mlr3::Learner$base_learner()
• mlr3::Learner$encapsulate()
• mlr3::Learner$format()
• mlr3::Learner$help()
• mlr3::Learner$predict()
• mlr3::Learner$predict_newdata()
• mlr3::Learner$print()
• mlr3::Learner$reset()
• mlr3::Learner$train()

---

Method new()

Creates a new instance of this R6 class. returned risk from survivalmodels is hp-style ie higher value => higher risk

Usage

LearnerSurvParametric$new()

---

Method clone()

The objects of this class are cloneable with this method.

Usage

LearnerSurvParametric$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Author(s)

bblodfon

References

Kalbfleisch, D J, Prentice, L R (2011). The statistical analysis of failure time data. John Wiley & Sons.

See Also

• Dictionary of Learners: mlr3::mlr_learners.

• as.data.table(mlr_learners) for a table of available Learners in the running session (depending on the loaded packages).

• Chapter in the mlr3book: https://mlr3book.mlr-org.com/basics.html#learners

• mlr3learners for a selection of recommended learners.

• mlr3cluster for unsupervised clustering learners.

• mlr3pipelines to combine learners with pre- and postprocessing steps.

• mlr3tuning for tuning of hyperparameters, mlr3tuningspaces for established default tuning spaces.

Examples

# Define the Learner
learner = mlr3::lrn("surv.parametric")
print(learner)

# Define a Task
task = mlr3::tsk("grace")

# Create train and test set
ids = mlr3::partition(task)

# Train the learner on the training ids
learner$train(task, row_ids = ids$train)

print(learner$model)


# Make predictions for the test rows
predictions = learner$predict(task, row_ids = ids$test)

# Score the predictions
predictions$score()

mlr-org/mlr3extralearners documentation built on Nov. 11, 2024, 11:11 a.m.