Tune greedy concentration-index forest controls by cross-validation

tune_cf_ci() is kept for existing code. New code should use tune_ci_forest().

Fits ci_forest() across candidate forest controls and concentration-index criteria. Concentration-index validation gain is computed directly from the forest's internal trees by averaging held-out validation gain across member tree partitions. Prediction-oriented metrics are computed from the averaged forest predictions in the same tuning run. When refit = TRUE, the selected forest is also summarized by a surrogate greedy ci_tree() for interpretation.

As in tune_ci_tree(), relative validation metrics are root-relative model scores, while min_relative_gain is a local parent-node relative split threshold.

Usage

tune_cf_ci(...)

tune_ci_forest(
  formula,
  data,
  rank_name,
  outcome_name,
  weights = NULL,
  type = c("CI", "CIg", "CIc", "L"),
  control_grid = NULL,
  ntree = 500L,
  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,
  surrogate_control = NULL,
  prediction_name = "forest_risk",
  refit = TRUE,
  verbose = FALSE,
  control = NULL,
  perturb = list(replace = FALSE, fraction = 0.632),
  parallel_over = c("none", "tuning", "forest"),
  future.seed = TRUE,
  na.action = stats::na.omit,
  ...
)

Arguments

...: Additional arguments passed to ci_tree().
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.
ntree: Number of trees used when control_grid does not contain an ntree column.
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.
surrogate_control: Optional ci_tree_control() for the surrogate tree. By default, the selected forest controls are reused with mtry = NULL so the surrogate searches all split variables.
prediction_name: Name of the forest-prediction column added to the surrogate data.
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.
perturb: Resampling controls passed to ci_forest().
parallel_over: Parallelization strategy. "none" runs tuning and forest fitting serially, "tuning" evaluates grid/resample tasks with future.apply::future_lapply(), and "forest" keeps tuning tasks serial while growing trees inside each ci_forest() call with future.apply::future_lapply(). Parallel modes require the suggested package future.apply. The future backend is controlled by the user outside tune_ci_forest().
future.seed: Passed to future.apply::future_lapply() when parallel_over is "tuning" or "forest".
na.action: A function for handling missing values.

Value

A ci_forest_tuning object.

Examples

if (requireNamespace("future", quietly = TRUE) &&
    requireNamespace("future.apply", quietly = TRUE)) {
  old_plan <- future::plan()
  on.exit(future::plan(old_plan), add = TRUE)
  future::plan(future::sequential)

  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,
    ntree = 3
  )
  tuned <- tune_ci_forest(
    cbind(rank, outcome) ~ income,
    data = toy_data,
    rank_name = "rank",
    outcome_name = "outcome",
    control_grid = grid,
    v = 2,
    parallel_over = "tuning",
    refit = FALSE
  )
}