Skip to contents

Setup BART Hyperparameters

Source: R/070_Hyperparameters.R
setup_BART.Rd

Setup hyperparameters for Bayesian Additive Regression Trees training.

Usage

setup_BART(
  num_trees = 200L,
  alpha = 0.95,
  beta = 2,
  min_samples_leaf = 5L,
  max_depth = 10L,
  num_features_subsample = NULL,
  variance_forest_num_trees = 0L,
  num_gfr = 5L,
  num_burnin = 0L,
  num_mcmc = 100L,
  num_chains = 1L,
  keep_every = 1L,
  cutpoint_grid_size = 100L,
  standardize = TRUE,
  link = "probit",
  seed = NULL,
  ifw = FALSE
)

Arguments

num_trees

(Tunable) Integer [1, Inf): Number of trees in the mean forest.

alpha

(Tunable) Numeric (0, 1): Base of the tree split prior alpha * (1 + depth)^-beta.

beta

(Tunable) Numeric [0, Inf): Depth penalty exponent of the tree split prior alpha * (1 + depth)^-beta.

min_samples_leaf

(Tunable) Integer [1, Inf): Minimum number of training cases in a leaf.

max_depth

(Tunable) Optional Integer [1, Inf): Maximum depth of any tree. NULL imposes no limit.

num_features_subsample

(Tunable) Optional Integer [1, Inf): Number of features subsampled when growing each tree. NULL uses every feature.

variance_forest_num_trees

(Tunable) Integer [0, Inf): Number of trees in the conditional variance forest. 0 fits a homoskedastic model, any larger value a heteroskedastic one.

num_gfr

Integer [0, Inf): Number of grow-from-root warm-start iterations.

num_burnin

Integer [0, Inf): Number of burn-in MCMC iterations.

num_mcmc

Integer [1, Inf): Number of retained MCMC iterations per chain.

num_chains

Integer [1, Inf): Number of independent MCMC chains. Cannot exceed num_gfr unless num_gfr is 0.

keep_every

Integer [1, Inf): Thinning interval: retain one MCMC sample in every keep_every.

cutpoint_grid_size

Integer [1, Inf): Maximum number of candidate cutpoints considered by the grow-from-root algorithm.

standardize

Logical: If TRUE, center and scale the outcome before sampling.

Character {"probit", "cloglog"}: Link function of the binary outcome model. Classification only.

seed

Optional Integer: Random seed for the sampler. NULL leaves the sampler seeded by the system.

ifw

(Tunable) Logical: If TRUE, use Inverse Frequency Weighting in classification.

Value

BARTHyperparameters object.

Details

Both outcome types are fit with stochtree::bart, which samples a sum-of-trees model by MCMC, optionally warm-started by the grow-from-root algorithm. Regression uses a continuous outcome model, binary classification a discrete one with the link named by link. Multiclass classification is not supported.

Factors are expanded by the backend, so no encoding is needed beforehand. Case weights scale the residual variance and are honored under the default link = "probit", but stochtree rejects them under "cloglog", so that combination makes training abort rather than silently fit an unweighted model.

Because the fit is a posterior rather than a point estimate, se() returns the standard deviation of the retained draws, and get_varimp() reports two measures rather than one:

  • importance: the variable inclusion proportion, the share of splitting rules that use the feature, averaged across draws.

  • inclusion_sd: its standard deviation across draws, separating a feature the sampler uses consistently from one whose importance rests on a few draws.

plot_varimp(mod, measure = "inclusion_sd") plots the second; the first is the default.

Inclusion proportions only discriminate when trees compete for splits. At the default num_trees each tree is a weak learner and uninformative features still get used, so the proportions flatten towards 1/n_features; refit with a small ensemble (num_trees = 10L to 20L) when the goal is variable selection rather than prediction.

Author

EDG

Examples

bart_hyperparams <- setup_BART(num_trees = 50L, num_mcmc = 200L)
bart_hyperparams
#> <BARTHyperparameters>
#>         hyperparameters: 
#>                                          num_trees: <int> 50
#>                                              alpha: <nmr> 0.95
#>                                               beta: <nmr> 2.00
#>                                   min_samples_leaf: <int> 5
#>                                          max_depth: <int> 10
#>                             num_features_subsample: <NUL> NULL
#>                          variance_forest_num_trees: <int> 0
#>                                            num_gfr: <int> 5
#>                                         num_burnin: <int> 0
#>                                           num_mcmc: <int> 200
#>                                         num_chains: <int> 1
#>                                         keep_every: <int> 1
#>                                 cutpoint_grid_size: <int> 100
#>                                        standardize: <lgc> TRUE
#>                                               link: <chr> probit
#>                                               seed: <NUL> NULL
#>                                                ifw: <lgc> FALSE
#> tunable_hyperparameters: <chr> num_trees, alpha, beta, min_samples_leaf, max_depth, num_features_subsample, variance_forest_num_trees, ifw
#>   fixed_hyperparameters: <chr> num_gfr, num_burnin, num_mcmc, num_chains, keep_every, cutpoint_grid_size, standardize, link, seed
#>                   tuned: <int> -1
#>               resampled: <int> 0
#>               n_workers: <int> 1
#> 
#>   No search values defined for tunable hyperparameters.