Survival Bayesian Additive Regression Trees Learner

Fits a Bayesian Additive Regression Trees (BART) learner to right-censored survival data. Calls BART::mc.surv.bart() from BART.

Details

Two types of prediction are returned for this learner:

1. distr: a 3d survival array with observations as 1st dimension, time points as 2nd and the posterior draws as 3rd dimension.

2. crank: the expected mortality using mlr3proba::.surv_return. The parameter which.curve decides which posterior draw (3rd dimension) will be used for the calculation of the expected mortality. Note that the median posterior is by default used for the calculation of survival measures that require a distr prediction, see more info on PredictionSurv.

Initial parameter values

• mc.cores is initialized to 1 to avoid threading conflicts with future.

Custom mlr3 parameters

• quiet allows to suppress messages generated by the wrapped C++ code. Is initialized to TRUE.

• importance allows to choose the type of importance. Default is count, see documentation of method $importance() for more details.

• which.curve allows to choose which posterior draw will be used for the calculation of the crank prediction. If between (0,1) it is taken as the quantile of the curves otherwise if greater than 1 it is taken as the curve index, can also be 'mean'. By default the median posterior is used, i.e. which.curve is 0.5.

Dictionary

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

mlr_learners$get("surv.bart")
lrn("surv.bart")

Meta Information

• Task type: “surv”

• Predict Types: “crank”, “distr”

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

• Required Packages: mlr3, mlr3proba, BART

Parameters

Id	Type	Default	Levels	Range
K	numeric	NULL		\([1, \infty)\)
events	untyped	NULL		-
ztimes	untyped	NULL		-
zdelta	untyped	NULL		-
sparse	logical	FALSE	TRUE, FALSE	-
theta	numeric	0		\((-\infty, \infty)\)
omega	numeric	1		\((-\infty, \infty)\)
a	numeric	0.5		\([0.5, 1]\)
b	numeric	1		\((-\infty, \infty)\)
augment	logical	FALSE	TRUE, FALSE	-
rho	numeric	NULL		\((-\infty, \infty)\)
usequants	logical	FALSE	TRUE, FALSE	-
rm.const	logical	TRUE	TRUE, FALSE	-
type	character	pbart	pbart, lbart	-
ntype	integer	-		\([1, 3]\)
k	numeric	2		\([0, \infty)\)
power	numeric	2		\([0, \infty)\)
base	numeric	0.95		\([0, 1]\)
offset	numeric	NULL		\((-\infty, \infty)\)
ntree	integer	50		\([1, \infty)\)
numcut	integer	100		\([1, \infty)\)
ndpost	integer	1000		\([1, \infty)\)
nskip	integer	250		\([0, \infty)\)
keepevery	integer	10		\([1, \infty)\)
printevery	integer	100		\([1, \infty)\)
seed	integer	99		\((-\infty, \infty)\)
mc.cores	integer	2		\([1, \infty)\)
nice	integer	19		\([0, 19]\)
openmp	logical	TRUE	TRUE, FALSE	-
quiet	logical	TRUE	TRUE, FALSE	-
importance	character	count	count, prob	-
which.curve	numeric	-		\([0, \infty)\)

References

Sparapani, Rodney, Spanbauer, Charles, McCulloch, Robert (2021). “Nonparametric machine learning and efficient computation with bayesian additive regression trees: the BART R package.” Journal of Statistical Software, 97, 1--66.

Chipman, A H, George, I E, McCulloch, E R (2010). “BART: Bayesian additive regression trees.” The Annals of Applied Statistics, 4(1), 266--298.

See also

• Dictionary of Learners: mlr3::mlr_learners.

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

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

• mlr3learners for a selection of recommended learners.

• mlr3cluster for unsupervised clustering learners.

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

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

Author

bblodfon

Super classes

mlr3::Learner -> mlr3proba::LearnerSurv -> LearnerSurvLearnerSurvBART

Methods

Public methods

• LearnerSurvLearnerSurvBART$new()

• LearnerSurvLearnerSurvBART$importance()

• LearnerSurvLearnerSurvBART$clone()

Inherited methods

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

---

Method new()

Creates a new instance of this R6 class.

Usage

LearnerSurvLearnerSurvBART$new()

---

Method importance()

Two types of importance scores are supported based on the value of the parameter importance:

1. prob: The mean selection probability of each feature in the trees, extracted from the slot varprob.mean. If sparse = FALSE (default), this is a fixed constant. Recommended to use this option when sparse = TRUE.

2. count: The mean observed count of each feature in the trees (average number of times the feature was used in a tree decision rule across all posterior draws), extracted from the slot varcount.mean. This is the default importance scores.

In both cases, higher values signify more important variables.

Usage

LearnerSurvLearnerSurvBART$importance()

Returns

Named numeric().

---

Method clone()

The objects of this class are cloneable with this method.

Usage

LearnerSurvLearnerSurvBART$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

learner = mlr3::lrn("surv.bart")
print(learner)
#> <LearnerSurvLearnerSurvBART:surv.bart>: Bayesian Additive Regression Trees
#> * Model: -
#> * Parameters: mc.cores=1, quiet=TRUE, importance=count, which.curve=0.5
#> * Packages: mlr3, mlr3proba, BART
#> * Predict Types:  [crank], distr
#> * Feature Types: logical, integer, numeric
#> * Properties: importance, missings

# available parameters:
learner$param_set$ids()
#>  [1] "K"           "events"      "ztimes"      "zdelta"      "sparse"     
#>  [6] "theta"       "omega"       "a"           "b"           "augment"    
#> [11] "rho"         "usequants"   "rm.const"    "type"        "ntype"      
#> [16] "k"           "power"       "base"        "offset"      "ntree"      
#> [21] "numcut"      "ndpost"      "nskip"       "keepevery"   "printevery" 
#> [26] "seed"        "mc.cores"    "nice"        "openmp"      "quiet"      
#> [31] "importance"  "which.curve"