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
• tests/testthat/test-verification.R

src/ci_split_search_cpp.cpp is a maintained source file. This flat file documents the R wrappers; it does not contain the C++ implementation.

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 production tree and forest builders use the C++ split search by default: ci_tree_control() sets split_engine = "cpp", and the recursive builder calls best_global_ci_split_cpp() on that setting. Pass ci_tree_control(split_engine = "R") to use the R reference search instead. Both engines are expected to agree on the chosen partition, and both are covered by parity tests.

The historical development notes in the earlier sections of this record describe the period when the C++ path was an optional experiment. They are kept for provenance only; they are not current usage instructions.

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")