Package {xplaineff}

xplaineff: Generalized Additive Decomposition of Global EffecTs

Description

The **xplaineff** package implements the GADGET algorithm for interpretable machine learning. It builds a tree by recursively partitioning the feature space to minimize the heterogeneity of feature effects (e.g., Accumulated Local Effects or Partial Dependence), so that within each region the effects are more stable and easier to interpret.

Details

**Main components (user-facing):**

• GadgetTree: R6 class to grow and visualize effect-based trees.

• AleStrategy: Strategy for ALE-based trees (ALE computed internally from a fitted model).

• PdStrategy: Strategy for PD-based trees (uses precomputed ICE/PD from iml or similar tools).

**Typical workflow:**

1. Train a model (e.g., with mlr3).

2. Create a tree: tree = GadgetTree$new(strategy = AleStrategy$new(), n_split = 3, min_node_size = 50).

3. Fit: tree$fit(data, target_feature_name, ...). Strategy-specific ... arguments include:

   • AleStrategy: model (required), n_intervals = 10, predict_fun = NULL, order_method = "raw", ale_engine (default "auto"), categorical_split, and max_exhaustive_levels.

   • PdStrategy: either effect, or model with optional predict_fun, n_grid, pd_engine (default "auto"), categorical_split, and max_exhaustive_levels.

   • Both strategies accept feature_set and split_feature.

   • Tree parameters include impr_par, min_node_size, and n_quantiles.

4. Visualize: tree$plot_tree_structure(), tree$plot(...), tree$extract_split_info().

For PD-based trees, either pass an effect object from iml::FeatureEffects(..., method = "ice") to tree$fit(effect = ..., data = ..., target_feature_name = ...), or pass a fitted model and let xplaineff compute PD/ICE internally.

Author(s)

Maintainer: Zizheng Zhang Zizheng.Zhang@stat.uni-muenchen.de

References

Herbinger, J., Wright, M. N., Nagler, T., Bischl, B., and Casalicchio, G. (2024). Decomposing Global Feature Effects Based on Feature Interactions. Journal of Machine Learning Research, 25(23-0699), 1–65. URL: https://jmlr.org/papers/volume25/23-0699/23-0699.pdf.

Apley, D.W. and Zhu, J. (2016). Visualizing the Effects of Predictors on the Response in Nonlinear and Generalized Linear Models. Journal of Computational and Graphical Statistics, 25(2), 590–600.

See Also

GadgetTree, AleStrategy, PdStrategy

AleStrategy: Generalized Additive Decomposition Based on ALE Effects

Description

ALE-based effect strategy (inherits from EffectStrategy). Given model and data, preprocesses to Z/Y via prepare_split_data_ale; transforms ALE effects per node; computes ALE-derivative heterogeneity; finds best split via search_best_split_ale; fits tree and plots ALE curves.

Format

[R6::R6Class] object inheriting from [EffectStrategy].

Details

Intended for use through GadgetTree$new(strategy = AleStrategy$new()) and tree$fit(...). Can be instantiated directly for custom pipelines.

Construction

“' s = AleStrategy$new(categorical_split = "ordered_prefix") “'

Super class

::EffectStrategy -> AleStrategy

Public fields

Methods

Public methods

• AleStrategy$new()

• AleStrategy$preprocess()

• AleStrategy$node_transform()

• AleStrategy$heterogeneity()

• AleStrategy$get_child_objectives()

• AleStrategy$find_best_split()

• AleStrategy$plot()

• AleStrategy$fit()

• AleStrategy$clean()

• AleStrategy$clone()

Method new()

Create an AleStrategy instance (calls super$initialize("ale")).

Usage

AleStrategy$new(
  categorical_split = "ordered_prefix",
  max_exhaustive_levels = 12L
)

Arguments

Method preprocess()

Preprocess to Z and Y via prepare_split_data_ale.

Usage

AleStrategy$preprocess(
  model,
  effect = NULL,
  data,
  target_feature_name,
  n_intervals,
  feature_set = NULL,
  split_feature = NULL,
  predict_fun = NULL,
  order_method = "raw",
  ale_engine = c("auto", "cpp", "r")
)

Arguments

Returns

('list()')
Z: split features; Y: ALE effect data.tables.

Method node_transform()

Subset ALE by node indices; handle single-interval and categorical.

Usage

AleStrategy$node_transform(Y, idx, grid = NULL, is_child = FALSE)

Arguments

Returns

('list()')
Transformed ALE data.tables.

Method heterogeneity()

Compute ALE heterogeneity via calculate_ale_heterogeneity_cpp.

Usage

AleStrategy$heterogeneity(Y)

Arguments

Returns

('numeric()')
Heterogeneity per feature.

Method get_child_objectives()

Compute left/right child objective values from split result. For ALE, extracts from split_info (computed during sweep).

Usage

AleStrategy$get_child_objectives(
  Z,
  Y,
  split_info,
  idx_left,
  idx_right,
  grid_left,
  grid_right
)

Arguments

Returns

('list()')
left_objective_value_j, right_objective_value_j, left_objective_value, right_objective_value.

Method find_best_split()

Find best split via search_best_split_ale.

Usage

AleStrategy$find_best_split(Z, Y, min_node_size, n_quantiles)

Arguments

Returns

('list()' or 'data.frame()')
Best split info: split_feature, split_point, etc.

Method plot()

Plot ALE curves via plot_tree_ale.

Usage

AleStrategy$plot(
  tree,
  effect = NULL,
  data,
  target_feature_name,
  depth = NULL,
  node_id = NULL,
  features = NULL,
  show_plot = TRUE,
  show_point = TRUE,
  mean_center = TRUE,
  ...
)

Arguments

Returns

('list()')
Nested list (depth -> node -> patchwork).

Method fit()

Fit tree: preprocess, create root, split recursively.

Usage

AleStrategy$fit(
  tree,
  model,
  effect = NULL,
  data,
  target_feature_name,
  n_intervals = 10,
  feature_set = NULL,
  split_feature = NULL,
  predict_fun = NULL,
  order_method = "raw",
  ale_engine = c("auto", "cpp", "r"),
  categorical_split = NULL,
  max_exhaustive_levels = NULL,
  ...
)

Arguments

Returns

('GadgetTree')
The tree, invisibly.

Method clean()

Sets data and model to NULL to free memory after fitting. effect is intentionally retained because plot() requires it post-fit.

Usage

AleStrategy$clean()

Method clone()

The objects of this class are cloneable with this method.

Usage

AleStrategy$clone(deep = FALSE)

Arguments

See Also

calculate_ale_heterogeneity_cpp

Examples

ale_strat = AleStrategy$new()
ale_strat$categorical_split

EffectStrategy: Abstract base for effect-based tree strategies.

Description

EffectStrategy: Abstract base for effect-based tree strategies.

EffectStrategy: Abstract base for effect-based tree strategies.

Details

Defines the common interface and shared fit logic for AleStrategy and PdStrategy. Effect strategies implement ALE (Accumulated Local Effects) or PD (Partial Dependence) based tree growing. Not exported.

Public fields

Methods

Public methods

• EffectStrategy$new()

• EffectStrategy$clean()

• EffectStrategy$clone()

Method new()

Create an EffectStrategy instance.

Usage

EffectStrategy$new(name)

Arguments

Method clean()

Optional post-fit cleanup to release retained objects. Default is no-op; subclasses override when needed (see AleStrategy$clean()).

Usage

EffectStrategy$clean()

Method clone()

The objects of this class are cloneable with this method.

Usage

EffectStrategy$clone(deep = FALSE)

Arguments

GadgetTree: Regional feature-effect tree

Description

Wrapper for effect-based trees: given a strategy (pd/ale), fits tree via $fit(), plots effects via $plot(), extracts splits via $extract_split_info(). Delegates all effect logic to the strategy.

Format

[R6::R6Class] object.

Details

This class manages the overall tree structure and delegates effect-specific operations (such as splitting and plotting) to the provided strategy object. It is the main entry point for fitting and visualizing effect-based decision trees in the xplaineff package.

Construction

“' t = GadgetTree$new(strategy, n_split = 2, impr_par = 0.1, min_node_size = 10, n_quantiles = NULL) “' * 'strategy' :: ([AleStrategy] | [PdStrategy])
Effect strategy object. * 'n_split' :: 'integer(1)'
Maximum split depth, counted as splits along any root-to-leaf path. * 'impr_par' :: 'numeric(1)'
Improvement threshold. * 'min_node_size' :: 'integer(1)'
Minimum samples per node. * 'n_quantiles' :: 'integer(1)' or 'NULL'
Number of quantile cut points for numeric split candidates; 'NULL' = use all unique values.

Public fields

Methods

Public methods

• GadgetTree$new()

• GadgetTree$fit()

• GadgetTree$plot()

• GadgetTree$plot_tree_structure()

• GadgetTree$extract_split_info()

• GadgetTree$get_tree_list()

• GadgetTree$clone()

Method new()

Initialize tree parameters.

Usage

GadgetTree$new(
  strategy,
  n_split = 2,
  impr_par = 0.1,
  min_node_size = 10,
  n_quantiles = NULL
)

Arguments

Method fit()

Fit tree via strategy$fit().

Usage

GadgetTree$fit(
  data,
  target_feature_name,
  feature_set = NULL,
  split_feature = NULL,
  ...
)

Arguments

Returns

('GadgetTree')
The tree, invisibly.

Method plot()

Plot tree via strategy$plot().

Usage

GadgetTree$plot(
  data,
  target_feature_name,
  effect = NULL,
  depth = NULL,
  node_id = NULL,
  features = NULL,
  ...
)

Arguments

Returns

('list()')
Nested list (depth -> node -> patchwork).

Method plot_tree_structure()

Converts root to depth-list and calls plot_tree_structure(). Prints graph.

Usage

GadgetTree$plot_tree_structure(
  label_wrap_width = 34L,
  node_spread_x = 1.55,
  node_spread_y = 1.12
)

Arguments

Method extract_split_info()

Extract split info from tree.

Usage

GadgetTree$extract_split_info(include_timing = FALSE)

Arguments

Returns

('data.frame()')
Split info: depth, id, split_feature, split_value, int_imp, etc.

Method get_tree_list()

Get depth-based tree list (cached). Invalidated on $fit().

Usage

GadgetTree$get_tree_list()

Returns

('list()')
Depth-based list of nodes.

Method clone()

The objects of this class are cloneable with this method.

Usage

GadgetTree$clone(deep = FALSE)

Arguments

Examples

tree = GadgetTree$new(strategy = PdStrategy$new(), n_split = 2L)
tree$n_split

Node: Tree Node for Effect-based Decision Trees (R6 class)

Description

Node: Tree Node for Effect-based Decision Trees (R6 class)

Node: Tree Node for Effect-based Decision Trees (R6 class)

Details

Represents a single node in an effect-based decision tree, storing split information, effect statistics, and child nodes. Uses grouped fields for clearer structure.

This class is used internally by GadgetTree and strategy objects to represent and manage nodes in effect-based decision trees. Each node stores split information, effect statistics, and references to its children.

Public fields

Methods

Public methods

• Node$new()

• Node$split_node()

• Node$find_best_split()

• Node$create_children()

• Node$create_child_grids()

• Node$apply_split()

• Node$clone()

Method new()

Create a node from id, depth, subset indices, grid, and optional parent/objective metadata. Sets stop_criterion_met = FALSE.

Usage

Node$new(
  id,
  depth = NULL,
  subset_idx,
  grid,
  id_parent = NULL,
  child_type = NULL,
  objective_value_parent = NULL,
  objective_value_j = NULL,
  objective_value = NULL,
  improvement_met = FALSE,
  int_imp = NULL,
  int_imp_j = NULL,
  strategy = NULL
)

Arguments

Method split_node()

Given Z, Y, root objectives, and tree params: checks stopping criteria; finds best split; creates and applies children; recurses into child nodes. Returns NULL if no valid split.

Usage

Node$split_node(
  Z,
  Y,
  objective_value_root_j,
  objective_value_root,
  min_node_size,
  n_quantiles,
  impr_par,
  depth,
  max_depth
)

Arguments

Returns

('NULL')

Method find_best_split()

Given Z (subset by node indices), y_curr, and params: calls strategy$find_best_split and returns list with split_feature, split_value, is_categorical (and for AleStrategy: left/right_objective_value_j).

Usage

Node$find_best_split(Z, y_curr, min_node_size, n_quantiles)

Arguments

Returns

('list()' or 'NULL')
Best split info or NULL if no valid split.

Method create_children()

Given Z, Y, split_info, and root objectives: computes idx_left/right, child grids, objective values; checks improvement threshold; creates left/right Node instances and sets parent info. Returns list of left_child, right_child, int_imp, int_imp_j or NULL if improvement too small.

Usage

Node$create_children(
  z_split_feature,
  Y,
  split_info,
  objective_value_root_j,
  objective_value_root,
  impr_par
)

Arguments

Returns

('list()')
Left/right child nodes and split statistics.

Method create_child_grids()

Given split_feature, split_value, and is_categorical: partitions self$grid[[split_feature]] into left (<= or ==) and right (> or !=). Returns list grid_left, grid_right.

Usage

Node$create_child_grids(
  split_feature,
  split_value,
  is_categorical,
  split_levels = NULL
)

Arguments

Returns

('list()')
grid_left, grid_right.

Method apply_split()

Given split_info and children_info: sets split_feature, split_value, int_imp, int_imp_j, children.

Usage

Node$apply_split(split_info, children_info)

Arguments

Returns

('NULL')

Method clone()

The objects of this class are cloneable with this method.

Usage

Node$clone(deep = FALSE)

Arguments

PdStrategy: Generalized Additive Decomposition Based on PD Effects

Description

PD-based effect strategy (inherits from EffectStrategy). Given effect or model and data, preprocesses to Z/Y/grid; mean-centers effects per node; computes sum-of-variances heterogeneity; finds best split via C++; fits tree and plots PD/ICE. Character feature columns are coerced to factor before ICE/PD computation so they match split-matrix treatment and learner conventions (same as prepare_split_data_common).

Format

[R6::R6Class] object inheriting from [EffectStrategy].

Details

This class is used internally by the GadgetTree framework to implement partial dependence tree growing, splitting, and visualization. It is not intended to be used directly by end users, but can be instantiated for advanced customization.

Construction

“' s = PdStrategy$new(categorical_split = "one_vs_rest") “'

Super class

::EffectStrategy -> PdStrategy

Public fields

Methods

Public methods

• PdStrategy$new()

• PdStrategy$preprocess()

• PdStrategy$node_transform()

• PdStrategy$heterogeneity()

• PdStrategy$get_child_objectives()

• PdStrategy$find_best_split()

• PdStrategy$plot()

• PdStrategy$fit()

• PdStrategy$clean()

• PdStrategy$clone()

Method new()

Create a PdStrategy instance (calls super$initialize("pd")).

Usage

PdStrategy$new(categorical_split = "one_vs_rest", max_exhaustive_levels = 12L)

Arguments

Method preprocess()

Preprocess to Z, Y, grid via prepare_split_data_pd.

Usage

PdStrategy$preprocess(
  effect,
  data,
  target_feature_name = NULL,
  feature_set = NULL,
  split_feature = NULL
)

Arguments

Returns

('list()')
Z, Y, grid.

Method node_transform()

Subset and mean-center via re_mean_center_ice_cpp.

Usage

PdStrategy$node_transform(Y, idx, grid, is_child = FALSE)

Arguments

Returns

('list()')
Mean-centered effect matrices.

Method heterogeneity()

Compute heterogeneity via node_heterogeneity.

Usage

PdStrategy$heterogeneity(Y)

Arguments

Returns

('numeric()')
Heterogeneity per feature.

Method get_child_objectives()

Compute left/right child objective values via node_transform and heterogeneity.

Usage

PdStrategy$get_child_objectives(
  Z,
  Y,
  split_info,
  idx_left,
  idx_right,
  grid_left,
  grid_right
)

Arguments

Returns

('list()')
left_objective_value_j, right_objective_value_j, left_objective_value, right_objective_value.

Method find_best_split()

Find best split via search_best_split_cpp.

Usage

PdStrategy$find_best_split(Z, Y, min_node_size, n_quantiles)

Arguments

Returns

('data.frame()' or 'list()')
Best split info.

Method plot()

Plot PD/ICE tree via plot_tree_pd.

Usage

PdStrategy$plot(
  tree,
  effect = NULL,
  data,
  target_feature_name,
  depth = NULL,
  node_id = NULL,
  features = NULL,
  ...
)

Arguments

Returns

('list()')
Nested list (depth -> node -> patchwork).

Method fit()

Fit tree: preprocess, create root, split recursively.

Usage

PdStrategy$fit(
  tree,
  effect = NULL,
  model = NULL,
  data,
  target_feature_name,
  feature_set = NULL,
  split_feature = NULL,
  predict_fun = NULL,
  n_grid = 20L,
  pd_engine = c("auto", "cpp", "r"),
  categorical_split = NULL,
  max_exhaustive_levels = NULL,
  ...
)

Arguments

Returns

('GadgetTree')
The tree, invisibly.

Method clean()

Drops tree_ref; effect cache is intentionally retained when present.

Usage

PdStrategy$clean()

Method clone()

The objects of this class are cloneable with this method.

Usage

PdStrategy$clone(deep = FALSE)

Arguments

Examples

pd_strat = PdStrategy$new()
pd_strat$categorical_split

ALE for a single categorical feature.

Description

ALE for a single categorical feature.

Usage

ale_categorical_feature(
  model,
  data,
  X,
  feature,
  predict_fun = NULL,
  stacked = NULL,
  idx_lower = NULL,
  idx_upper = NULL,
  predictor = NULL
)

Arguments

Value

('data.table()')
ALE data with row_id, feat_val, d_l, interval_index, etc.

Fast ALE for a single feature.

Description

Fast ALE for a single feature.

Usage

ale_feature(
  data,
  X,
  stacked,
  idx_lower,
  idx_upper,
  feature,
  n_intervals = 10L,
  predictor
)

Arguments

Value

('data.table()')
ALE data with row_id, feat_val, d_l, interval_index, etc.

ALE for a single numeric feature.

Description

ALE for a single numeric feature.

Usage

ale_numeric_feature(
  model,
  data,
  X,
  feature,
  n_intervals = 10,
  predict_fun = NULL,
  stacked = NULL,
  idx_lower = NULL,
  idx_upper = NULL,
  predictor = NULL
)

Arguments

Value

('data.table()')
ALE data with row_id, feat_val, d_l, interval_index, etc.

Build per-feature interval statistics for ALE effect.

Description

Build per-feature interval statistics for ALE effect.

Usage

build_ale_interval_stats(effect, features)

Arguments

Value

('list()')
Statistics: K, offsets, tot_n, tot_s1, tot_s2, r_n, r_s1, r_s2, r_risks, d_l_mat, interval_idx_mat.

Build order and split candidates for ALE sweep.

Description

Build order and split candidates for ALE sweep.

Usage

build_ale_order_and_candidates(z, is_categorical, n_quantiles = NULL)

Arguments

Value

('list()' or 'NULL')
ord_idx, z_sorted, n_obs, is_cand; for categorical also boundary_pos, levels_vec. NULL if no valid split.

Build node title for ALE or PD tree plots.

Description

Build node title for ALE or PD tree plots.

Usage

build_node_title(node, depth_idx, tree, style = c("ale", "pd"))

Arguments

Value

('character(1)')
Title string.

Calculate Accumulated Local Effects (ALE)

Description

Given model, data, feature_set, target_feature_name, n_intervals, predict_fun: for each feature, computes finite differences (d_l) and per-interval stats (int_n, int_s1, int_s2). Numeric: quantile intervals; categorical: level-by-level prediction differences. Returns named list of data.tables (row_id, feat_val, d_l, interval_index, int_n, int_s1, int_s2, etc.).

Usage

calculate_ale(
  model,
  data,
  feature_set,
  target_feature_name,
  n_intervals = 10,
  predict_fun = NULL
)

Arguments

Details

Numeric features: builds n_intervals quantile-based intervals, assigns each row to an interval, and computes finite differences between interval boundaries via predict_fun.

Categorical features: use factor levels as given (typically pre-ordered by order_categorical_levels in prepare_split_data_ale). For each row, d_l is the difference in predictions when the focal feature is set to the next vs. previous level; single-level factors get d_l = 0.

Sample-level columns (row_id, feat_val, d_l, etc.) support subsetting by node and downstream heterogeneity calculation.

Downstream plotting (prepare_plot_data_ale) aggregates these rows by (interval_index, x_left, x_right), cumulates d_l, and optionally mean-centers the cumulative curve; plot grids for categories derive from aggregated x_left values, not by re-evaluating calculate_ale.

Value

('list()')
Named list of data.tables per feature_set. Each has columns:

Calculate ALE via C++ kernels

Description

Fast ALE path that keeps model prediction in R, while using C++ kernels for interval indexing and interval-wise aggregation. Numeric and categorical branches stack lower/upper (or plus/minus) configurations into 2n rows and call the predictor once per feature, matching the batched predict_newdata_fast pattern used in xplaineff::ale.

Usage

calculate_ale_fast(
  model,
  data,
  feature_set,
  target_feature_name,
  n_intervals = 10,
  predict_fun = NULL
)

Arguments

Value

('list()')
Named list of ALE data.tables, same schema as calculate_ale().

Calculate ALE Heterogeneity

Description

Calculate ALE Heterogeneity

Usage

calculate_ale_heterogeneity_cpp(Y)

Arguments

Value

('numeric()')
Heterogeneity value(s): vector per feature when Y is list, single value when Y is data.frame.

Calculate Partial Dependence Curves

Description

Computes ICE (Individual Conditional Expectation) matrices for each feature in feature_set and returns them in long-format data.tables.

Usage

calculate_pd(
  model,
  data,
  target_feature_name,
  feature_set = NULL,
  predict_fun = NULL,
  n_grid = 20L,
  pd_engine = c("auto", "cpp", "r")
)

Arguments

Value

('list()')
Named list with element results: a named list of data.tables, one per feature, each with columns .id, .type, .feature, .borders, .value.

Calculate Partial Dependence Matrices

Description

Internal matrix-form variant used by PdStrategy when effects are computed from a model. It avoids converting ICE matrices to long tables only to pivot them back to matrices before split search.

Usage

calculate_pd_matrix(
  model,
  data,
  target_feature_name,
  feature_set = NULL,
  predict_fun = NULL,
  n_grid = 20L,
  pd_engine = c("auto", "cpp", "r")
)

Arguments

Value

('list()')
Object of class xplaineff_pd_matrix with Y and grid.

Compute y-axis range for PD plots.

Description

Compute y-axis range for PD plots.

Usage

calculate_y_range(
  prepared_data,
  data,
  target_feature_name,
  mean_center = FALSE
)

Arguments

Value

('list()')
ymin, ymax.

Shared implementation for y-axis range from effect values.

Description

Shared implementation for y-axis range from effect values.

Usage

calculate_y_range_impl(effect_values, data = NULL, target_feature_name = NULL)

Arguments

Value

('list()')
ymin, ymax.

Return comparison operator for child relative to parent. Given parent_node and current_node: if current is left child returns <= (numeric) or = (categorical); if right returns > or !=.

Description

Return comparison operator for child relative to parent. Given parent_node and current_node: if current is left child returns <= (numeric) or = (categorical); if right returns > or !=.

Usage

choose_operator(parent_node, current_node)

Arguments

Value

('character(1)')
"<=", ">", "=", or "!=".

Compute ICE Matrix (Dispatch)

Description

Dispatches ICE computation to the C++, R, or row-major backend based on pd_engine.

Usage

compute_ice(
  model,
  data,
  feature,
  grid,
  predict_fun = NULL,
  pd_engine = c("cpp", "r", "row_major"),
  base_data_dt = NULL,
  cols_list = NULL,
  feature_index = NULL,
  stacked_pd_cache = NULL,
  predictor = NULL,
  base_data_df = NULL
)

Arguments

Value

('matrix')
Numeric matrix of shape n_obs x length(grid) containing ICE predictions.

Compute ICE Matrix (C++ Backend)

Description

Uses cpp_pd_stack_newdata to build the stacked prediction table in C++. Prediction still runs through the shared predictor wrapper. Character and logical focal feature columns are unsupported in this path.

Usage

compute_ice_cpp(
  model,
  data,
  feature,
  grid,
  predict_fun = NULL,
  base_data_dt = NULL,
  cols_list = NULL,
  feature_index = NULL,
  predictor = NULL
)

Arguments

Value

('matrix')
Numeric matrix of shape n_obs x length(grid).

Compute ICE Matrix (Pure R)

Description

Builds a stacked prediction data.table by repeating each row once per grid value, replaces the focal feature column with each grid value, runs pd_predict, and reshapes predictions into a matrix.

Usage

compute_ice_r(
  model,
  data,
  feature,
  grid,
  predict_fun = NULL,
  base_data_dt = NULL,
  stacked_pd_cache = NULL,
  predictor = NULL
)

Arguments

Value

('matrix')
Numeric matrix of shape n_obs x length(grid).

Compute ICE Matrix (Row-Major Backend)

Description

Builds full ICE prediction data in observation-major order: all grid values for observation 1, then all grid values for observation 2, and so on. Prediction still runs through the shared predictor wrapper.

Usage

compute_ice_row_major(
  model,
  data,
  feature,
  grid,
  predict_fun = NULL,
  base_data_dt = NULL,
  base_data_df = NULL,
  predictor = NULL
)

Arguments

Value

('matrix')
Numeric matrix of shape n_obs x length(grid).

Convert Recursive Tree to Depth-based List

Description

Given root_node and optional max_depth: traverses children recursively, collects nodes by depth. Returns list of lists (depth 1, 2, ...), each element a list of Node objects at that depth.

Usage

convert_tree_to_list(root_node, max_depth = NULL)

Arguments

Value

('list()')
List where each element is a depth level containing Node objects.

Create PD plots for one depth.

Description

Create PD plots for one depth.

Usage

create_plots_for_depth(
  tree,
  prepared_data,
  data,
  target_feature_name,
  depth_idx,
  nodes_to_render,
  color_ice,
  color_pd,
  show_plot,
  show_point,
  mean_center
)

Arguments

Value

('list()')
Named list of patchwork objects per node.

Cumulative sum with NA as zero.

Description

Cumulative sum with NA as zero.

Usage

cumsum_na_as_zero(values)

Arguments

Value

('numeric()')
Cumulative sum.

Ensure character columns are factors.

Description

Ensure character columns are factors.

Usage

ensure_factors(data, cols)

Arguments

Value

('data.frame()' or 'data.table()')
Modified data (by reference for data.table).

Extract Split Information from Tree Structure

Description

Given tree (depth-list of Node objects) and optional split_benchmark: flattens nodes; builds one row per node (depth, id, n_obs, split_feature, split_value, int_imp, int_imp_j, etc.); merges timing if split_benchmark has node_id/depth. Returns data frame.

Usage

extract_split_info(tree, split_benchmark = NULL)

Arguments

Details

This function is used internally by the GadgetTree framework to extract and summarize the structure and statistics of effect-based decision trees. It is useful for interpretation, reporting, and benchmarking.

Value

('data.frame()')
One row per node: split feature/value, statistics, and (if available) timing.

Convert factor to numeric. Given f: if all level labels parse as numbers, uses as.numeric(as.character(f)); otherwise uses as.numeric(f) (level indices). Returns numeric vector.

Description

Convert factor to numeric. Given f: if all level labels parse as numbers, uses as.numeric(as.character(f)); otherwise uses as.numeric(f) (level indices). Returns numeric vector.

Usage

factor_to_numeric(f)

Arguments

Value

('numeric()')
Numeric vector.

Find node by id in a flat list.

Description

Given node_list and id: loops and returns first node with node$id == id, or NULL.

Usage

find_node_by_id(node_list, id)

Arguments

Value

('Node' or 'NULL')
The node with matching id, or NULL if not found.

Internal ALE curve computation

Description

Given ALE data.table for one feature and mean_center: cumsums d_l by interval; optionally subtracts global mean. Returns data.table with x_grid and .value (cumulative ALE).

Usage

mean_center_ale(feat, mean_center = TRUE)

Arguments

Value

('data.table()')
Cumulative ALE with x_grid and cumulative values in column d_l.

Build wide effect matrices from iml-style effect containers

Description

Expects effect$results as either a single data.frame or a named list of per-feature tables. Delegates pivoting to pivot_effect_to_wide.

Usage

mean_center_ice(effect, feature_set = NULL, mean_center = TRUE)

Arguments

Details

If effect$results is a data.frame, one feature is inferred from column names. If it is a named list, each element is pivoted separately.

Value

('list()')
Y: named list of matrices per feature; grid: column names (grid coordinates) per feature.

Compute heterogeneity per feature from effect matrices

Description

Given Y (list of numeric matrices): for each matrix, computes sum over columns of (sum of squares - (sum)^2/n) via node_heterogeneity_cpp. Returns numeric vector of length length(Y).

Usage

node_heterogeneity(Y)

Arguments

Value

('numeric()')
Heterogeneity per feature, length length(Y).

Node Transform ALE

Description

Subsets ALE effect data to the current node's row indices and recomputes per-interval statistics. When is_child is TRUE, forces d_l = 0 for any feature whose values are constant in this node (single unique value).

Usage

node_transform_ale(Y, idx, is_child = FALSE)

Arguments

Value

('list()')
Transformed ALE effects per feature.

Order Levels of a Categorical Feature

Description

Given x_cat (factor), data, feature, target_feature_name, order_method: builds KxK distance matrix from other features (ECDF diff for numeric, L1 for categorical); embeds in 1D via MDS/PCA/random/raw; reorders levels. Returns factor with reordered levels (or x_cat unchanged if K<=1 or no other features).

Usage

order_categorical_levels(
  x_cat,
  data,
  feature,
  target_feature_name,
  order_method = "raw"
)

Arguments

Details

For each pair of levels, a distance is computed from all other features (all columns in data except feature and target_feature_name):

• Numeric: sum over features of max absolute difference of ECDFs (KS-style).

• Categorical: sum over features of half-L_1 (total variation) distance between conditional level distributions, matching the convention used in the ale package.

The K \times K distance matrix is embedded in 1D via order_method; that 1D order defines the new level order. Single-level factors or no other features yield x_cat unchanged.

Value

('factor()')
Same as x_cat with reordered levels and ordered = TRUE; unchanged if nlevels(x_cat) <= 1 or no other features.

Build Feature Grid for Partial Dependence

Description

Returns grid values for a single feature column: factor levels (after droplevels), unique sorted values for character, or n_grid quantile-based numeric values.

Usage

pd_feature_grid(x, n_grid)

Arguments

Value

('atomic vector')
Grid values: character() for factor/character, numeric() otherwise.

Pack ICE Matrix into Long-Format data.table

Description

Converts an n_obs x length(grid) ICE matrix into a long-format data.table with one row per (observation, grid value) pair.

Usage

pd_pack_ice_result(ice, feature, grid)

Arguments

Value

('data.table')
Columns: .id (observation index), .type ("ice"), .feature, .borders, .value (prediction).

Generate Predictions for New Data

Description

Calls predict_fun (or the default predict method) on newdata and extracts a numeric prediction vector via extract_numeric_prediction.

Usage

pd_predict(model, newdata, predict_fun = NULL)

Arguments

Value

('numeric()')
Numeric prediction vector of length nrow(newdata).

Pivot tabular effect data to wide numeric columns

Description

Uses data.table::dcast on data: rows indexed by id_cols (all columns except grid_col and value_col), columns by grid_col.

Usage

pivot_effect_to_wide(
  data,
  grid_col,
  value_col = ".value",
  drop_cols = c(".type", ".id"),
  mean_center = FALSE
)

Arguments

Value

('data.frame')
Wide numeric matrix-like frame (columns are grid cells).

Build per-feature ALE panels (mean curve only)

Description

Helper used by plot_tree_ale() to generate per-feature ALE mean panels (optionally with overlaid observation points).

Usage

plot_regional_ale(
  curves,
  color_ale = "lightcoral",
  target_feature_name,
  mean_center = TRUE,
  ymin = NULL,
  ymax = NULL,
  show_point = FALSE,
  point_values = NULL,
  x_limits = NULL
)

Arguments

Value

('list()')
Named list of ggplot objects per feature.

Plot regional PD/ICE for one node.

Description

Plot regional PD/ICE for one node.

Usage

plot_regional_pd(
  prepared_data,
  origin_data,
  target_feature_name,
  node_idx,
  color_ice,
  color_pd,
  ymin,
  ymax,
  split_condition = NULL,
  show_point,
  mean_center
)

Arguments

Value

('list()')
List of ggplot objects per feature.

Plot ALE curves for selected tree nodes

Description

External helper mirroring plot_tree_pd, used by AleStrategy$plot. Produces patchwork objects per node with ALE mean curves and optional observation points. Y-axis limits use global and node-specific cumulative ALE (d_l). When show_point = TRUE, the node subset response is merged into ylim so overlaid points are not clipped by coord_cartesian. x limits follow the global grid. Y-axis labels use target_feature_name, matching PD tree plots.

Usage

plot_tree_ale(
  tree,
  effect,
  data,
  target_feature_name,
  depth = NULL,
  node_id = NULL,
  features = NULL,
  color_ale = "lightgreen",
  show_plot = TRUE,
  show_point = TRUE,
  mean_center = TRUE,
  ...
)

Arguments

Value

('list()')
Nested list (depth -> node -> patchwork).

Plot PD/ICE tree by depth and node.

Description

Plot PD/ICE tree by depth and node.

Usage

plot_tree_pd(
  tree,
  effect,
  data,
  target_feature_name,
  color_ice = "lightblue",
  color_pd = "lightcoral",
  show_plot = TRUE,
  show_point = FALSE,
  mean_center = TRUE,
  depth = NULL,
  node_id = NULL,
  features = NULL
)

Arguments

Value

('list()')
Nested list (depth -> node -> patchwork).

Visualize the Tree Structure

Description

Given tree (depth-list of Node objects): calls prepare_layout_data to build layout data; creates parent map; builds edge list; creates ggraph plot with nodes labeled by split info and edges representing tree hierarchy. Returns ggplot object.

Usage

plot_tree_structure(
  tree,
  label_wrap_width = 34L,
  node_spread_x = 1.55,
  node_spread_y = 1.12
)

Arguments

Value

(ggplot)
Tree structure visualization.

Build layout data frame for tree structure plot

Description

Given tree (depth-list of Node objects): flattens to one row per node; extracts id, id_parent, split_feature, split_value, N, depth; builds label. Returns data frame for plot_tree_structure (ggraph).

Usage

prepare_layout_data(tree)

Arguments

Value

('data.frame()')
Columns: id, node_id, id_parent, split_feature, split_value, label, depth, etc.

Prepare ALE Plot Data for One or More Nodes

Description

Given effect (from calculate_ale), idx (row indices or list of such), features, mean_center: subsets ALE rows by idx; calls mean_center_ale per feature for cumulative and optional centering. Returns named list of mean_effect data.tables (or nested list if idx is list).

Usage

prepare_plot_data_ale(
  effect,
  idx = NULL,
  features = names(effect),
  mean_center = TRUE
)

Arguments

Details

Rows are subset with effect[[feat]][row_id %in% idx] when idx is non-NULL.

mean_center_ale() builds plot grids from aggregated intervals: means sample-wise d_l within each (interval_index, x_left, x_right) group (delta_aggr), cumulates, then optionally subtracts a weighted scalar f_j0. Sample-wise d_l == 0 is mapped to NA before aggregation so exact zeros do not enter group means.

For categorical features, each row of mean_effect corresponds to one row of delta_aggr; x_grid uses as.character(delta_aggr$x_left), so the number of plotted points follows the number of distinct aggregated intervals after subsetting (not always one row per factor level). Factor x_grid still carries full levels(feat_val) for axis ordering.

Value

('list()')
Named list of mean_effect data.tables per feature; nested if idx is list.

Prepare ALE Data for Tree Splitting

Description

Given model, data, target_feature_name, n_intervals, and optional feature/split sets: validates features; converts character to factor and orders levels via order_categorical_levels; builds Z (data.table of split columns); calls calculate_ale for Y. Returns list Z, Y.

Usage

prepare_split_data_ale(
  model,
  data,
  target_feature_name,
  n_intervals,
  feature_set = NULL,
  split_feature = NULL,
  predict_fun = NULL,
  order_method = "raw",
  ale_engine = c("auto", "cpp", "r")
)

Arguments

Details

Steps performed:

1. Resolve feature_set and split_feature against feature columns (see GadgetTree/AleStrategy for target-column validation).

2. For union(feature_set, split_feature), convert character columns to factor and order levels via order_categorical_levels (using droplevels internally).

3. Build Z as data[split_feature] (data.table).

4. Call calculate_ale(model, data, feature_set, ...) to get Y.

Stops with an error if any requested feature is missing from data.

Value

('list()')
Z: data.table of split features; Y: list of ALE effect data per feature.

Common preprocessing for ALE and PD split data.

Description

Resolves feature_set/split_feature, ensures factors, builds Z.

Usage

prepare_split_data_common(
  data,
  target_feature_name,
  feature_set,
  split_feature
)

Arguments

Value

('list()')
data, Z, feature_set, split_feature.

Prepare PD Data for Tree Splitting

Description

Given effect, data, and optional feature/split sets: resolves features; converts character to factor; builds Z (split columns); calls mean_center_ice for Y and grid.

Usage

prepare_split_data_pd(
  effect,
  data,
  target_feature_name = NULL,
  feature_set = NULL,
  split_feature = NULL
)

Arguments

Value

('list()')
Z: split-feature data.table; Y: mean-centered effects; grid: grid list.

Preprocess PD node data by depth.

Description

Preprocess PD node data by depth.

Usage

preprocess_node_data(tree, Y, grid_total, mean_center)

Arguments

Value

('list()')
Processed data per depth.

Resolve feature names against available columns.

Description

Resolve feature names against available columns.

Usage

resolve_split_features(requested, all_features, err_label)

Arguments

Value

('character()')
Resolved feature names.

Find best ALE split across features.

Description

Find best ALE split across features.

Usage

search_best_split_ale(
  Z,
  effect,
  min_node_size = 1L,
  n_quantiles = NULL,
  active_effect_tol = active_effect_rel_tol(),
  categorical_split = c("ordered_prefix", "exhaustive"),
  max_exhaustive_levels = 12L
)

Arguments

Value

('data.frame()')
Best split info with per-feature objective values.

Find best ALE split point for one feature.

Description

Find best ALE split point for one feature.

Usage

search_best_split_point_ale(
  z,
  effect,
  st_table,
  split_feat,
  is_categorical,
  n_quantiles = NULL,
  min_node_size = 1L,
  categorical_split = c("ordered_prefix", "exhaustive"),
  max_exhaustive_levels = 12L
)

Arguments

Value

('list()')
split_point, split_objective, objective_value_j, left_objective_value_j, right_objective_value_j, and split_levels.

Select depth indices to render based on tree, depth, and node_id.

Description

Select depth indices to render based on tree, depth, and node_id.

Usage

select_depths_to_render(tree, depth, node_id)

Arguments

Value

('integer()')
Depth indices to render.

Subset columns from data.frame or data.table.

Description

Subset columns from data.frame or data.table.

Usage

take_cols(data, cols)

Arguments

Value

('data.frame()' or 'data.table()')
Subset of columns.

Build path of split conditions from root to node

Description

Given node and tree (depth-list): walks parent chain via find_node_by_id; at each step builds condition string (e.g. "x <= 0.5") via choose_operator. Returns character vector of conditions (root to node).

Usage

track_split_condition(node, tree)

Arguments

Value

('character()')
Conditions from root to node (e.g. "x <= 0.5").

Internal C++ helpers and package symbols

Description

Functions and symbols used internally by the package. Not intended for direct use.