Compute held-out concentration-index validation gain for a CI forest

Applies each member tree in a fitted ci_forest() to validation data, computes ci_tree_validation_gain() for each internal tree partition, and returns the average gain across trees. This is a forest-native partition diagnostic: it measures the average concentration-index impurity reduction from the forest's stored trees, not from a surrogate tree and not from the averaged prediction surface.

Usage

ci_forest_validation_gain(
  fit,
  new_data,
  rank_name = fit$rank_name,
  outcome_name = fit$outcome_name,
  weights = NULL,
  type = fit$type,
  root_impurity = NULL
)

Arguments

fit

A fitted ci_forest object.

new_data

Validation data.

rank_name

Name of the socioeconomic ranking column.

outcome_name

Name of the outcome column.

weights

Optional non-negative validation weights.

type

One of "CI", "CIg", "CIc", or "L" selecting the inequality index used for validation scoring. "L" uses observed socioeconomic levels in the first response column rather than fractional ranks.

root_impurity

Optional pre-computed root impurity for the validation sample under the selected concentration-index criterion. If NULL, the root impurity is computed from new_data.

Value

A single numeric validation gain.

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)
)
forest <- ci_forest(
  cbind(rank, outcome) ~ income,
  data = toy_data,
  rank_name = "rank",
  outcome_name = "outcome",
  ntree = 3,
  control = ci_tree_control(minsplit = 1, minbucket = 1, maxdepth = 1)
)
ci_forest_validation_gain(forest, toy_data, "rank", "outcome")
#> [1] -0.05972222