CI split search with Rcpp

library(ineqTrees)

This development file documents the Rcpp-backed split-search fast path. It is kept separate from dev/ci_split_search.Rmd so the original R implementation remains available as the reference implementation.

Package files owned by this development note:

• R/ci_split_search_cpp.R
• src/ci_split_search_cpp.cpp
• R/RcppExports.R
• src/RcppExports.cpp
• tests/testthat/test-ci_split_search_cpp.R

The exported R-facing functions mirror the existing split-search helpers and add the _cpp suffix:

• best_numeric_split_cpp()
• best_factor_split_cpp()
• best_split_for_one_variable_cpp()
• best_global_ci_split_cpp()

The global helper also accepts vars, an optional integer vector of predictor ids to search. When vars is omitted, all columns in x are searched.

The roxygen source for the generated wrapper should document this argument as:

#' @param vars Optional integer variable ids to search. Defaults to all columns
#'   of `x`.

The current production tree and forest builders still call the R split-search helpers. The _cpp helpers are a parallel fast path for testing and later integration.

best_global_ci_split_cpp(
  x = predictors,
  y = y,
  wt = wt,
  ctrl = ci_tree_control(),
  type = "CI"
)

Design notes

The C++ engine computes the same concentration-index gain as the R path:

1. Compute the parent CI once.
2. Search all admissible candidate splits.
3. Compute child-specific weighted fractional ranks inside each candidate child.
4. Score child nodes with the direct population-style weighted covariance, without a child-specific finite-sample correction.
5. Return the best gain, child membership, parent impurity, and parent-node relative gain for min_relative_gain thresholding.

The C++ functions return compact engine results. The R wrappers convert those results into the same user-facing objects as the R split search: partysplit objects for return = "split" and candidate lists for return = "candidate".

Verification

The tests compare the C++ path against the current R implementation for:

• numeric split search,
• factor split search with unused levels,
• mixed-predictor global split search,
• tied socioeconomic rank values.

Run focused tests with:

testthat::test_file("tests/testthat/test-ci_split_search_cpp.R")