Package 'mlr3cmprsk'

Description

Provides a unified interface for right-censored competing risks tasks in 'mlr3'.

Package Options

The following options control optional predicted CIF diagnostics and default to FALSE. Set them with options() to enable diagnostics package-wide.

• mlr3cmprsk.warn_cif_sum: Warn with class Mlr3WarningCIFSumExceedsOne when predictions contain cause-specific CIFs whose sum exceeds 1 (allowing numerical tolerance). Predictions are retained without changing their probabilities. Enable by using options(mlr3cmprsk.warn_cif_sum = TRUE).

• mlr3cmprsk.warn_cif_extrapolation: Warn with class Mlr3WarningCIFExtrapolation when a measure evaluates times after a scored cause's final CIF anchor. CIFs are constantly extrapolated after the final anchor. One warning lists all affected causes per scoring call. Enable by using options(mlr3cmprsk.warn_cif_extrapolation = TRUE).

Author(s)

Maintainer: John Zobolas [email protected] (ORCID)

Authors:

• John Zobolas [email protected] (ORCID)

• Andreas Bender [email protected] (ORCID)

Other contributors:

• Andrzej Galecki [email protected] (ORCID) [contributor]

See Also

Useful links:

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

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

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

Description

Convert object to a PredictionCompRisks. An existing PredictionCompRisks is returned unchanged. See Details for requirements on list and data.frame inputs.

Use mlr3::as_prediction() to convert the internal PredictionDataCompRisks data to a PredictionCompRisks object.

Usage

as_prediction_cmprsk(x, ...)

## S3 method for class 'PredictionCompRisks'
as_prediction_cmprsk(x, ...)

## S3 method for class 'list'
as_prediction_cmprsk(x, ...)

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

## S3 method for class 'PredictionDataCompRisks'
as_prediction(x, check = FALSE, ...)

Arguments

Details

If x is a named list, it must contain row_ids, truth, and cif. The weights and extra elements are optional. These elements are passed to the PredictionCompRisks constructor and validated there (using check = TRUE by default). The cif element must be a nonempty list of matrices, with one matrix for every task competing cause. This requirement also applies to the internal prediction data of PredictionDataCompRisks class.

If x is a data.frame/data.table input, the following requirements must be met:

• Columns row_ids, time, event, and a list-column CIF must be present.

• An optional column weights may hold measurement weights.

• All other columns are stored as extra data. Column names must be unique.

• The per-observation CIF object must be a named list of numeric vectors (one per cause), with names exactly "1", "2", ..., "K", in that order (where K is the number of competing risks).

• Cause names must be identical across observations and in the same order.

• CIF vectors corresponding to the same cause must have the same length and the same time names (the names of the vectors) across all observations.

• Values for the event column must be 0 (censoring) or one of the consecutive cause codes 1, 2, ..., K.

Value

PredictionCompRisks.

Examples

library(mlr3)
task = tsk("pbc")
learner = lrn("cmprsk.aalen")
learner$train(task)
p = learner$predict(task)

# from an existing PredictionCompRisks object (no change)
as_prediction_cmprsk(p)

# Convert a named list to a PredictionCompRisks object
# The list must contain `row_ids`, `truth`, and `cif` elements
p_list = list(
  row_ids = p$row_ids,
  truth = p$truth,
  cif = p$cif
)
as_prediction_cmprsk(p_list)

# Convert a data.frame to a PredictionCompRisks object
# The data.frame must contain the required columns: row_ids, time, event, and CIF
tab = as.data.frame(as.data.table(p))
as_prediction_cmprsk(tab)

# Convert internal prediction data using as_prediction()
p$data
as_prediction(p$data)

Description

Convert object to a competing risks task (TaskCompRisks).

Usage

as_task_cmprsk(x, ...)

## S3 method for class 'TaskCompRisks'
as_task_cmprsk(x, clone = FALSE, ...)

## S3 method for class 'data.frame'
as_task_cmprsk(
  x,
  time = "time",
  event = "event",
  id = deparse1(substitute(x)),
  ...
)

## S3 method for class 'DataBackend'
as_task_cmprsk(
  x,
  time = "time",
  event = "event",
  id = deparse1(substitute(x)),
  ...
)

Arguments

Description

Checks the structure, cause names, and probabilities of a list of cumulative incidence function (CIF) matrices. This is the format used by PredictionCompRisks to store predictions for competing events.

Usage

assert_cif_list(x, n_rows = NULL, causes = NULL)

Arguments

Details

Each matrix is checked with survdistr::assert_prob() using type = "cif":

• At least one row and one column are required, and missing values are not allowed.

• Column names must represent unique, increasing, non-negative numeric time points.

• Probabilities must be between 0 and 1 and non-decreasing over time within each row.

• If time 0 is included, its probabilities must all be 0.

Matrices are checked individually and may use different time grids.

Value

Returns NULL invisibly if all checks pass, otherwise raises an error.

Examples

cif = list(
  "1" = matrix(c(0, 0, 0.1, 0.2, 0.3, 0.4), nrow = 2L),
  "2" = matrix(c(0, 0, 0.2, 0.1, 0.4, 0.3), nrow = 2L)
)
cif = lapply(cif, function(x) {
  colnames(x) = c("0", "1", "2")
  x
})

assert_cif_list(cif)
assert_cif_list(cif, n_rows = 2L, causes = c("1", "2"))

Description

This Learner specializes Learner for competing risks problems:

• task_type is set to "cmprsk"

• Creates Predictions of class PredictionCompRisks.

• The only currently available option for predict_types is "cif", which represents the predicted cumulative incidence function for each observation in the test set.

Details

By design, competing risks learners fit all available causes in task$cmp_events and return a CIF for every cause and observation in PredictionCompRisks. For example, LearnerCompRisksFineGray fits a separate subdistribution hazards model for each available cause and returns the CIFs from all of these models.

Super class

mlr3::Learner -> LearnerCompRisks

Methods

Public methods

• LearnerCompRisks$new()

• LearnerCompRisks$clone()

LearnerCompRisks$new()

Creates a new instance of this R6 class.

Usage

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

Arguments

LearnerCompRisks$clone()

The objects of this class are cloneable with this method.

Usage

LearnerCompRisks$clone(deep = FALSE)

Arguments

Examples

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

# get a specific learner from mlr_learners:
mlr_learners$get("cmprsk.aalen")
lrn("cmprsk.aalen")

Description

This measure specializes Measure for competing risk problems.

• task_type is set to "cmprsk".

• predict_type is set to "cif".

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

Super class

mlr3::Measure -> MeasureCompRisks

Methods

Public methods

• MeasureCompRisks$new()

• MeasureCompRisks$clone()

MeasureCompRisks$new()

Creates a new instance of this R6 class.

Usage

MeasureCompRisks$new(
  id,
  param_set = ps(),
  range,
  minimize = NA,
  average = "macro",
  aggregator = NULL,
  properties = character(),
  predict_type = "cif",
  predict_sets = "test",
  task_properties = character(),
  packages = character(),
  label = NA_character_,
  man = NA_character_
)

Arguments

MeasureCompRisks$clone()

The objects of this class are cloneable with this method.

Usage

MeasureCompRisks$clone(deep = FALSE)

Arguments

See Also

Default competing risks measure: cmprsk.ibs

Description

This learner estimates the Cumulative Incidence Function (CIF) for competing risks using the empirical Aalen-Johansen (AJ) estimator.

Transition probabilities to each competing event are computed from the training data via the survival::survfit.formula() function. Predictions are made at all unique event times (across all causes) observed in the training set.

Dictionary

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

mlr_learners$get("cmprsk.aalen")
lrn("cmprsk.aalen")

Meta Information

• Task type: “cmprsk”

• Predict Types: “cif”

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

• Required Packages: mlr3, mlr3cmprsk, survival

Parameters

Empty ParamSet

Super classes

mlr3::Learner -> LearnerCompRisks -> LearnerCompRisksAalenJohansen

Active bindings

Methods

Public methods

• LearnerCompRisksAalenJohansen$new()

• LearnerCompRisksAalenJohansen$importance()

• LearnerCompRisksAalenJohansen$selected_features()

• LearnerCompRisksAalenJohansen$clone()

LearnerCompRisksAalenJohansen$new()

Creates a new instance of this R6 class.

Usage

LearnerCompRisksAalenJohansen$new()

LearnerCompRisksAalenJohansen$importance()

All features have a score of 0 for this learner. This method exists solely for compatibility with the mlr3 ecosystem, as this learner is used as a fallback for other survival learners that require an importance() method.

Usage

LearnerCompRisksAalenJohansen$importance()

Returns

Named numeric().

LearnerCompRisksAalenJohansen$selected_features()

Selected features are always the empty set for this learner. This method is implemented only for compatibility with the mlr3 API, as this learner does not perform feature selection.

Usage

LearnerCompRisksAalenJohansen$selected_features()

Returns

character(0).

LearnerCompRisksAalenJohansen$clone()

The objects of this class are cloneable with this method.

Usage

LearnerCompRisksAalenJohansen$clone(deep = FALSE)

Arguments

References

Aalen, O O, Johansen, Soren (1978). “An empirical transition matrix for non-homogeneous Markov chains based on censored observations.” Scandinavian journal of statistics, 141–150.

See Also

• Chapter in the mlr3book: https://mlr3book.mlr-org.com/chapters/chapter2/data_and_basic_modeling.html#sec-learners

• Dictionary of Learners: mlr3::mlr_learners

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

• mlr3pipelines to combine learners with pre- and postprocessing steps

• mlr3tuning for tuning of hyperparameters

Other competing risk learners: mlr_learners_cmprsk.fg

Examples

# Define a task
task = tsk("pbc")
task$select(c("age", "chol", "albumin", "ast", "bili", "protime"))

# Stratify by event status
task$set_col_roles(cols = "status", add_to = "stratum")
task

# Create training and test sets
set.seed(42L)
part = partition(task)

# Define the learner
learner = lrn("cmprsk.aalen")

# Train on the training set
learner$train(task, row_ids = part$train)
learner$native_model

# Predict CIFs for the test set
predictions = learner$predict(task, row_ids = part$test)
predictions

# Score predictions
predictions$score()

Description

Fine-Gray subdistribution hazards model for competing risks using cmprsk::crr().

Details

A separate Fine-Gray subdistribution hazards model is fitted for every cause in task$cmp_events. This follows the LearnerCompRisks design: predictions contain CIFs for all available causes.

The fitted model is an S3 object of class "fine_gray" that stores a cause-specific list of crr class models.

At prediction time, each cause-specific model is evaluated with cmprsk::predict.crr() and the resulting CIF matrices are aligned to a common time grid across causes using constant CIF interpolation. The time grid is the unique event times (across all causes) observed in the training set.

Independently fitted cause-specific models can produce CIFs whose sum exceeds 1. The corresponding warning is disabled package-wide by default, as it can recur on every prediction call. Set options(mlr3cmprsk.warn_cif_sum = TRUE) to enable it. See also Package Options section in mlr3cmprsk-package.

Time-interaction terms (via cov2) are not implemented.

Dictionary

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

mlr_learners$get("cmprsk.fg")
lrn("cmprsk.fg")

Meta Information

• Task type: “cmprsk”

• Predict Types: “cif”

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

• Required Packages: mlr3, mlr3cmprsk, cmprsk

Parameters

Super classes

mlr3::Learner -> LearnerCompRisks -> LearnerCompRisksFineGray

Methods

Public methods

• LearnerCompRisksFineGray$new()

• LearnerCompRisksFineGray$clone()

LearnerCompRisksFineGray$new()

Creates a new instance of this R6 class.

Usage

LearnerCompRisksFineGray$new()

LearnerCompRisksFineGray$clone()

The objects of this class are cloneable with this method.

Usage

LearnerCompRisksFineGray$clone(deep = FALSE)

Arguments

References

Fine, P J, Gray, J R (1999). “A Proportional Hazards Model for the Subdistribution of a Competing Risk.” Journal of the American Statistical Association, 94(446), 496–509. doi:10.1080/01621459.1999.10474144.

See Also

• Chapter in the mlr3book: https://mlr3book.mlr-org.com/chapters/chapter2/data_and_basic_modeling.html#sec-learners

• Dictionary of Learners: mlr3::mlr_learners

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

• mlr3pipelines to combine learners with pre- and postprocessing steps

• mlr3tuning for tuning of hyperparameters

Other competing risk learners: mlr_learners_cmprsk.aalen

Examples

# Define a task
task = tsk("pbc")
task$select(c("age", "chol", "albumin", "ast", "bili", "protime"))

# Stratify by event status
task$set_col_roles(cols = "status", add_to = "stratum")
task

# Create training and test sets
set.seed(42L)
part = partition(task)

# Define the learner
learner = lrn("cmprsk.fg")

# Train on the training set
learner$train(task, row_ids = part$train)
learner$native_model

# Predict CIFs for the test set
predictions = learner$predict(task, row_ids = part$test)
predictions

# Score predictions
predictions$score()

Description

Calculates the time-dependent ROC-AUC at a specific time point, as described in Blanche et al. (2013), Equation 4. Controls include subjects who survive beyond the time horizon and those who experience a competing event before the horizon.

Details

By default, this measure returns a cause-independent AUC(t) score, calculated as a weighted average of the cause-specific AUCs. The weights correspond to the relative event frequencies of each cause, following Equation 7 in Heyard et al. (2020). User-supplied weights are also supported through cause_weights. See the Cause weights section for weighting rules.

Alternatively, users can obtain the cause-specific AUC(t) for any individual cause by specifying the cause parameter.

Calls riskRegression::Score() with:

• metric = "auc"

• cens.method = "ipcw"

• cens.model = "km"

Notes on the riskRegression implementation:

1. IPCW weights are estimated using the test data only, so smaller test sets may lead to less stable estimates.

2. Scoring at a time beyond the maximum observed test-set time produces an input error.

3. AUC(t) is undefined if no events of the requested cause are observed at or before time, or if no controls are available at that time. In these cases, riskRegression returns NaN for the cause-specific AUC.

Dictionary

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

mlr_measures$get("cmprsk.auc")
msr("cmprsk.auc")

Meta Information

• Task type: “cmprsk”

• Range: $[0, 1]$

• Minimize: FALSE

• Average: macro

• Required Prediction: “cif”

• Required Packages: mlr3, mlr3cmprsk, riskRegression

Parameters

Cause weights

Cause weights are used only for cause = "mean". The cause_weights parameter is ignored when scoring a specific cause.

With cause_weights = NULL, weights are the relative frequencies of observed non-censored events from the test set. Causes without observed events receive zero weight, are listed in a warning and are skipped when calculating the mean score. If no events from any cause are observed, weights are undefined, and the measure warns and returns NA_real_.

Alternatively, the user can supply custom weights via cause_weights. Weights must be finite, non-negative, sum to 1, and contain one entry per predicted cause. Entries must match the order of the predicted CIFs cause names. If any user-supplied weight happens to be zero, it is skipped silently.

In general, non-finite scores from positive-weight causes propagate to the mean, causing the measure to return NaN and a warning identifies the causes with non-finite scores.

Parameter details

• cause (numeric(1)|"mean")
  Integer number indicating which cause to use. Default value is "mean" which returns an event-frequency weighted mean of the cause-specific AUCs.

• cause_weights (numeric()|NULL)
  Optional custom weights for cause = "mean". See the Cause weights section for weighting rules.

• time (numeric(1))
  Single time point at which to return the score. If NULL, the median observed time point from the test set is used.

Super classes

mlr3::Measure -> MeasureCompRisks -> MeasureCompRisksAUC

Methods

Public methods

• MeasureCompRisksAUC$new()

• MeasureCompRisksAUC$clone()

MeasureCompRisksAUC$new()

Creates a new instance of this R6 class.

Usage

MeasureCompRisksAUC$new()

MeasureCompRisksAUC$clone()

The objects of this class are cloneable with this method.

Usage

MeasureCompRisksAUC$clone(deep = FALSE)

Arguments

References

Blanche, Paul, Dartigues, Francois J, Jacqmin-Gadda, Helene (2013). “Estimating and comparing time-dependent areas under receiver operating characteristic curves for censored event times with competing risks.” Statistics in Medicine, 32(30), 5381–5397. ISSN 1097-0258, doi:10.1002/SIM.5958, https://onlinelibrary.wiley.com/doi/10.1002/sim.5958.

Spitoni, Claudia, Lammens, Valerie, Putter, Hein (2018). “Prediction errors for state occupation and transition probabilities in multi-state models.” Biometrical Journal, 60(1), 34–48. ISSN 0323-3847, doi:10.1002/BIMJ.201600191, https://doi.org/10.1002/BIMJ.201600191.

Heyard, Rachel, Timsit, Jean-Francois, Held, Leonhard (2020). “Validation of discrete time-to-event prediction models in the presence of competing risks.” Biometrical Journal, 62(3), 643–657. https://doi.org/10.1002/BIMJ.201800293.

Examples

# Define a task
task = tsk("pbc")
task$select(c("age", "chol", "albumin", "ast", "bili", "protime"))

# Stratify by event status
task$set_col_roles(cols = "status", add_to = "stratum")
task

# Create training and test sets
set.seed(42L)
part = partition(task)

# Define the learner
learner = lrn("cmprsk.fg")

# Train on the training set
learner$train(task, row_ids = part$train)
learner$native_model

# Predict CIFs for the test set
predictions = learner$predict(task, row_ids = part$test)
predictions

# AUC at the median observed test-set time,
# weighted by event frequencies
predictions$score(msr("cmprsk.auc"))

# AUC at 100 months, weighted by event frequencies
predictions$score(msr("cmprsk.auc", time = 100))

# AUC at 100 months, with equal weights for both causes
predictions$score(msr("cmprsk.auc", time = 100, cause_weights = c(0.5, 0.5)))

# AUC at 100 months, with custom weights for transplant and death
predictions$score(msr("cmprsk.auc", time = 100, cause_weights = c(0.2, 0.8)))

# AUC at 100 months, for transplant only
predictions$score(msr("cmprsk.auc", time = 100, cause = 1))

# AUC at 100 months, for death only
predictions$score(msr("cmprsk.auc", time = 100, cause = 2))

Description

Calculates the competing risks prediction error (Brier score, BS(t)) at a specific time point, using IPCW as described in Schoop et al. (2011).

Details

By default, this measure returns a cause-independent BS(t) (or all-cause) score, calculated as a weighted average of the cause-specific Brier scores. The weights correspond to the relative event frequencies of each cause, following Equation (8) in Spitoni et al. (2018). User-supplied weights are also supported through cause_weights. See the Cause weights section for weighting rules.

Alternatively, users can obtain the cause-specific Brier score for any individual cause by specifying the cause parameter.

Calls riskRegression::Score() with:

• metric = "brier"

• cens.method = "ipcw"

• cens.model = "km"

Notes on the riskRegression implementation:

1. IPCW weights are estimated using the test data only, so smaller test sets may lead to less stable estimates.

2. Scoring at a time beyond the maximum observed test-set time produces an input error.

Dictionary

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

mlr_measures$get("cmprsk.brier")
msr("cmprsk.brier")

Meta Information

• Task type: “cmprsk”

• Range: $[0, \infty)$

• Minimize: TRUE

• Average: macro

• Required Prediction: “cif”

• Required Packages: mlr3, mlr3cmprsk, riskRegression

Parameters

Cause weights

Cause weights are used only for cause = "mean". The cause_weights parameter is ignored when scoring a specific cause.

With cause_weights = NULL, weights are the relative frequencies of observed non-censored events from the test set. Causes without observed events receive zero weight, are listed in a warning and are skipped when calculating the mean score. If no events from any cause are observed, weights are undefined, and the measure warns and returns NA_real_.

Alternatively, the user can supply custom weights via cause_weights. Weights must be finite, non-negative, sum to 1, and contain one entry per predicted cause. Entries must match the order of the predicted CIFs cause names. If any user-supplied weight happens to be zero, it is skipped silently.

In general, non-finite scores from positive-weight causes propagate to the mean, causing the measure to return NaN and a warning identifies the causes with non-finite scores.

Parameter details

• cause (numeric(1)|"mean")
  Integer number indicating which cause to use. Default value is "mean" which returns an event-frequency weighted mean of the cause-specific Brier scores.

• cause_weights (numeric()|NULL)
  Optional custom weights for cause = "mean". See the Cause weights section for weighting rules.

• time (numeric(1))
  Single time point at which to return the score. If NULL, the median observed time point from the test set is used.

Super classes

mlr3::Measure -> MeasureCompRisks -> MeasureCompRisksBrierScore

Methods

Public methods

• MeasureCompRisksBrierScore$new()

• MeasureCompRisksBrierScore$clone()

MeasureCompRisksBrierScore$new()

Creates a new instance of this R6 class.

Usage

MeasureCompRisksBrierScore$new()

MeasureCompRisksBrierScore$clone()

The objects of this class are cloneable with this method.

Usage

MeasureCompRisksBrierScore$clone(deep = FALSE)

Arguments

References

Schoop, Roland, Beyersmann, Jan, Schumacher, Martin, Binder, Harald (2011). “Quantifying the predictive accuracy of time-to-event models in the presence of competing risks.” Biometrical Journal, 53(1), 88–112. https://doi.org/10.1002/BIMJ.201000073.

Spitoni, Claudia, Lammens, Valerie, Putter, Hein (2018). “Prediction errors for state occupation and transition probabilities in multi-state models.” Biometrical Journal, 60(1), 34–48. ISSN 0323-3847, doi:10.1002/BIMJ.201600191, https://doi.org/10.1002/BIMJ.201600191.

Examples

# Define a task
task = tsk("pbc")
task$select(c("age", "chol", "albumin", "ast", "bili", "protime"))

# Stratify by event status
task$set_col_roles(cols = "status", add_to = "stratum")
task

# Create training and test sets
set.seed(42L)
part = partition(task)

# Define the learner
learner = lrn("cmprsk.fg")

# Train on the training set
learner$train(task, row_ids = part$train)
learner$native_model

# Predict CIFs for the test set
predictions = learner$predict(task, row_ids = part$test)
predictions

# Brier score at the median observed test-set time,
# weighted by event frequencies
predictions$score(msr("cmprsk.brier"))

# Brier score at 100 months, weighted by event frequencies
predictions$score(msr("cmprsk.brier", time = 100))

# Brier score at 100 months, with equal weights for both causes
predictions$score(msr("cmprsk.brier", time = 100, cause_weights = c(0.5, 0.5)))

# Brier score at 100 months, with custom weights for transplant and death
predictions$score(msr("cmprsk.brier", time = 100, cause_weights = c(0.2, 0.8)))

# Brier score at 100 months, for transplant only
predictions$score(msr("cmprsk.brier", time = 100, cause = 1))

# Brier score at 100 months, for death only
predictions$score(msr("cmprsk.brier", time = 100, cause = 2))

Description

Calculates the integrated competing risks prediction error (integrated Brier score, IBS) using IPCW as described in Schoop et al. (2011).

Details

By default, this measure returns a cause-independent IBS (or all-cause) score, calculated as a weighted average of the cause-specific integrated Brier scores. The weights correspond to the relative event frequencies of each cause, following Equation (8) in Spitoni et al. (2018). User-supplied weights are also supported through cause_weights. See the Cause weights section for weighting rules.

Alternatively, users can obtain the cause-specific IBS for any individual cause by specifying the cause parameter.

Calls riskRegression::Score() with:

• metric = "brier"

• summary = "ibs"

• cens.method = "ipcw"

• cens.model = "km"

Notes on the riskRegression implementation:

1. IPCW weights are estimated using the test data only, so smaller test sets may lead to less stable estimates.

2. Evaluation is limited to the maximum observed test-set follow-up time. See the Integration grid section for how this restriction is applied.

Dictionary

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

mlr_measures$get("cmprsk.ibs")
msr("cmprsk.ibs")

Meta Information

• Task type: “cmprsk”

• Range: $[0, \infty)$

• Minimize: TRUE

• Average: macro

• Required Prediction: “cif”

• Required Packages: mlr3, mlr3cmprsk, riskRegression

Parameters

Parameter details

• cause (numeric(1)|"mean")
  Integer number indicating which cause to use. Default value is "mean" which returns an event-frequency weighted mean of the cause-specific integrated Brier scores.

• cause_weights (numeric()|NULL)
  Optional custom weights for cause = "mean". See the Cause weights section for weighting rules.

• times (numeric()|NULL)
  Explicit integration grid, supplied as a sorted vector of at least two distinct, finite, non-negative time points. Default is NULL, which uses an automatically generated grid. t_max and t_quantile must both be NULL when supplying explicit times.

• ntimes (integer(1))
  Number of points in an automatically constructed integration grid, including time 0 and the upper integration horizon. Must be at least 2; default is 100. Ignored when supplying explicit times.

• t_max (numeric(1)|NULL)
  Finite, non-negative upper integration horizon; default is NULL. Mutually exclusive with t_quantile.

• t_quantile (numeric(1)|NULL)
  Quantile probability of observed test-set follow-up times used to determine the upper integration horizon. Must be finite and between 0 and 1, inclusive. Default is NULL, which uses the 90th percentile when t_max is also NULL. Mutually exclusive with t_max.

Cause weights

Cause weights are used only for cause = "mean". The cause_weights parameter is ignored when scoring a specific cause.

With cause_weights = NULL, weights are the relative frequencies of observed non-censored events from the test set. Causes without observed events receive zero weight, are listed in a warning and are skipped when calculating the mean score. If no events from any cause are observed, weights are undefined, and the measure warns and returns NA_real_.

Alternatively, the user can supply custom weights via cause_weights. Weights must be finite, non-negative, sum to 1, and contain one entry per predicted cause. Entries must match the order of the predicted CIFs cause names. If any user-supplied weight happens to be zero, it is skipped silently.

In general, non-finite scores from positive-weight causes propagate to the mean, causing the measure to return NaN and a warning identifies the causes with non-finite scores.

Integration grid

The integration grid contains the time points at which Brier scores are evaluated for numerical integration. Its largest time point is the upper integration horizon. All causes use the same grid, with their predicted CIFs constantly interpolated to these times.

If the user explicitly provides times, the supplied grid is used directly. Points beyond the maximum test-set follow-up are removed with a warning due to the limitations of riskRegression::Score(). At least two distinct evaluation times must remain.

When times = NULL, the upper integration horizon is determined first. By default, it is the 90th percentile of observed test-set follow-up times, including both events and censored observations. Set t_quantile to change the quantile probability (e.g., 0.8 for the 80th percentile), or supply t_max to specify the time horizon directly. If t_max exceeds the maximum test-set follow-up, it is reduced to that maximum before constructing the grid, and a warning reports the effective horizon.

The automatic grid is then generated and contains exactly ntimes equally spaced points from time 0 to the horizon, including both endpoints. Thus, the default grid consists of 100 points from 0 to the 90th percentile of test-set follow-up times. Note that the generated grid is completely independent of the time grids of the predicted CIFs.

The default 90th percentile is chosen to limit evaluation at extreme follow-up times, where IPCW weights may be large or CIF extrapolation beyond the last predicted time point may be needed.

Super classes

mlr3::Measure -> MeasureCompRisks -> MeasureCompRisksIntegratedBrierScore

Methods

Public methods

• MeasureCompRisksIntegratedBrierScore$new()

• MeasureCompRisksIntegratedBrierScore$clone()

MeasureCompRisksIntegratedBrierScore$new()

Creates a new instance of this R6 class.

Usage

MeasureCompRisksIntegratedBrierScore$new()

MeasureCompRisksIntegratedBrierScore$clone()

The objects of this class are cloneable with this method.

Usage

MeasureCompRisksIntegratedBrierScore$clone(deep = FALSE)

Arguments

References

Schoop, Roland, Beyersmann, Jan, Schumacher, Martin, Binder, Harald (2011). “Quantifying the predictive accuracy of time-to-event models in the presence of competing risks.” Biometrical Journal, 53(1), 88–112. https://doi.org/10.1002/BIMJ.201000073.

Spitoni, Claudia, Lammens, Valerie, Putter, Hein (2018). “Prediction errors for state occupation and transition probabilities in multi-state models.” Biometrical Journal, 60(1), 34–48. ISSN 0323-3847, doi:10.1002/BIMJ.201600191, https://doi.org/10.1002/BIMJ.201600191.

Examples

# Define a task
task = tsk("pbc")
task$select(c("age", "chol", "albumin", "ast", "bili", "protime"))

# Stratify by event status
task$set_col_roles(cols = "status", add_to = "stratum")
task

# Create training and test sets
set.seed(42L)
part = partition(task)

# Define the learner
learner = lrn("cmprsk.fg")

# Train on the training set
learner$train(task, row_ids = part$train)
learner$native_model

# Predict CIFs for the test set
predictions = learner$predict(task, row_ids = part$test)
predictions

# IBS over 100 equally spaced points from 0 to the 90th test-set follow-up percentile,
# weighted by event frequencies
predictions$score(msr("cmprsk.ibs"))

# IBS with an upper integration horizon of 100 months
predictions$score(msr("cmprsk.ibs", t_max = 100))

# IBS up to the 85th percentile of test-set follow-up times
predictions$score(msr("cmprsk.ibs", t_quantile = 0.85))

# IBS over 20 equally spaced points up to the default 90th percentile
predictions$score(msr("cmprsk.ibs", ntimes = 20L))

# Define the integration grid in months
times = seq(0, 100, by = 5)

# IBS from 0 to 100 months on a 5-month grid, weighted by event frequencies
predictions$score(msr("cmprsk.ibs", times = times))

# IBS from 0 to 100 months on a 5-month grid, with equal weights for both causes
predictions$score(msr("cmprsk.ibs", times = times, cause_weights = c(0.5, 0.5)))

# IBS from 0 to 100 months on a 5-month grid, with custom weights for transplant and death
predictions$score(msr("cmprsk.ibs", times = times, cause_weights = c(0.2, 0.8)))

# IBS from 0 to 100 months on a 5-month grid, for transplant only
predictions$score(msr("cmprsk.ibs", times = times, cause = 1))

# IBS from 0 to 100 months on a 5-month grid, for death only
predictions$score(msr("cmprsk.ibs", times = times, cause = 2))

Description

A competing risks task for the pbc data set.

Format

R6::R6Class inheriting from TaskCompRisks.

Dictionary

This Task can be instantiated via the dictionary mlr_tasks or with the associated sugar function tsk():

mlr_tasks$get("pbc")
tsk("pbc")

Meta Information

• Task type: “cmprsk”

• Dimensions: 276x19

• Properties: -

• Has Missings: FALSE

• Target: “time”, “status”

• Features: “age”, “albumin”, “alk.phos”, “ascites”, “ast”, “bili”, “chol”, “copper”, “edema”, “hepato”, “platelet”, “protime”, “sex”, “spiders”, “stage”, “trig”, “trt”

Pre-processing

• Removed column id.

• Kept only complete cases (no missing values).

• Column age has been converted to integer.

• Columns trt, stage, hepato, edema and ascites have been converted to factors.

• Column trt has levels Dpenicillmain and placebo instead of 1 and 2.

• Column status has 0 for censored, 1 for transplant and 2 for death.

• Column time as been converted from days to months.

See Also

• Chapter in the mlr3book: https://mlr3book.mlr-org.com/chapters/chapter2/data_and_basic_modeling.html

• Dictionary of Tasks: mlr3::mlr_tasks

• as.data.table(mlr_tasks) for a table of available Tasks in the running session

Other Task: TaskCompRisks

Description

This object stores the predictions returned by a learner of class LearnerCompRisks.

The task_type is set to "cmprsk".

Causes use consecutive codes 1, 2, ..., K, matching the task used for prediction. By design, predictions contain one CIF matrix for every cause in task$cmp_events, including causes that are not observed among the predicted observations. Filtering prediction rows retains all cause levels and CIFs, even for unobserved causes. Combining predictions requires the same cause set.

Accessing all-cause survival or cause-specific hazard functions or similar quantities from a LearnerCompRisks object is not possible at the moment.

Super class

mlr3::Prediction -> PredictionCompRisks

Active bindings

Methods

Public methods

• PredictionCompRisks$new()

• PredictionCompRisks$clone()

PredictionCompRisks$new()

Creates a new instance of this R6 class.

Usage

PredictionCompRisks$new(
  task = NULL,
  row_ids = task$row_ids,
  truth = task$truth(),
  cif,
  weights = NULL,
  extra = NULL,
  check = TRUE
)

Arguments

Details

The cif input is a list of CIF matrices. With check = TRUE, nonempty predictions are validated using assert_cif_list(). This checks the list structure and cause names, the time points used for prediction, and validates each CIF matrix, including probabilities in [0, 1] and non-decreasing probabilities over time.

With options(mlr3cmprsk.warn_cif_sum = TRUE), joint coherence is checked separately by aligning the CIF matrices on a common time grid and summing their probabilities across causes for each observation and time point. A sum greater than 1, allowing a numerical tolerance of sqrt(.Machine$double.eps), triggers a warning of class Mlr3WarningCIFSumExceedsOne. This diagnostic is disabled by default; see the Package Options section in mlr3cmprsk-package. The prediction is retained without modifying its probabilities. Such sums can occur with independently fitted cause-specific models, such as the Fine-Gray model.

PredictionCompRisks$clone()

The objects of this class are cloneable with this method.

Usage

PredictionCompRisks$clone(deep = FALSE)

Arguments

Examples

library(mlr3)
task = tsk("pbc")
learner = lrn("cmprsk.aalen")
part = partition(task)
p = learner$train(task, part$train)$predict(task, part$test)
p

# CIF list: 1 matrix (obs x times) per competing event
names(p$cif) # competing events
# CIF matrix for competing event 1 (first 5 test observations and 20 time points)
p$cif[["1"]][1:5, 1:20]
# CIF matrix for competing event 2 (first 5 test observations and 20 time points)
p$cif[["2"]][1:5, 1:20]

# data.table conversion
tab = as.data.table(p)
tab$CIF[[1]] # for first test observation, list of CIF vectors

Description

This task extends mlr3::Task and mlr3::TaskSupervised for competing risks survival analysis. The target consists of a survival time and an event indicator. Event codes must be non-negative integers in $(0, 1, 2, ..., K)$. $0$ denotes censoring, and positive integers denote distinct event causes. Each row represents one observation.

Predefined tasks are stored in mlr3::mlr_tasks.

The task_type is set to "cmprsk".

Details

The following design choices apply to this task:

• Only right-censoring is currently supported.

• Tasks must contain at least two event causes, i.e., $K \geq 2$, encoded as consecutive integers $1, 2, ..., K$.

It is advised to use stratified resampling to reduce the risk of creating training splits with fewer than two causes, which may cause issues during model training (and later prediction). Task filtering specifically issues a warning when the number of competing events is reduced but remains >= 2, and an error if fewer than two causes remain.

Super classes

mlr3::Task -> mlr3::TaskSupervised -> TaskCompRisks

Active bindings

Methods

Public methods

• TaskCompRisks$new()

• TaskCompRisks$truth()

• TaskCompRisks$formula()

• TaskCompRisks$times()

• TaskCompRisks$event()

• TaskCompRisks$unique_times()

• TaskCompRisks$unique_event_times()

• TaskCompRisks$aalen_johansen()

• TaskCompRisks$cens_prop()

• TaskCompRisks$filter()

• TaskCompRisks$clone()

TaskCompRisks$new()

Creates a new instance of this R6 class.

Usage

TaskCompRisks$new(
  id,
  backend,
  time = "time",
  event = "event",
  label = NA_character_
)

Arguments

Details

Only right-censoring competing risk tasks are currently supported.

TaskCompRisks$truth()

True response for specified row_ids. This is the multi-state format using Surv with the event target column as a factor. Defaults to all rows with role "use".

Usage

TaskCompRisks$truth(rows = NULL)

Arguments

Returns

survival::Surv().

TaskCompRisks$formula()

Creates a formula for competing risk models with survival::Surv() on the LHS (left hand side).

Usage

TaskCompRisks$formula(rhs = NULL)

Arguments

Returns

stats::formula().

TaskCompRisks$times()

Returns the (unsorted) outcome times.

Usage

TaskCompRisks$times(rows = NULL)

Arguments

Returns

numeric()

TaskCompRisks$event()

Returns the event indicators. $0$ denotes censoring, and positive integers denote distinct event causes.

Usage

TaskCompRisks$event(rows = NULL)

Arguments

Returns

integer()

TaskCompRisks$unique_times()

Returns the sorted unique outcome times.

Usage

TaskCompRisks$unique_times(rows = NULL)

Arguments

Returns

numeric()

TaskCompRisks$unique_event_times()

Returns the sorted unique event outcome times (by any cause).

Usage

TaskCompRisks$unique_event_times(rows = NULL)

Arguments

Returns

numeric()

TaskCompRisks$aalen_johansen()

Calls survival::survfit() to calculate the Aalen–Johansen estimator.

Usage

TaskCompRisks$aalen_johansen(strata = NULL, rows = NULL, ...)

Arguments

Returns

survival::survfit.object.

TaskCompRisks$cens_prop()

Returns the proportion of censored observations for this competing risks task.

Usage

TaskCompRisks$cens_prop(rows = NULL)

Arguments

Returns

numeric()

TaskCompRisks$filter()

Subsets the task, keeping only the rows specified via the row ids rows. This operation mutates the task in-place. A warning is thrown if the filtering results in fewer competing events than the original task. An error is thrown if fewer than two competing events remain after filtering.

Usage

TaskCompRisks$filter(rows = NULL)

Arguments

Returns

Returns the object itself, but modified by reference.

TaskCompRisks$clone()

The objects of this class are cloneable with this method.

Usage

TaskCompRisks$clone(deep = FALSE)

Arguments

See Also

Other Task: mlr_tasks_pbc

Examples

library(mlr3)
task = tsk("pbc")

# Time and event target columns
task$target_names
# Feature names
task$feature_names
# Censoring type
task$cens_type

# survival data
task$formula(c("age", "sex")) # formula with survival::Surv() on LHS
task$truth() # survival::Surv() object
task$times() # (unsorted) times
task$event() # event indicators (0 = censored, >0 = different causes)
task$unique_times() # sorted unique times
task$unique_event_times() # sorted unique event times (from any cause)
task$cens_prop() # proportion of censored observations

# Aalen-Johansen estimator
task$aalen_johansen(strata = "sex")

# Causes
task$cmp_events