Package 'mlr3proba'

Description

Provides extensions for probabilistic supervised learning for 'mlr3'. This includes extending the regression task to probabilistic and interval regression, adding a survival task, and other specialized models, predictions, and measures.

Author(s)

Maintainer: John Zobolas [email protected] (ORCID)

Authors:

• Raphael Sonabend [email protected] (ORCID)

• Franz Kiraly [email protected]

• Michel Lang [email protected] (ORCID)

• Philip Studener [email protected]

Other contributors:

• Nurul Ain Toha [email protected] [contributor]

• Andreas Bender [email protected] (ORCID) [contributor]

• Lukas Burk [email protected] (ORCID) [contributor]

• Maximilian Muecke [email protected] (ORCID) [contributor]

See Also

Useful links:

• https://mlr3proba.mlr-org.com

• https://github.com/mlr-org/mlr3proba

• Report bugs at https://github.com/mlr-org/mlr3proba/issues

Description

Internal helper function to easily return the correct survival predict types.

Usage

.surv_return(
  times = NULL,
  surv = NULL,
  crank = NULL,
  lp = NULL,
  response = NULL,
  which.curve = NULL
)

Arguments

References

Sonabend, Raphael, Bender, Andreas, Vollmer, Sebastian (2022). “Avoiding C-hacking when evaluating survival distribution predictions with discrimination measures.” Bioinformatics. ISSN 1367-4803, doi:10.1093/BIOINFORMATICS/BTAC451, https://academic.oup.com/bioinformatics/advance-article/doi/10.1093/bioinformatics/btac451/6640155.

Description

actg dataset from Hosmer et al. (2008)

Usage

actg

Format

id

Identification Code

time

Time to AIDS diagnosis or death (days).

censor

Event indicator. 1 = AIDS defining diagnosis, 0 = Otherwise.

time_d

Time to death (days)

censor_d

Event indicator for death (only). 1 = Death, 0 = Otherwise.

tx

Treatment indicator. 1 = Treatment includes IDV, 0 = Control group.

txgrp

Treatment group indicator. 1 = ZDV + 3TC. 2 = ZDV + 3TC + IDV. 3 = d4T + 3TC. 4 = d4T + 3TC + IDV.

strat2

CD4 stratum at screening. 0 = CD4 <= 50. 1 = CD4 > 50.

sexF

0 = Male. 1 = Female.

raceth

Race/Ethnicity. 1 = White Non-Hispanic. 2 = Black Non-Hispanic. 3 = Hispanic. 4 = Asian, Pacific Islander. 5 = American Indian, Alaskan Native. 6 = Other/unknown.

ivdrug

IV drug use history. 1 = Never. 2 = Currently. 3 = Previously.

hemophil

Hemophiliac. 1 = Yes. 0 = No.

karnof

Karnofsky Performance Scale. 100 = Normal; no complaint no evidence of disease. 90 = Normal activity possible; minor signs/symptoms of disease. 80 = Normal activity with effort; some signs/symptoms of disease. 70 = Cares for self; normal activity/active work not possible.

cd4

Baseline CD4 count (Cells/Milliliter).

priorzdv

Months of prior ZDV use (months).

age

Age at Enrollment (years).

Source

https://onlinelibrary.wiley.com/doi/book/10.1002/9780470258019

References

Hosmer, D.W. and Lemeshow, S. and May, S. (2008) Applied Survival Analysis: Regression Modeling of Time to Event Data: Second Edition, John Wiley and Sons Inc., New York, NY

Description

Convert object to a PredictionDens.

Usage

as_prediction_dens(x, ...)

## S3 method for class 'PredictionDens'
as_prediction_dens(x, ...)

## S3 method for class 'data.frame'
as_prediction_dens(x, ...)

Arguments

Value

PredictionDens.

Examples

library(mlr3)
task = tsk("precip")
learner = lrn("dens.hist")
learner$train(task)
p = learner$predict(task)

# convert to a data.table
tab = as.data.table(p)

# convert back to a Prediction
as_prediction_dens(tab)

Description

Convert object to a PredictionSurv.

Usage

as_prediction_surv(x, ...)

## S3 method for class 'PredictionSurv'
as_prediction_surv(x, ...)

## S3 method for class 'data.frame'
as_prediction_surv(x, ...)

Arguments

Value

PredictionSurv.

Examples

library(mlr3)
task = tsk("rats")
learner = lrn("surv.coxph")
learner$train(task)
p = learner$predict(task)

# convert to a data.table
tab = as.data.table(p)

# convert back to a Prediction
as_prediction_surv(tab)

Description

Convert object to a density task (TaskDens).

Usage

as_task_dens(x, ...)

## S3 method for class 'TaskDens'
as_task_dens(x, clone = FALSE, ...)

## S3 method for class 'data.frame'
as_task_dens(x, id = deparse(substitute(x)), ...)

## S3 method for class 'DataBackend'
as_task_dens(x, id = deparse(substitute(x)), ...)

Arguments

Description

Convert object to a survival task (TaskSurv).

Usage

as_task_surv(x, ...)

## S3 method for class 'TaskSurv'
as_task_surv(x, clone = FALSE, ...)

## S3 method for class 'data.frame'
as_task_surv(
  x,
  time = "time",
  event = "event",
  time2,
  type = "right",
  id = deparse(substitute(x)),
  ...
)

## S3 method for class 'DataBackend'
as_task_surv(
  x,
  time = "time",
  event = "event",
  time2,
  type = "right",
  id = deparse(substitute(x)),
  ...
)

## S3 method for class 'formula'
as_task_surv(x, data, id = deparse(substitute(data)), ...)

Arguments

Description

Asserts x is a survival::Surv object with added checks

Usage

assert_surv(
  x,
  len = NULL,
  any.missing = TRUE,
  null.ok = FALSE,
  .var.name = vname(x)
)

Arguments

Description

Asserts if the given input matrix is a (discrete) survival probabilities matrix using Rcpp code. The following checks are performed:

1. All values are probabilities, i.e. $S(t) \in [0,1]$

2. Column names correspond to time-points and should therefore be coercable to numeric and increasing

3. Per row/observation, the survival probabilities decrease non-strictly, i.e. $S(t) \ge S(t+1)$

Usage

assert_surv_matrix(x)

Arguments

Value

if the assertion fails an error occurs, otherwise NULL is returned invisibly.

Examples

x = matrix(data = c(1,0.6,0.4,0.8,0.8,0.7), nrow = 2, ncol = 3, byrow = TRUE)
colnames(x) = c(12, 34, 42)
x

assert_surv_matrix(x)

Description

Generates plots for PredictionSurv, depending on argument type:

• "calib" (default): Calibration plot comparing the average predicted survival distribution to a Kaplan-Meier prediction, this is not a comparison of a stratified crank or lp prediction. object must have distr prediction. geom_line() is used for comparison split between the prediction (Pred) and Kaplan-Meier estimate (KM). In addition labels are added for the x (T) and y (S(T)) axes.

• "dcalib": Distribution calibration plot. A model is D-calibrated if X% of deaths occur before the X/100 quantile of the predicted distribution, e.g. if 50% of observations die before their predicted median survival time. A model is D-calibrated if the resulting plot lies on x = y.

• "preds": Matplots the survival curves for all predictions

Usage

## S3 method for class 'PredictionSurv'
autoplot(
  object,
  type = "calib",
  task = NULL,
  row_ids = NULL,
  times = NULL,
  xyline = TRUE,
  cuts = 11L,
  theme = theme_minimal(),
  extend_quantile = FALSE,
  ...
)

Arguments

References

Haider H, Hoehn B, Davis S, Greiner R (2020). “Effective Ways to Build and Evaluate Individual Survival Distributions.” Journal of Machine Learning Research, 21(85), 1-63. https://jmlr.org/papers/v21/18-772.html.

Examples

library(mlr3)
library(mlr3proba)
library(mlr3viz)

learn = lrn("surv.coxph")
task = tsk("unemployment")
p = learn$train(task, row_ids = 1:300)$predict(task, row_ids = 301:400)

# calibration by comparison of average prediction to Kaplan-Meier
autoplot(p, type = "calib", task = task, row_ids = 301:400)

# Distribution-calibration (D-Calibration)
autoplot(p, type = "dcalib")

# Predictions
autoplot(p, type = "preds")

Description

Generates plots for TaskDens.

Usage

## S3 method for class 'TaskDens'
autoplot(object, type = "dens", theme = theme_minimal(), ...)

Arguments

Value

ggplot2::ggplot() object.

Examples

library(mlr3)
library(mlr3proba)
library(mlr3viz)
library(ggplot2)
task = tsk("precip")

head(fortify(task))
autoplot(task, bins = 15)
autoplot(task, type = "freq", bins = 15)
autoplot(task, type = "overlay", bins = 15)
autoplot(task, type = "freqpoly", bins = 15)

Description

Generates plots for TaskSurv, depending on argument type:

• "target": Calls GGally::ggsurv() on a survival::survfit() object. This computes the Kaplan-Meier survival curve for the observations if this task.

• "duo": Passes data and additional arguments down to GGally::ggduo(). columnsX is target, columnsY is features.

• "pairs": Passes data and additional arguments down to GGally::ggpairs(). Color is set to target column.

Usage

## S3 method for class 'TaskSurv'
autoplot(
  object,
  type = "target",
  theme = theme_minimal(),
  reverse = FALSE,
  ...
)

Arguments

Value

ggplot2::ggplot() object.

Examples

library(mlr3)
library(mlr3viz)
library(mlr3proba)
library(ggplot2)

task = tsk("lung")

head(fortify(task))
autoplot(task) # KM
autoplot(task) # KM of the censoring distribution
autoplot(task, rhs = "sex")
autoplot(task, type = "duo")

Description

Helper function to compose a survival distribution (or cumulative hazard) from the relative risk predictions (linear predictors, lp) of a proportional hazards model (e.g. a Cox-type model).

Usage

breslow(times, status, lp_train, lp_test, eval_times = NULL, type = "surv")

Arguments

Details

We estimate the survival probability of individual $i$ (from the test set), at time point $t$ as follows:

$S_i(t) = e^{-H_i(t)} = e^{-\hat{H}_0(t) \times e^{lp_i}}$

where:

• $H_i(t)$ is the cumulative hazard function for individual $i$

• $\hat{H}_0(t)$ is Breslow's estimator for the cumulative baseline hazard. Estimation requires the training set's times and status as well the risk predictions (lp_train).

• $lp_i$ is the risk prediction (linear predictor) of individual $i$ on the test set.

Breslow's approach uses a non-parametric maximum likelihood estimation of the cumulative baseline hazard function:

$\hat{H}_0(t) = \sum_{i=1}^n{\frac{I(T_i \le t)\delta_i} {\sum\nolimits_{j \in R_i}e^{lp_j}}}$

where:

• $t$ is the vector of time points (unique and sorted, from the train set)

• $n$ is number of events (train set)

• $T$ is the vector of event times (train set)

• $\delta$ is the status indicator (1 = event or 0 = censored)

• $R_i$ is the risk set (number of individuals at risk just before event $i$)

• $lp_j$ is the risk prediction (linear predictor) of individual $j$ (who is part of the risk set $R_i$) on the train set.

We employ constant interpolation to estimate the cumulative baseline hazards, extending from the observed unique event times to the specified evaluation times (eval_times). Any values falling outside the range of the estimated times are assigned as follows:

$\hat{H}_0(eval\_times < min(t)) = 0$

and

$\hat{H}_0(eval\_times > max(t)) = \hat{H}_0(max(t))$

Note that in the rare event of lp predictions being Inf or -Inf, the resulting cumulative hazard values become NaN, which we substitute with Inf (and corresponding survival probabilities take the value of $0$).

For similar implementations, see gbm::basehaz.gbm(), C060::basesurv() and xgboost.surv::sgb_bhaz().

Value

a matrix (obs x times). Number of columns is equal to eval_times and number of rows is equal to the number of test observations (i.e. the length of the lp_test vector). Depending on the type argument, the matrix can have either survival probabilities (0-1) or cumulative hazard estimates (0-Inf).

References

Cox DR (1972). “Regression Models and Life-Tables.” Journal of the Royal Statistical Society: Series B (Methodological), 34(2), 187–202. doi:10.1111/j.2517-6161.1972.tb00899.x.

Lin, Y. D (2007). “On the Breslow estimator.” Lifetime Data Analysis, 13(4), 471-480. doi:10.1007/s10985-007-9048-y.

Examples

task = tsk("rats")
part = partition(task, ratio = 0.8)

learner = lrn("surv.coxph")
learner$train(task, part$train)
p_train = learner$predict(task, part$train)
p_test = learner$predict(task, part$test)

surv = breslow(times = task$times(part$train), status = task$status(part$train),
               lp_train = p_train$lp, lp_test = p_test$lp)
head(surv)

Description

gbcs dataset from Hosmer et al. (2008)

Usage

gbcs

Format

id

Identification Code

diagdate

Date of diagnosis.

recdate

Date of recurrence free survival.

deathdate

Date of death.

age

Age at diagnosis (years).

menopause

Menopausal status. 1 = Yes, 0 = No.

hormone

Hormone therapy. 1 = Yes. 0 = No.

size

Tumor size (mm).

grade

Tumor grade (1-3).

nodes

Number of lymph nodes.

prog_recp

Number of progesterone receptors.

estrg_recp

Number of estrogen receptors.

rectime

Time to recurrence (days).

censrec

Recurrence status. 1 = Recurrence. 0 = Censored.

survtime

Time to death (days).

censdead

Censoring status. 1 = Death. 0 = Censored.

Source

https://onlinelibrary.wiley.com/doi/book/10.1002/9780470258019

References

Hosmer, D.W. and Lemeshow, S. and May, S. (2008) Applied Survival Analysis: Regression Modeling of Time to Event Data: Second Edition, John Wiley and Sons Inc., New York, NY

Description

Many methods can be used to reduce a discrete survival distribution prediction (i.e. matrix) to a relative risk / ranking prediction, see Sonabend et al. (2022).

This function calculates a relative risk score as the sum of the predicted cumulative hazard function, also called ensemble/expected mortality. This risk score can be loosely interpreted as the expected number of deaths for patients with similar characteristics, see Ishwaran et al. (2008) and has no model or survival distribution assumptions.

Usage

get_mortality(x)

Arguments

Value

a numeric vector of the mortality risk scores, one per row of the input survival matrix.

References

Sonabend, Raphael, Bender, Andreas, Vollmer, Sebastian (2022). “Avoiding C-hacking when evaluating survival distribution predictions with discrimination measures.” Bioinformatics. ISSN 1367-4803, doi:10.1093/BIOINFORMATICS/BTAC451, https://academic.oup.com/bioinformatics/advance-article/doi/10.1093/bioinformatics/btac451/6640155.

Ishwaran, Hemant, Kogalur, B U, Blackstone, H E, Lauer, S M, others (2008). “Random survival forests.” The Annals of applied statistics, 2(3), 841–860.

Examples

n = 10 # number of observations
k = 50 # time points

# Create the matrix with random values between 0 and 1
mat = matrix(runif(n * k, min = 0, max = 1), nrow = n, ncol = k)

# transform it to a survival matrix
surv_mat = t(apply(mat, 1L, function(row) sort(row, decreasing = TRUE)))
colnames(surv_mat) = 1:k # time points

# get mortality scores (the larger, the more risk)
mort = get_mortality(surv_mat)
mort

Description

grace dataset from Hosmer et al. (2008)

Usage

grace

Format

id

Identification Code

days

Follow up time.

death

Censoring indicator. 1 = Death. 0 = Censored.

revasc

Revascularization Performed. 1 = Yes. 0 = No.

revascdays

Days to revascularization after admission.

los

Length of hospital stay (days).

age

Age at admission (years).

sysbp

Systolic blood pressure on admission (mm Hg).

stchange

ST-segment deviation on index ECG. 1 = Yes. 0 = No.

Source

https://onlinelibrary.wiley.com/doi/book/10.1002/9780470258019

References

Hosmer, D.W. and Lemeshow, S. and May, S. (2008) Applied Survival Analysis: Regression Modeling of Time to Event Data: Second Edition, John Wiley and Sons Inc., New York, NY

Description

This Learner specializes Learner for density estimation problems:

• task_type is set to "dens"

• Creates Predictions of class PredictionDens.

• Possible values for predict_types are:

  • "pdf": Evaluates estimated probability density function for each value in the test set.

  • "cdf": Evaluates estimated cumulative distribution function for each value in the test set.

Super class

mlr3::Learner -> LearnerDens

Methods

Public methods

• LearnerDens$new()

• LearnerDens$clone()

Method new()

Creates a new instance of this R6 class.

Usage

LearnerDens$new(
  id,
  param_set = ps(),
  predict_types = "cdf",
  feature_types = character(),
  properties = character(),
  data_formats = "data.table",
  packages = character(),
  label = NA_character_,
  man = NA_character_
)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

LearnerDens$clone(deep = FALSE)

Arguments

See Also

Other Learner: LearnerSurv

Examples

library(mlr3)
# get all density learners from mlr_learners:
lrns = mlr_learners$mget(mlr_learners$keys("^dens"))
names(lrns)

# get a specific learner from mlr_learners:
mlr_learners$get("dens.hist")
lrn("dens.hist")

Description

This Learner specializes Learner for survival problems:

• task_type is set to "surv"

• Creates Predictions of class PredictionSurv.

• Possible values for predict_types are:

  • "distr": Predicts a probability distribution for each observation in the test set, uses distr6.

  • "lp": Predicts a linear predictor for each observation in the test set.

  • "crank": Predicts a continuous ranking for each observation in the test set.

  • "response": Predicts a survival time for each observation in the test set.

Super class

mlr3::Learner -> LearnerSurv

Methods

Public methods

• LearnerSurv$new()

• LearnerSurv$clone()

Method new()

Creates a new instance of this R6 class.

Usage

LearnerSurv$new(
  id,
  param_set = ps(),
  predict_types = "distr",
  feature_types = character(),
  properties = character(),
  packages = character(),
  label = NA_character_,
  man = NA_character_
)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

LearnerSurv$clone(deep = FALSE)

Arguments

See Also

Other Learner: LearnerDens

Examples

library(mlr3)
# get all survival learners from mlr_learners:
lrns = mlr_learners$mget(mlr_learners$keys("^surv"))
names(lrns)

# get a specific learner from mlr_learners:
mlr_learners$get("surv.coxph")
lrn("surv.coxph")

Description

This measure specializes Measure for survival problems.

• task_type is set to "dens".

• Possible values for predict_type are "pdf" and "cdf".

Predefined measures can be found in the dictionary mlr3::mlr_measures.

Super class

mlr3::Measure -> MeasureDens

Methods

Public methods

• MeasureDens$new()

Method new()

Creates a new instance of this R6 class.

Usage

MeasureDens$new(
  id,
  param_set = ps(),
  range,
  minimize = NA,
  aggregator = NULL,
  properties = character(),
  predict_type = "pdf",
  task_properties = character(),
  packages = character(),
  label = NA_character_,
  man = NA_character_
)

Arguments

See Also

Default density measures: dens.logloss

Other Measure: MeasureSurv

Description

This measure specializes Measure for survival problems.

• task_type is set to "surv".

• Possible values for predict_type are "distr", "lp", "crank", and "response".

Predefined measures can be found in the dictionary mlr3::mlr_measures.

Super class

mlr3::Measure -> MeasureSurv

Methods

Public methods

• MeasureSurv$new()

• MeasureSurv$print()

Method new()

Creates a new instance of this R6 class.

Usage

MeasureSurv$new(
  id,
  param_set = ps(),
  range,
  minimize = NA,
  aggregator = NULL,
  properties = character(),
  predict_type = "distr",
  task_properties = character(),
  packages = character(),
  label = NA_character_,
  man = NA_character_,
  se = FALSE
)

Arguments

Method print()

Printer.

Usage

MeasureSurv$print()

See Also

Default survival measures: surv.cindex

Other Measure: MeasureDens

Description

This is an abstract class that should not be constructed directly.

Parameter details

• integrated (logical(1))
  If TRUE (default), returns the integrated score (eg across time points); otherwise, not integrated (eg at a single time point).

• times (numeric())
  If integrate == TRUE then a vector of time-points over which to integrate the score. If integrate == FALSE then a single time point at which to return the score.

Super classes

mlr3::Measure -> mlr3proba::MeasureSurv -> MeasureSurvAUC

Methods

Public methods

• MeasureSurvAUC$new()

• MeasureSurvAUC$clone()

Method new()

Creates a new instance of this R6 class.

Usage

MeasureSurvAUC$new(
  id,
  properties = character(),
  label = NA_character_,
  man = NA_character_,
  param_set = ps()
)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

MeasureSurvAUC$clone(deep = FALSE)

Arguments

Description

Wrapper around PipeOpCrankCompositor to simplify Graph creation.

Usage

pipeline_crankcompositor(
  learner,
  method = c("mort"),
  overwrite = FALSE,
  graph_learner = FALSE
)

Arguments

Value

mlr3pipelines::Graph or mlr3pipelines::GraphLearner

See Also

Other pipelines: mlr_graphs_distrcompositor, mlr_graphs_probregr, mlr_graphs_responsecompositor, mlr_graphs_survaverager, mlr_graphs_survbagging, mlr_graphs_survtoclassif_disctime, mlr_graphs_survtoregr

Examples

## Not run: 
if (requireNamespace("mlr3pipelines", quietly = TRUE)) {
  library("mlr3")
  library("mlr3pipelines")

  task = tsk("lung")
  part = partition(task)

  # change the crank prediction type of a Cox's model predictions
  grlrn = ppl(
    "crankcompositor",
    learner = lrn("surv.coxph"),
    method = "mort",
    overwrite = TRUE,
    graph_learner = TRUE
  )
  grlrn$train(task, part$train)
  grlrn$predict(task, part$test)
}

## End(Not run)

Description

Wrapper around PipeOpDistrCompositor or PipeOpBreslow to simplify Graph creation.

Usage

pipeline_distrcompositor(
  learner,
  estimator = "kaplan",
  form = "aft",
  overwrite = FALSE,
  graph_learner = FALSE
)

Arguments

Value

mlr3pipelines::Graph or mlr3pipelines::GraphLearner

See Also

Other pipelines: mlr_graphs_crankcompositor, mlr_graphs_probregr, mlr_graphs_responsecompositor, mlr_graphs_survaverager, mlr_graphs_survbagging, mlr_graphs_survtoclassif_disctime, mlr_graphs_survtoregr

Examples

## Not run: 
if (requireNamespace("mlr3pipelines", quietly = TRUE)) {
  library("mlr3pipelines")

  # let's change the distribution prediction of Cox (Breslow-based) to an AFT form:
  task = tsk("rats")
  grlrn = ppl(
    "distrcompositor",
    learner = lrn("surv.coxph"),
    estimator = "kaplan",
    form = "aft",
    overwrite = TRUE,
    graph_learner = TRUE
  )
  grlrn$train(task)
  grlrn$predict(task)
}

## End(Not run)

Description

Wrapper around PipeOpProbregr to simplify Graph creation.

Usage

pipeline_probregr(
  learner,
  learner_se = NULL,
  dist = "Uniform",
  graph_learner = FALSE
)

Arguments

Value

mlr3pipelines::Graph or mlr3pipelines::GraphLearner

See Also

Other pipelines: mlr_graphs_crankcompositor, mlr_graphs_distrcompositor, mlr_graphs_responsecompositor, mlr_graphs_survaverager, mlr_graphs_survbagging, mlr_graphs_survtoclassif_disctime, mlr_graphs_survtoregr

Examples

## Not run: 
if (requireNamespace("mlr3pipelines", quietly = TRUE) &&
  requireNamespace("rpart", quietly = TRUE)) {
  library("mlr3")
  library("mlr3pipelines")

  task = tsk("boston_housing")

  # method 1 - same learner for response and se
  pipe = ppl(
    "probregr",
    learner = lrn("regr.featureless", predict_type = "se"),
    dist = "Uniform"
  )
  pipe$train(task)
  pipe$predict(task)

  # method 2 - different learners for response and se
  pipe = ppl(
    "probregr",
    learner = lrn("regr.rpart"),
    learner_se = lrn("regr.featureless", predict_type = "se"),
    dist = "Normal"
  )
  pipe$train(task)
  pipe$predict(task)
}

## End(Not run)

Description

Wrapper around PipeOpResponseCompositor to simplify Graph creation.

Usage

pipeline_responsecompositor(
  learner,
  method = "rmst",
  cutoff_time = NULL,
  add_crank = FALSE,
  overwrite = FALSE,
  graph_learner = FALSE
)

Arguments

Value

mlr3pipelines::Graph or mlr3pipelines::GraphLearner

See Also

Other pipelines: mlr_graphs_crankcompositor, mlr_graphs_distrcompositor, mlr_graphs_probregr, mlr_graphs_survaverager, mlr_graphs_survbagging, mlr_graphs_survtoclassif_disctime, mlr_graphs_survtoregr

Examples

## Not run: 
if (requireNamespace("mlr3pipelines", quietly = TRUE)) {
  library("mlr3")
  library("mlr3pipelines")

  task = tsk("lung")
  part = partition(task)

  # add survival time prediction type to the predictions of a Cox model
  grlrn = ppl(
    "responsecompositor",
    learner = lrn("surv.coxph"),
    method = "rmst",
    overwrite = TRUE,
    graph_learner = TRUE
  )
  grlrn$train(task, part$train)
  grlrn$predict(task, part$test)
}

## End(Not run)

Description

Wrapper around PipeOpSurvAvg to simplify Graph creation.

Usage

pipeline_survaverager(learners, param_vals = list(), graph_learner = FALSE)

Arguments

Value

mlr3pipelines::Graph or mlr3pipelines::GraphLearner

See Also

Other pipelines: mlr_graphs_crankcompositor, mlr_graphs_distrcompositor, mlr_graphs_probregr, mlr_graphs_responsecompositor, mlr_graphs_survbagging, mlr_graphs_survtoclassif_disctime, mlr_graphs_survtoregr

Examples

## Not run: 
if (requireNamespace("mlr3pipelines", quietly = TRUE)) {
  library("mlr3")
  library("mlr3pipelines")

  task = tsk("rats")
  pipe = ppl(
    "survaverager",
    learners = lrns(c("surv.kaplan", "surv.coxph")),
    param_vals = list(weights = c(0.1, 0.9)),
    graph_learner = FALSE
  )
  pipe$train(task)
  pipe$predict(task)
}

## End(Not run)

Description

Wrapper around PipeOpSubsample and PipeOpSurvAvg to simplify Graph creation.

Usage

pipeline_survbagging(
  learner,
  iterations = 10,
  frac = 0.7,
  avg = TRUE,
  weights = 1,
  graph_learner = FALSE
)

Arguments

Details

Bagging (Bootstrap AGGregatING) is the process of bootstrapping data and aggregating the final predictions. Bootstrapping splits the data into B smaller datasets of a given size and is performed with PipeOpSubsample. Aggregation is the sample mean of deterministic predictions and a MixtureDistribution of distribution predictions. This can be further enhanced by using a weighted average by supplying weights.

Value

mlr3pipelines::Graph or mlr3pipelines::GraphLearner

mlr3pipelines::GraphLearner

See Also

Other pipelines: mlr_graphs_crankcompositor, mlr_graphs_distrcompositor, mlr_graphs_probregr, mlr_graphs_responsecompositor, mlr_graphs_survaverager, mlr_graphs_survtoclassif_disctime, mlr_graphs_survtoregr

Examples

## Not run: 
if (requireNamespace("mlr3pipelines", quietly = TRUE)) {
  library("mlr3")
  library("mlr3pipelines")

  task = tsk("rats")
  pipe = ppl(
    "survbagging",
    learner = lrn("surv.coxph"),
    iterations = 5,
    graph_learner = FALSE
  )
  pipe$train(task)
  pipe$predict(task)
}

## End(Not run)

Description

Wrapper around multiple PipeOps to help in creation of complex survival reduction methods.

Usage

pipeline_survtoclassif_disctime(
  learner,
  cut = NULL,
  max_time = NULL,
  rhs = NULL,
  graph_learner = FALSE
)

Arguments

Details

The pipeline consists of the following steps:

1. PipeOpTaskSurvClassifDiscTime Converts TaskSurv to a TaskClassif.

2. A LearnerClassif is fit and predicted on the new TaskClassif.

3. PipeOpPredClassifSurvDiscTime transforms the resulting PredictionClassif to PredictionSurv.

4. Optionally: PipeOpModelMatrix is used to transform the formula of the task before fitting the learner.

Value

mlr3pipelines::Graph or mlr3pipelines::GraphLearner

See Also

Other pipelines: mlr_graphs_crankcompositor, mlr_graphs_distrcompositor, mlr_graphs_probregr, mlr_graphs_responsecompositor, mlr_graphs_survaverager, mlr_graphs_survbagging, mlr_graphs_survtoregr

Examples

## Not run: 
if (requireNamespace("mlr3pipelines", quietly = TRUE) &&
    requireNamespace("mlr3learners", quietly = TRUE)) {

  library(mlr3)
  library(mlr3learners)
  library(mlr3pipelines)

  task = tsk("lung")
  part = partition(task)

  grlrn = ppl(
    "survtoclassif_disctime",
    learner = lrn("classif.log_reg"),
    cut = 4, # 4 equidistant time intervals
    graph_learner = TRUE
  )
  grlrn$train(task, row_ids = part$train)
  grlrn$predict(task, row_ids = part$test)
}

## End(Not run)

Description

Wrapper around multiple PipeOps to help in creation of complex survival reduction methods. Three reductions are currently implemented, see details.

Usage

pipeline_survtoregr(
  method = 1,
  regr_learner = lrn("regr.featureless"),
  distrcompose = TRUE,
  distr_estimator = lrn("surv.kaplan"),
  regr_se_learner = NULL,
  surv_learner = lrn("surv.coxph"),
  survregr_params = list(method = "ipcw", estimator = "kaplan", alpha = 1),
  distrcompose_params = list(form = "aft"),
  probregr_params = list(dist = "Uniform"),
  learnercv_params = list(resampling.method = "insample"),
  graph_learner = FALSE
)

Arguments

Details

Three reduction strategies are implemented, these are:

1. Survival to Deterministic Regression A

   1. PipeOpTaskSurvRegr Converts TaskSurv to TaskRegr.

   2. A LearnerRegr is fit and predicted on the new TaskRegr.

   3. PipeOpPredRegrSurv transforms the resulting PredictionRegr to PredictionSurv.

2. Survival to Probabilistic Regression

   1. PipeOpTaskSurvRegr Converts TaskSurv to TaskRegr.

   2. A LearnerRegr is fit on the new TaskRegr to predict response, optionally a second LearnerRegr can be fit to predict se.

   3. PipeOpProbregr composes a distr prediction from the learner(s).

   4. PipeOpPredRegrSurv transforms the resulting PredictionRegr to PredictionSurv.

3. Survival to Deterministic Regression B

   1. PipeOpLearnerCV cross-validates and makes predictions from a linear LearnerSurv with lp predict type on the original TaskSurv.

   2. PipeOpTaskSurvRegr transforms the lp predictions into the target of a TaskRegr with the same features as the original TaskSurv.

   3. A LearnerRegr is fit and predicted on the new TaskRegr.

   4. PipeOpPredRegrSurv transforms the resulting PredictionRegr to PredictionSurv.

   5. Optionally: PipeOpDistrCompositor is used to compose a distr predict_type from the predicted lp predict_type.

Interpretation:

1. Once a dataset has censoring removed (by a given method) then a regression learner can predict the survival time as the response.

2. This is a very similar reduction to the first method with the main difference being the distribution composition. In the first case this is composed in a survival framework by assuming a linear model form and baseline hazard estimator, in the second case the composition is in a regression framework. The latter case could result in problematic negative predictions and should therefore be interpreted with caution, however a wider choice of distributions makes it a more flexible composition.

3. This is a rarer use-case that bypasses censoring not be removing it but instead by first predicting the linear predictor from a survival model and fitting a regression model on these predictions. The resulting regression predictions can then be viewed as the linear predictors of the new data, which can ultimately be composed to a distribution.

Value

mlr3pipelines::Graph or mlr3pipelines::GraphLearner

See Also

Other pipelines: mlr_graphs_crankcompositor, mlr_graphs_distrcompositor, mlr_graphs_probregr, mlr_graphs_responsecompositor, mlr_graphs_survaverager, mlr_graphs_survbagging, mlr_graphs_survtoclassif_disctime

Examples

## Not run: 
if (requireNamespace("mlr3pipelines", quietly = TRUE)) {
  library("mlr3")
  library("mlr3pipelines")

  task = tsk("rats")

  # method 1 with censoring deletion, compose to distribution
  pipe = ppl(
    "survtoregr",
    method = 1,
    regr_learner = lrn("regr.featureless"),
    survregr_params = list(method = "delete")
  )
  pipe$train(task)
  pipe$predict(task)

  # method 2 with censoring imputation (mrl), one regr learner
  pipe = ppl(
    "survtoregr",
    method = 2,
    regr_learner = lrn("regr.featureless", predict_type = "se"),
    survregr_params = list(method = "mrl")
  )
  pipe$train(task)
  pipe$predict(task)

  # method 3 with censoring omission and no composition, insample resampling
  pipe = ppl(
    "survtoregr",
    method = 3,
    regr_learner = lrn("regr.featureless"),
    distrcompose = FALSE,
    surv_learner = lrn("surv.coxph"),
    survregr_params = list(method = "omission")
  )
  pipe$train(task)
  pipe$predict(task)
}

## End(Not run)

Description

Calls graphics::hist() and the result is coerced to a distr6::Distribution.

Dictionary

This Learner can be instantiated via the dictionary mlr_learners or with the associated sugar function lrn():

LearnerDensHistogram$new()
mlr_learners$get("dens.hist")
lrn("dens.hist")

Meta Information

• Type: "dens"

• Predict Types: ⁠pdf, cdf, distr⁠

• Feature Types: ⁠integer, numeric⁠

• Properties: -

• Packages: mlr3 mlr3proba distr6

Super classes

mlr3::Learner -> mlr3proba::LearnerDens -> LearnerDensHistogram

Methods

Public methods

• LearnerDensHistogram$new()

• LearnerDensHistogram$clone()

Method new()

Creates a new instance of this R6 class.

Usage

LearnerDensHistogram$new()

Method clone()

The objects of this class are cloneable with this method.

Usage

LearnerDensHistogram$clone(deep = FALSE)

Arguments

See Also

Other density estimators: mlr_learners_dens.kde

Description

Calls kernels implemented in distr6 and the result is coerced to a distr6::Distribution.

Details

The default bandwidth uses Silverman's rule-of-thumb for Gaussian kernels, however for non-Gaussian kernels it is recommended to use mlr3tuning to tune the bandwidth with cross-validation. Other density learners can be used for automated bandwidth selection. The default kernel is Epanechnikov (chosen to reduce dependencies).

Dictionary

This Learner can be instantiated via the dictionary mlr_learners or with the associated sugar function lrn():

LearnerDensKDE$new()
mlr_learners$get("dens.kde")
lrn("dens.kde")

Meta Information

• Type: "dens"

• Predict Types: ⁠pdf, distr⁠

• Feature Types: ⁠integer, numeric⁠

• Properties: missings

• Packages: mlr3 mlr3proba distr6

Super classes

mlr3::Learner -> mlr3proba::LearnerDens -> LearnerDensKDE

Methods

Public methods

• LearnerDensKDE$new()

• LearnerDensKDE$clone()

Method new()

Creates a new instance of this R6 class.

Usage

LearnerDensKDE$new()

Method clone()

The objects of this class are cloneable with this method.

Usage

LearnerDensKDE$clone(deep = FALSE)

Arguments

References

Silverman, W. B (1986). Density Estimation for Statistics and Data Analysis. Chapman & Hall, London.

See Also

Other density estimators: mlr_learners_dens.hist

Description

Calls survival::coxph().

• lp is predicted by survival::predict.coxph()

• distr is predicted by survival::survfit.coxph()

• crank is identical to lp

Dictionary

This Learner can be instantiated via the dictionary mlr_learners or with the associated sugar function lrn():

LearnerSurvCoxPH$new()
mlr_learners$get("surv.coxph")
lrn("surv.coxph")

Meta Information

• Task type: “surv”

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

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

• Required Packages: mlr3, mlr3proba, survival, distr6

Parameters

Super classes

mlr3::Learner -> mlr3proba::LearnerSurv -> LearnerSurvCoxPH

Methods

Public methods

• LearnerSurvCoxPH$new()

• LearnerSurvCoxPH$clone()

Method new()

Creates a new instance of this R6 class.

Usage

LearnerSurvCoxPH$new()

Method clone()

The objects of this class are cloneable with this method.

Usage

LearnerSurvCoxPH$clone(deep = FALSE)

Arguments

References

Cox DR (1972). “Regression Models and Life-Tables.” Journal of the Royal Statistical Society: Series B (Methodological), 34(2), 187–202. doi:10.1111/j.2517-6161.1972.tb00899.x.

See Also

Other survival learners: mlr_learners_surv.kaplan, mlr_learners_surv.rpart

Description

Calls survival::survfit().

• distr is predicted by estimating the survival function with survival::survfit()

• crank is predicted as the sum of the cumulative hazard function (expected mortality) derived from the survival distribution, distr

Dictionary

This Learner can be instantiated via the dictionary mlr_learners or with the associated sugar function lrn():

LearnerSurvKaplan$new()
mlr_learners$get("surv.kaplan")
lrn("surv.kaplan")

Meta Information

• Task type: “surv”

• Predict Types: “crank”, “distr”

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

• Required Packages: mlr3, mlr3proba, survival, distr6

Parameters

Empty ParamSet

Super classes

mlr3::Learner -> mlr3proba::LearnerSurv -> LearnerSurvKaplan

Methods

Public methods

• LearnerSurvKaplan$new()

• LearnerSurvKaplan$clone()

Method new()

Creates a new instance of this R6 class.

Usage

LearnerSurvKaplan$new()

Method clone()

The objects of this class are cloneable with this method.

Usage

LearnerSurvKaplan$clone(deep = FALSE)

Arguments

References

Kaplan EL, Meier P (1958). “Nonparametric Estimation from Incomplete Observations.” Journal of the American Statistical Association, 53(282), 457–481. doi:10.1080/01621459.1958.10501452.

See Also

Other survival learners: mlr_learners_surv.coxph, mlr_learners_surv.rpart

Description

Calls rpart::rpart().

• crank is predicted using rpart::predict.rpart()

Dictionary

This Learner can be instantiated via the dictionary mlr_learners or with the associated sugar function lrn():

LearnerSurvRpart$new()
mlr_learners$get("surv.rpart")
lrn("surv.rpart")

Meta Information

• Task type: “surv”

• Predict Types: “crank”

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

• Required Packages: mlr3, mlr3proba, rpart, distr6, survival

Parameters

Initial parameter values

• xval is set to 0 in order to save some computation time.

• model has been renamed to keep_model.

Super classes

mlr3::Learner -> mlr3proba::LearnerSurv -> LearnerSurvRpart

Methods

Public methods

• LearnerSurvRpart$new()

• LearnerSurvRpart$importance()

• LearnerSurvRpart$selected_features()

• LearnerSurvRpart$clone()

Method new()

Creates a new instance of this R6 class.

Usage

LearnerSurvRpart$new()

Method importance()

The importance scores are extracted from the model slot variable.importance.

Usage

LearnerSurvRpart$importance()

Returns

Named numeric().

Method selected_features()

Selected features are extracted from the model slot frame$var.

Usage

LearnerSurvRpart$selected_features()

Returns

character().

Method clone()

The objects of this class are cloneable with this method.

Usage

LearnerSurvRpart$clone(deep = FALSE)

Arguments

References

Breiman L, Friedman JH, Olshen RA, Stone CJ (1984). Classification And Regression Trees. Routledge. doi:10.1201/9781315139470.

See Also

Other survival learners: mlr_learners_surv.coxph, mlr_learners_surv.kaplan

Description

Calculates the cross-entropy, or logarithmic (log), loss.

Details

The Log Loss, in the context of probabilistic predictions, is defined as the negative log probability density function, $f$, evaluated at the observed value, $y$,

$L(f, y) = -\log(f(y))$

Dictionary

This Measure can be instantiated via the dictionary mlr_measures or with the associated sugar function msr():

MeasureDensLogloss$new()
mlr_measures$get("dens.logloss")
msr("dens.logloss")

Parameters

Meta Information

• Type: "density"

• Range: $[0, \infty)$

• Minimize: TRUE

• Required prediction: pdf

Parameter details

• eps (numeric(1))
  Very small number to substitute zero values in order to prevent errors in e.g. log(0) and/or division-by-zero calculations. Default value is 1e-15.

Super classes

mlr3::Measure -> mlr3proba::MeasureDens -> MeasureDensLogloss

Methods

Public methods

• MeasureDensLogloss$new()

• MeasureDensLogloss$clone()

Method new()

Creates a new instance of this R6 class.

Usage

MeasureDensLogloss$new()

Method clone()

The objects of this class are cloneable with this method.

Usage

MeasureDensLogloss$clone(deep = FALSE)

Arguments

Description

Calculates the cross-entropy, or logarithmic (log), loss.

Details

The Log Loss, in the context of probabilistic predictions, is defined as the negative log probability density function, $f$, evaluated at the observed value, $y$,

$L(f, y) = -\log(f(y))$

Parameters

Meta Information

• Type: "regr"

• Range: $[0, \infty)$

• Minimize: TRUE

• Required prediction: distr

Parameter details

• eps (numeric(1))
  Very small number to substitute zero values in order to prevent errors in e.g. log(0) and/or division-by-zero calculations. Default value is 1e-15.

Super classes

mlr3::Measure -> mlr3::MeasureRegr -> MeasureRegrLogloss

Methods

Public methods

• MeasureRegrLogloss$new()

• MeasureRegrLogloss$clone()

Method new()

Creates a new instance of this R6 class.

Usage

MeasureRegrLogloss$new()

Method clone()

The objects of this class are cloneable with this method.

Usage

MeasureRegrLogloss$clone(deep = FALSE)

Arguments

Description

This calibration method is defined by estimating

$\hat{\alpha} = \sum \delta_i / \sum H_i(T_i)$

where $\delta$ is the observed censoring indicator from the test data, $H_i$ is the predicted cumulative hazard, and $T_i$ is the observed survival time (event or censoring).

The standard error is given by

$\hat{\alpha_{se}} = exp(1/\sqrt{\sum \delta_i})$

The model is well calibrated if the estimated $\hat{\alpha}$ coefficient (returned score) is equal to 1.

Dictionary

This Measure can be instantiated via the dictionary mlr_measures or with the associated sugar function msr():

MeasureSurvCalibrationAlpha$new()
mlr_measures$get("surv.calib_alpha")
msr("surv.calib_alpha")

Parameters

Meta Information

• Type: "surv"

• Range: $(-\infty, \infty)$

• Minimize: FALSE

• Required prediction: distr

Parameter details

• eps (numeric(1))
  Very small number to substitute zero values in order to prevent errors in e.g. log(0) and/or division-by-zero calculations. Default value is 0.001.

• se (logical(1))
  If TRUE then return standard error of the measure, otherwise the score itself (default).

• method (character(1))
  Returns $\hat{\alpha}$ if equal to ratio (default) and $|1-\hat{\alpha}|$ if equal to diff. With diff, the output score can be minimized and for example be used for tuning purposes. This parameter takes effect only if se is FALSE.

• truncate (double(1))
  This parameter controls the upper bound of the output score. We use truncate = Inf by default (so no truncation) and it's up to the user to set this up reasonably given the chosen method. Note that truncation may severely limit automated tuning with this measure using method = diff.

Super classes

mlr3::Measure -> mlr3proba::MeasureSurv -> MeasureSurvCalibrationAlpha

Methods

Public methods

• MeasureSurvCalibrationAlpha$new()

• MeasureSurvCalibrationAlpha$clone()

Method new()

Creates a new instance of this R6 class.

Usage

MeasureSurvCalibrationAlpha$new(method = "ratio")

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

MeasureSurvCalibrationAlpha$clone(deep = FALSE)

Arguments

References

Van Houwelingen, C. H (2000). “Validation, calibration, revision and combination of prognostic survival models.” Statistics in Medicine, 19(24), 3401–3415. doi:10.1002/1097-0258(20001230)19:24<3401::AID-SIM554>3.0.CO;2-2.

See Also

Other survival measures: mlr_measures_surv.calib_beta, mlr_measures_surv.chambless_auc, mlr_measures_surv.cindex, mlr_measures_surv.dcalib, mlr_measures_surv.graf, mlr_measures_surv.hung_auc, mlr_measures_surv.intlogloss, mlr_measures_surv.logloss, mlr_measures_surv.mae, mlr_measures_surv.mse, mlr_measures_surv.nagelk_r2, mlr_measures_surv.oquigley_r2, mlr_measures_surv.rcll, mlr_measures_surv.rmse, mlr_measures_surv.schmid, mlr_measures_surv.song_auc, mlr_measures_surv.song_tnr, mlr_measures_surv.song_tpr, mlr_measures_surv.uno_auc, mlr_measures_surv.uno_tnr, mlr_measures_surv.uno_tpr, mlr_measures_surv.xu_r2

Other calibration survival measures: mlr_measures_surv.calib_beta, mlr_measures_surv.dcalib

Other distr survival measures: mlr_measures_surv.dcalib, mlr_measures_surv.graf, mlr_measures_surv.intlogloss, mlr_measures_surv.logloss, mlr_measures_surv.rcll, mlr_measures_surv.schmid

Description

This calibration method fits the predicted linear predictor from a Cox PH model as the only predictor in a new Cox PH model with the test data as the response.

$h(t|x) = h_0(t)exp(\beta \times lp)$

where $lp$ is the predicted linear predictor on the test data.

The model is well calibrated if the estimated $\hat{\beta}$ coefficient (returned score) is equal to 1.

Note: Assumes fitted model is Cox PH (i.e. has an lp prediction type).

Dictionary

This Measure can be instantiated via the dictionary mlr_measures or with the associated sugar function msr():

MeasureSurvCalibrationBeta$new()
mlr_measures$get("surv.calib_beta")
msr("surv.calib_beta")

Parameters

Meta Information

• Type: "surv"

• Range: $(-\infty, \infty)$

• Minimize: FALSE

• Required prediction: lp

Parameter details

• se (logical(1))
  If TRUE then return standard error of the measure which is the standard error of the estimated coefficient $se_{\hat{\beta}}$ from the Cox PH model. If FALSE (default) then returns the estimated coefficient $\hat{\beta}$.

• method (character(1))
  Returns $\hat{\beta}$ if equal to ratio (default) and $|1-\hat{\beta}|$ if diff. With diff, the output score can be minimized and for example be used for tuning purposes. This parameter takes effect only if se is FALSE.

Super classes

mlr3::Measure -> mlr3proba::MeasureSurv -> MeasureSurvCalibrationBeta

Methods

Public methods

• MeasureSurvCalibrationBeta$new()

• MeasureSurvCalibrationBeta$clone()

Method new()

Creates a new instance of this R6 class.

Usage

MeasureSurvCalibrationBeta$new(method = "ratio")

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

MeasureSurvCalibrationBeta$clone(deep = FALSE)

Arguments

References

Van Houwelingen, C. H (2000). “Validation, calibration, revision and combination of prognostic survival models.” Statistics in Medicine, 19(24), 3401–3415. doi:10.1002/1097-0258(20001230)19:24<3401::AID-SIM554>3.0.CO;2-2.

See Also

Other survival measures: mlr_measures_surv.calib_alpha, mlr_measures_surv.chambless_auc, mlr_measures_surv.cindex, mlr_measures_surv.dcalib, mlr_measures_surv.graf, mlr_measures_surv.hung_auc, mlr_measures_surv.intlogloss, mlr_measures_surv.logloss, mlr_measures_surv.mae, mlr_measures_surv.mse, mlr_measures_surv.nagelk_r2, mlr_measures_surv.oquigley_r2, mlr_measures_surv.rcll, mlr_measures_surv.rmse, mlr_measures_surv.schmid, mlr_measures_surv.song_auc, mlr_measures_surv.song_tnr, mlr_measures_surv.song_tpr, mlr_measures_surv.uno_auc, mlr_measures_surv.uno_tnr, mlr_measures_surv.uno_tpr, mlr_measures_surv.xu_r2

Other calibration survival measures: mlr_measures_surv.calib_alpha, mlr_measures_surv.dcalib

Other lp survival measures: mlr_measures_surv.chambless_auc, mlr_measures_surv.hung_auc, mlr_measures_surv.nagelk_r2, mlr_measures_surv.oquigley_r2, mlr_measures_surv.song_auc, mlr_measures_surv.song_tnr, mlr_measures_surv.song_tpr, mlr_measures_surv.uno_auc, mlr_measures_surv.uno_tnr, mlr_measures_surv.uno_tpr, mlr_measures_surv.xu_r2

Description

Calls survAUC::AUC.cd().

Assumes Cox PH model specification.

Details

All measures implemented from survAUC should be used with care, we are aware of problems in implementation that sometimes cause fatal errors in R. In future updates some of these measures may be re-written and implemented directly in mlr3proba.

Dictionary

This Measure can be instantiated via the dictionary mlr_measures or with the associated sugar function msr():

MeasureSurvChamblessAUC$new()
mlr_measures$get("surv.chambless_auc")
msr("surv.chambless_auc")

Parameters

Meta Information

• Type: "surv"

• Range: $[0, 1]$

• Minimize: FALSE

• Required prediction: lp

Parameter details

• integrated (logical(1))
  If TRUE (default), returns the integrated score (eg across time points); otherwise, not integrated (eg at a single time point).

• times (numeric())
  If integrate == TRUE then a vector of time-points over which to integrate the score. If integrate == FALSE then a single time point at which to return the score.

Super classes

mlr3::Measure -> mlr3proba::MeasureSurv -> mlr3proba::MeasureSurvAUC -> MeasureSurvChamblessAUC

Methods

Public methods

• MeasureSurvChamblessAUC$new()

• MeasureSurvChamblessAUC$clone()

Method new()

Creates a new instance of this R6 class.

Usage

MeasureSurvChamblessAUC$new()

Method clone()

The objects of this class are cloneable with this method.

Usage

MeasureSurvChamblessAUC$clone(deep = FALSE)

Arguments

References

Chambless LE, Diao G (2006). “Estimation of time-dependent area under the ROC curve for long-term risk prediction.” Statistics in Medicine, 25(20), 3474–3486. doi:10.1002/sim.2299.

See Also

Other survival measures: mlr_measures_surv.calib_alpha, mlr_measures_surv.calib_beta, mlr_measures_surv.cindex, mlr_measures_surv.dcalib, mlr_measures_surv.graf, mlr_measures_surv.hung_auc, mlr_measures_surv.intlogloss, mlr_measures_surv.logloss, mlr_measures_surv.mae, mlr_measures_surv.mse, mlr_measures_surv.nagelk_r2, mlr_measures_surv.oquigley_r2, mlr_measures_surv.rcll, mlr_measures_surv.rmse, mlr_measures_surv.schmid, mlr_measures_surv.song_auc, mlr_measures_surv.song_tnr, mlr_measures_surv.song_tpr, mlr_measures_surv.uno_auc, mlr_measures_surv.uno_tnr, mlr_measures_surv.uno_tpr, mlr_measures_surv.xu_r2

Other AUC survival measures: mlr_measures_surv.hung_auc, mlr_measures_surv.song_auc, mlr_measures_surv.song_tnr, mlr_measures_surv.song_tpr, mlr_measures_surv.uno_auc, mlr_measures_surv.uno_tnr, mlr_measures_surv.uno_tpr

Other lp survival measures: mlr_measures_surv.calib_beta, mlr_measures_surv.hung_auc, mlr_measures_surv.nagelk_r2, mlr_measures_surv.oquigley_r2, mlr_measures_surv.song_auc, mlr_measures_surv.song_tnr, mlr_measures_surv.song_tpr, mlr_measures_surv.uno_auc, mlr_measures_surv.uno_tnr, mlr_measures_surv.uno_tpr, mlr_measures_surv.xu_r2

Description

Calculates weighted concordance statistics, which, depending on the chosen weighting method (weight_meth) and tied times parameter (tiex), are equivalent to several proposed methods. By default, no weighting is applied and this is equivalent to Harrell's C-index.

Details

For the Kaplan-Meier estimate of the training survival distribution ($S$), and the Kaplan-Meier estimate of the training censoring distribution ($G$), we have the following options for time-independent concordance statistics (C-indexes) given the weighted method:

weight_meth:

• "I" = No weighting. (Harrell)

• "GH" = Gonen and Heller's Concordance Index

• "G" = Weights concordance by $1/G$.

• "G2" = Weights concordance by $1/G^2$. (Uno et al.)

• "SG" = Weights concordance by $S/G$ (Shemper et al.)

• "S" = Weights concordance by $S$ (Peto and Peto)

The last three require training data. "GH" is only applicable to LearnerSurvCoxPH.

The implementation is slightly different from survival::concordance. Firstly this implementation is faster, and secondly the weights are computed on the training dataset whereas in survival::concordance the weights are computed on the same testing data.

Dictionary

This Measure can be instantiated via the dictionary mlr_measures or with the associated sugar function msr():

MeasureSurvCindex$new()
mlr_measures$get("surv.cindex")
msr("surv.cindex")

Parameters

Meta Information

• Type: "surv"

• Range: $[0, 1]$

• Minimize: FALSE

• Required prediction: crank

Parameter details

• eps (numeric(1))
  Very small number to substitute zero values in order to prevent errors in e.g. log(0) and/or division-by-zero calculations. Default value is 0.001.

• t_max (numeric(1))
  Cutoff time (i.e. time horizon) to evaluate concordance up to.

• p_max (numeric(1))
  The proportion of censoring to evaluate concordance up to in the given dataset. When t_max is specified, this parameter is ignored.

• weight_meth (character(1))
  Method for weighting concordance. Default "I" is Harrell's C. See details.

• tiex (numeric(1))
  Weighting applied to tied rankings, default is to give them half (0.5) weighting.

Super classes

mlr3::Measure -> mlr3proba::MeasureSurv -> MeasureSurvCindex

Methods

Public methods

• MeasureSurvCindex$new()

• MeasureSurvCindex$clone()

Method new()

This is an abstract class that should not be constructed directly.

Usage

MeasureSurvCindex$new()

Method clone()

The objects of this class are cloneable with this method.

Usage

MeasureSurvCindex$clone(deep = FALSE)

Arguments

References

Peto, Richard, Peto, Julian (1972). “Asymptotically efficient rank invariant test procedures.” Journal of the Royal Statistical Society: Series A (General), 135(2), 185–198.

Harrell, E F, Califf, M R, Pryor, B D, Lee, L K, Rosati, A R (1982). “Evaluating the yield of medical tests.” Jama, 247(18), 2543–2546.

Goenen M, Heller G (2005). “Concordance probability and discriminatory power in proportional hazards regression.” Biometrika, 92(4), 965–970. doi:10.1093/biomet/92.4.965.

Schemper, Michael, Wakounig, Samo, Heinze, Georg (2009). “The estimation of average hazard ratios by weighted Cox regression.” Statistics in Medicine, 28(19), 2473–2489. doi:10.1002/sim.3623.

Uno H, Cai T, Pencina MJ, D'Agostino RB, Wei LJ (2011). “On the C-statistics for evaluating overall adequacy of risk prediction procedures with censored survival data.” Statistics in Medicine, n/a–n/a. doi:10.1002/sim.4154.

See Also

Other survival measures: mlr_measures_surv.calib_alpha, mlr_measures_surv.calib_beta, mlr_measures_surv.chambless_auc, mlr_measures_surv.dcalib, mlr_measures_surv.graf, mlr_measures_surv.hung_auc, mlr_measures_surv.intlogloss, mlr_measures_surv.logloss, mlr_measures_surv.mae, mlr_measures_surv.mse, mlr_measures_surv.nagelk_r2, mlr_measures_surv.oquigley_r2, mlr_measures_surv.rcll, mlr_measures_surv.rmse, mlr_measures_surv.schmid, mlr_measures_surv.song_auc, mlr_measures_surv.song_tnr, mlr_measures_surv.song_tpr, mlr_measures_surv.uno_auc, mlr_measures_surv.uno_tnr, mlr_measures_surv.uno_tpr, mlr_measures_surv.xu_r2

Examples

library(mlr3)
task = tsk("rats")
learner = lrn("surv.coxph")
part = partition(task) # train/test split
learner$train(task, part$train)
p = learner$predict(task, part$test)

# Harrell's C-index
p$score(msr("surv.cindex")) # same as `p$score()`

# Uno's C-index
p$score(msr("surv.cindex", weight_meth = "G2"),
        task = task, train_set = part$train)

# Harrell's C-index evaluated up to a specific time horizon
p$score(msr("surv.cindex", t_max = 97))
# Harrell's C-index evaluated up to the time corresponding to 30% of censoring
p$score(msr("surv.cindex", p_max = 0.3))

Description

This calibration method is defined by calculating the following statistic:

$s = B/n \sum_i (P_i - n/B)^2$

where $B$ is number of 'buckets' (that equally divide $[0,1]$ into intervals), $n$ is the number of predictions, and $P_i$ is the observed proportion of observations in the $i$th interval. An observation is assigned to the $i$th bucket, if its predicted survival probability at the time of event falls within the corresponding interval. This statistic assumes that censoring time is independent of death time.

A model is well-calibrated if $s \sim Unif(B)$, tested with chisq.test ($p > 0.05$ if well-calibrated). Model $i$ is better calibrated than model $j$ if $s(i) < s(j)$, meaning that lower values of this measure are preferred.

Details

This measure can either return the test statistic or the p-value from the chisq.test. The former is useful for model comparison whereas the latter is useful for determining if a model is well-calibrated. If chisq = FALSE and s is the predicted value then you can manually compute the p.value with pchisq(s, B - 1, lower.tail = FALSE).

NOTE: This measure is still experimental both theoretically and in implementation. Results should therefore only be taken as an indicator of performance and not for conclusive judgements about model calibration.

Dictionary

This Measure can be instantiated via the dictionary mlr_measures or with the associated sugar function msr():

MeasureSurvDCalibration$new()
mlr_measures$get("surv.dcalib")
msr("surv.dcalib")

Parameters

Meta Information

• Type: "surv"

• Range: $[0, \infty)$

• Minimize: TRUE

• Required prediction: distr

Parameter details

• B (integer(1))
  Number of buckets to test for uniform predictions over. Default of 10 is recommended by Haider et al. (2020). Changing this parameter affects truncate.

• chisq (logical(1))
  If TRUE returns the p-value of the corresponding chisq.test instead of the measure. Default is FALSE and returns the statistic s. You can manually get the p-value by executing pchisq(s, B - 1, lower.tail = FALSE). The null hypothesis is that the model is D-calibrated.

• truncate (double(1))
  This parameter controls the upper bound of the output statistic, when chisq is FALSE. We use truncate = Inf by default but $10$ may be sufficient for most purposes, which corresponds to a p-value of 0.35 for the chisq.test using $B = 10$ buckets. Values $>10$ translate to even lower p-values and thus less calibrated models. If the number of buckets $B$ changes, you probably will want to change the truncate value as well to correspond to the same p-value significance. Note that truncation may severely limit automated tuning with this measure.

Super classes

mlr3::Measure -> mlr3proba::MeasureSurv -> MeasureSurvDCalibration

Methods

Public methods

• MeasureSurvDCalibration$new()

• MeasureSurvDCalibration$clone()

Method new()

Creates a new instance of this R6 class.

Usage

MeasureSurvDCalibration$new()

Method clone()

The objects of this class are cloneable with this method.

Usage

MeasureSurvDCalibration$clone(deep = FALSE)

Arguments

References

Haider, Humza, Hoehn, Bret, Davis, Sarah, Greiner, Russell (2020). “Effective Ways to Build and Evaluate Individual Survival Distributions.” Journal of Machine Learning Research, 21(85), 1–63. https://jmlr.org/papers/v21/18-772.html.

See Also

Other survival measures: mlr_measures_surv.calib_alpha, mlr_measures_surv.calib_beta, mlr_measures_surv.chambless_auc, mlr_measures_surv.cindex, mlr_measures_surv.graf, mlr_measures_surv.hung_auc, mlr_measures_surv.intlogloss, mlr_measures_surv.logloss, mlr_measures_surv.mae, mlr_measures_surv.mse, mlr_measures_surv.nagelk_r2, mlr_measures_surv.oquigley_r2, mlr_measures_surv.rcll, mlr_measures_surv.rmse, mlr_measures_surv.schmid, mlr_measures_surv.song_auc, mlr_measures_surv.song_tnr, mlr_measures_surv.song_tpr, mlr_measures_surv.uno_auc, mlr_measures_surv.uno_tnr, mlr_measures_surv.uno_tpr, mlr_measures_surv.xu_r2

Other calibration survival measures: mlr_measures_surv.calib_alpha, mlr_measures_surv.calib_beta

Other distr survival measures: mlr_measures_surv.calib_alpha, mlr_measures_surv.graf, mlr_measures_surv.intlogloss, mlr_measures_surv.logloss, mlr_measures_surv.rcll, mlr_measures_surv.schmid

Description

Calculates the Integrated Survival Brier Score (ISBS), Integrated Graf Score or squared survival loss.

Details

For an individual who dies at time $t$, with predicted Survival function, $S$, the Graf Score at time $t^*$ is given by