Survival Task

This task specializes mlr3::Task and mlr3::TaskSupervised for possibly-censored survival problems. The target is comprised of survival times and an event indicator. Predefined tasks are stored in mlr3::mlr_tasks.

The task_type is set to "surv".

Super classes

mlr3::Task -> mlr3::TaskSupervised -> TaskSurv

Active bindings

censtype: character(1)
Returns the type of censoring, one of "right", "left", "counting", "interval", or "mstate".

Methods

Inherited methods

Method `new()`

Creates a new instance of this R6 class.

Usage

TaskSurv$new(
  id,
  backend,
  time = "time",
  event = "event",
  time2,
  type = c("right", "left", "interval", "counting", "interval2", "mstate"),
  label = NA_character_
)

Arguments

id: (character(1))
Identifier for the new instance.
backend: (DataBackend)
Either a DataBackend, or any object which is convertible to a DataBackend with as_data_backend(). E.g., a data.frame() will be converted to a DataBackendDataTable.
time: (character(1))
Name of the column for event time if data is right censored, otherwise starting time if interval censored.
event: (character(1))
Name of the column giving the event indicator. If data is right censored then "0"/FALSE means alive (no event), "1"/TRUE means dead (event). If type is "interval" then "0" means right censored, "1" means dead (event), "2" means left censored, and "3" means interval censored. If type is "interval2" then event is ignored.
time2: (character(1))
Name of the column for ending time for interval censored data, otherwise ignored.
type: (character(1))
Name of the column giving the type of censoring. Default is 'right' censoring.
label: (character(1))
Label for the new instance.

Method `truth()`

True response for specified row_ids. Format depends on the task type. Defaults to all rows with role "use".

Usage

TaskSurv$truth(rows = NULL)

Arguments

rows: integer()
Row indices.

Returns

numeric().

Method `formula()`

Creates a formula for survival models with survival::Surv on the LHS.

Usage

TaskSurv$formula(rhs = NULL, reverse = FALSE)

Arguments

rhs: If NULL RHS is ., otherwise gives RHS of formula.
reverse: If TRUE then formula calculated with 1 - status.

Returns

numeric().

Method `times()`

Returns the (unsorted) outcome times.

Usage

TaskSurv$times(rows = NULL)

Arguments

rows: integer()
Row indices.

Returns

numeric()

Method `status()`

Returns the event indicator (aka censoring/survival indicator). If censtype is "right" or "left" then 1 is event and 0 is censored. If censtype is "mstate" then 0 is censored and all other values are different events. If censtype is "interval" then 0 is right-censored, 1 is event, 2 is left-censored, 3 is interval-censored. See survival::Surv.

Usage

TaskSurv$status(rows = NULL)

Arguments

rows: integer()
Row indices.

Returns

integer()

Method `unique_times()`

Returns the sorted unique outcome times for 'right', 'left', and 'mcstate'.

Usage

TaskSurv$unique_times(rows = NULL)

Arguments

rows: integer()
Row indices.

Returns

numeric()

Method `unique_event_times()`

Returns the sorted unique event (or failure) outcome times.

Usage

TaskSurv$unique_event_times(rows = NULL)

Arguments

rows: integer()
Row indices.

Returns

numeric()

Method `risk_set()`

Returns the row_ids of the observations 'at risk' (not dead or censored) at time.

Usage

TaskSurv$risk_set(time = NULL)

Arguments

time: (numeric(1))
Time to return risk set for, if NULL returns all row_ids.

Returns

integer()

Method `kaplan()`

Calls survival::survfit() to calculate the Kaplan-Meier estimator.

Usage

TaskSurv$kaplan(strata = NULL, rows = NULL, reverse = FALSE, ...)

Arguments

strata: (character())
Stratification variables to use.
rows: (integer())
Subset of row indices.
reverse: (logical())
If TRUE calculates Kaplan-Meier of censoring distribution (1-status). Default FALSE.
...: (any)
Additional arguments passed down to survival::survfit.formula().

Returns

survival::survfit.object.

Method `reverse()`

Returns the same task with the status variable reversed, i.e., 1 - status. Only designed for left and right censoring.

Usage

TaskSurv$reverse()

Returns

TaskSurv.

Method `clone()`

The objects of this class are cloneable with this method.

Usage

TaskSurv$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

library(mlr3)
lung = survival::lung
lung$status = (lung$status == 2L)
task = TaskSurv$new("lung",
  backend = lung, time = "time",
  event = "status")

# meta data
task$target_names
#> [1] "time"   "status"
task$feature_names
#> [1] "age"       "inst"      "meal.cal"  "pat.karno" "ph.ecog"   "ph.karno" 
#> [7] "sex"       "wt.loss"  
task$formula()
#> Surv(time, status, type = "right") ~ .
#> <environment: namespace:survival>

# survival data
task$truth()
#>   [1]  306   455  1010+  210   883  1022+  310   361   218   166   170   654 
#>  [13]  728    71   567   144   613   707    61    88   301    81   624   371 
#>  [25]  394   520   574   118   390    12   473    26   533   107    53   122 
#>  [37]  814   965+   93   731   460   153   433   145   583    95   303   519 
#>  [49]  643   765   735   189    53   246   689    65     5   132   687   345 
#>  [61]  444   223   175    60   163    65   208   821+  428   230   840+  305 
#>  [73]   11   132   226   426   705   363    11   176   791    95   196+  167 
#>  [85]  806+  284   641   147   740+  163   655   239    88   245   588+   30 
#>  [97]  179   310   477   166   559+  450   364   107   177   156   529+   11 
#> [109]  429   351    15   181   283   201   524    13   212   524   288   363 
#> [121]  442   199   550    54   558   207    92    60   551+  543+  293   202 
#> [133]  353   511+  267   511+  371   387   457   337   201   404+  222    62 
#> [145]  458+  356+  353   163    31   340   229   444+  315+  182   156   329 
#> [157]  364+  291   179   376+  384+  268   292+  142   413+  266+  194   320 
#> [169]  181   285   301+  348   197   382+  303+  296+  180   186   145   269+
#> [181]  300+  284+  350   272+  292+  332+  285   259+  110   286   270    81 
#> [193]  131   225+  269   225+  243+  279+  276+  135    79    59   240+  202+
#> [205]  235+  105   224+  239   237+  173+  252+  221+  185+   92+   13   222+
#> [217]  192+  183   211+  175+  197+  203+  116   188+  191+  105+  174+  177+
task$times()
#>   [1]  306  455 1010  210  883 1022  310  361  218  166  170  654  728   71  567
#>  [16]  144  613  707   61   88  301   81  624  371  394  520  574  118  390   12
#>  [31]  473   26  533  107   53  122  814  965   93  731  460  153  433  145  583
#>  [46]   95  303  519  643  765  735  189   53  246  689   65    5  132  687  345
#>  [61]  444  223  175   60  163   65  208  821  428  230  840  305   11  132  226
#>  [76]  426  705  363   11  176  791   95  196  167  806  284  641  147  740  163
#>  [91]  655  239   88  245  588   30  179  310  477  166  559  450  364  107  177
#> [106]  156  529   11  429  351   15  181  283  201  524   13  212  524  288  363
#> [121]  442  199  550   54  558  207   92   60  551  543  293  202  353  511  267
#> [136]  511  371  387  457  337  201  404  222   62  458  356  353  163   31  340
#> [151]  229  444  315  182  156  329  364  291  179  376  384  268  292  142  413
#> [166]  266  194  320  181  285  301  348  197  382  303  296  180  186  145  269
#> [181]  300  284  350  272  292  332  285  259  110  286  270   81  131  225  269
#> [196]  225  243  279  276  135   79   59  240  202  235  105  224  239  237  173
#> [211]  252  221  185   92   13  222  192  183  211  175  197  203  116  188  191
#> [226]  105  174  177
task$status()
#>   [1] 1 1 0 1 1 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
#>  [38] 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 1 1 0 1 1 1
#>  [75] 1 1 1 1 1 1 1 1 0 1 0 1 1 1 0 1 1 1 1 1 0 1 1 1 1 1 0 1 1 1 1 1 0 1 1 1 1
#> [112] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 1 1 1 0 1 0 1 1 1 1 1 0 1 1 0 0 1 1
#> [149] 1 1 1 0 0 1 1 1 0 1 1 0 0 1 0 1 0 0 1 1 1 1 0 1 1 0 0 0 1 1 1 0 0 0 1 0 0
#> [186] 0 1 0 1 1 1 1 1 0 1 0 0 0 0 1 1 1 0 0 0 1 0 1 0 0 0 0 0 0 1 0 0 1 0 0 0 0
#> [223] 1 0 0 0 0 0
task$unique_times()
#>   [1]    5   11   12   13   15   26   30   31   53   54   59   60   61   62   65
#>  [16]   71   79   81   88   92   93   95  105  107  110  116  118  122  131  132
#>  [31]  135  142  144  145  147  153  156  163  166  167  170  173  174  175  176
#>  [46]  177  179  180  181  182  183  185  186  188  189  191  192  194  196  197
#>  [61]  199  201  202  203  207  208  210  211  212  218  221  222  223  224  225
#>  [76]  226  229  230  235  237  239  240  243  245  246  252  259  266  267  268
#>  [91]  269  270  272  276  279  283  284  285  286  288  291  292  293  296  300
#> [106]  301  303  305  306  310  315  320  329  332  337  340  345  348  350  351
#> [121]  353  356  361  363  364  371  376  382  384  387  390  394  404  413  426
#> [136]  428  429  433  442  444  450  455  457  458  460  473  477  511  519  520
#> [151]  524  529  533  543  550  551  558  559  567  574  583  588  613  624  641
#> [166]  643  654  655  687  689  705  707  728  731  735  740  765  791  806  814
#> [181]  821  840  883  965 1010 1022
task$unique_event_times()
#>   [1]   5  11  12  13  15  26  30  31  53  54  59  60  61  62  65  71  79  81
#>  [19]  88  92  93  95 105 107 110 116 118 122 131 132 135 142 144 145 147 153
#>  [37] 156 163 166 167 170 175 176 177 179 180 181 182 183 186 189 194 197 199
#>  [55] 201 202 207 208 210 212 218 222 223 226 229 230 239 245 246 267 268 269
#>  [73] 270 283 284 285 286 288 291 293 301 303 305 306 310 320 329 337 340 345
#>  [91] 348 350 351 353 361 363 364 371 387 390 394 426 428 429 433 442 444 450
#> [109] 455 457 460 473 477 519 520 524 533 550 558 567 574 583 613 624 641 643
#> [127] 654 655 687 689 705 707 728 731 735 765 791 814 883
task$risk_set(time = 700)
#>  [1]  3  5  6 13 18 37 38 40 50 51 68 71 77 81 85 89
task$kaplan("sex")
#> Call: survfit(formula = f, data = data)
#> 
#>         n events median 0.95LCL 0.95UCL
#> sex=1 138    112    270     212     310
#> sex=2  90     53    426     348     550

See also

Super classes

Active bindings

Methods

Public methods

Method new()

Usage

Arguments

Method truth()

Usage

Arguments

Returns

Method formula()

Usage

Arguments

Returns

Method times()

Usage

Arguments

Returns

Method status()

Usage

Arguments

Returns

Method unique_times()

Usage

Arguments

Returns

Method unique_event_times()

Usage

Arguments

Returns

Method risk_set()

Usage

Arguments

Returns

Method kaplan()

Usage

Arguments

Returns

Method reverse()

Usage

Returns

Method clone()

Usage

Arguments

Examples

Method `new()`

Method `truth()`

Method `formula()`

Method `times()`

Method `status()`

Method `unique_times()`

Method `unique_event_times()`

Method `risk_set()`

Method `kaplan()`

Method `reverse()`

Method `clone()`