Tune greedy concentration-index tree controls by cross-validation

Fits ci_tree() across a grid of greedy tree controls and concentration index criteria. If type contains multiple values, each of "CI", "CIg", "CIc", and/or "L" is treated as a candidate objective and selected by the validation metric.

The default metric is validation_gain, the held-out reduction in concentration-index impurity after validation observations are assigned to terminal nodes. "relative_validation_gain" and "percent_validation_root_recovered" divide that gain by the absolute validation root impurity for within-type interpretation. Prediction-oriented metrics ("brier", "log_loss", and "roc_auc") are also available for numeric risk or binary event outcomes.

These cross-validation relative metrics are global, root-relative model scores. They are distinct from min_relative_gain in the control grid, which is a local parent-node relative threshold used only to decide whether a candidate split should be kept during tree growth.

Usage

tune_ci_tree(
  formula,
  data,
  rank_name,
  outcome_name,
  weights = NULL,
  type = c("CI", "CIg", "CIc", "L"),
  control_grid = NULL,
  v = 5L,
  strata = NULL,
  fold_id = NULL,
  resamples = NULL,
  seed = NULL,
  metric = c("validation_gain", "relative_validation_gain",
    "percent_validation_root_recovered", "brier", "log_loss", "roc_auc"),
  metrics = NULL,
  refit = TRUE,
  verbose = FALSE,
  control = NULL,
  na.action = stats::na.omit,
  ...
)

tune_ctree_ci(...)

Arguments

formula: A model formula, typically with a two-column response such as cbind(rank, outcome) ~ x1 + x2.
data: A data frame containing the variables in formula.
rank_name: Name of the socioeconomic rank variable.
outcome_name: Name of the outcome variable.
weights: Optional non-negative case weights.
type: One or more of "CI", "CIg", "CIc", or "L" selecting candidate inequality objectives. "L" uses observed socioeconomic levels in the first response column rather than fractional ranks.
control_grid: A data frame of candidate controls. Defaults to ci_tree_control_grid(). If it contains a type column, that column is used instead of expanding over type.
v: Number of cross-validation folds.
strata: Optional stratum vector, or a single column name in data, used for stratified fold creation.
fold_id: Optional precomputed integer fold ids. When supplied, v, strata, and seed are ignored for fold creation.
resamples: Optional rsample rset object. When supplied, it is used instead of creating folds from v, strata, or fold_id.
seed: Optional random seed for fold creation.
metric: Selection metric when a single metric is requested. validation_gain, relative_validation_gain, percent_validation_root_recovered, and roc_auc are maximized; brier and log_loss are minimized.
metrics: Optional character vector of one or more metrics to compute during tuning. When supplied, the first metric is used for final model selection.
refit: Should the best setting be refitted on the full data?
verbose: Should fold progress be printed?
control: Optional control_ci_tune() object controlling saved predictions, saved fits, extraction hooks, and parallel settings.
na.action: A function for handling missing values.
...: Additional arguments passed to ci_tree().

Value

A ci_tree_tuning object.

Examples

toy_data <- data.frame(
  rank = c(10, 20, 30, 40, 50, 60, 70, 80),
  outcome = c(1, 0, 1, 0, 1, 1, 0, 1),
  income = c(2, 4, 6, 8, 10, 12, 14, 16)
)
grid <- ci_tree_control_grid(
  minsplit = 1,
  minbucket = 1,
  minprob = 0,
  maxdepth = 1:2
)
tuned <- tune_ci_tree(
  cbind(rank, outcome) ~ income,
  data = toy_data,
  rank_name = "rank",
  outcome_name = "outcome",
  type = c("CI", "CIg"),
  control_grid = grid,
  v = 2,
  seed = 1
)
tuned$best_type
#> [1] "CI"