Find the best factor split by concentration-index gain

Evaluate binary splits of a factor predictor and return the split with the largest weighted concentration-index gain. Exact partition search is used for small factors when enabled by ctrl$factor_split; otherwise levels are ordered by weighted mean outcome and cumulative splits are evaluated.

Usage

best_factor_split(
  x_full,
  keep,
  y_full,
  wt_full,
  varid,
  ctrl,
  ci_fun,
  return = c("split", "candidate")
)

Arguments

x_full

A factor predictor containing all original levels.

keep

A logical vector selecting the observations currently available for splitting.

y_full

A two-column numeric matrix whose first column is the socioeconomic ranking variable and whose second column is the health outcome.

wt_full

A numeric vector of case weights for all observations.

varid

Integer identifier of the splitting variable, passed to partykit::partysplit().

ctrl

A list-like control object containing minbucket, minprob, and optional factor split controls.

ci_fun

A concentration-index scoring function, typically created by ci_factory().

return

Either "split" to return only a partykit::partysplit() object, or "candidate" to also return the gain and left-child routing needed by the greedy tree builder.

Value

A partysplit object describing the best admissible split of the observed factor levels, or NULL if fewer than two levels are present after subsetting or if all candidate splits violate the control constraints.

Details

Only levels present among the kept observations are scored, but the returned split keeps the full level mapping so it can be used with partykit::partysplit().