Documentation · e2tree — Explainable Ensemble Trees

Installation

Get e2tree on CRAN or GitHub.

          
# Stable release from CRAN
install.packages("e2tree")

# Development version from GitHub
install.packages("remotes")
remotes::install_github("massimoaria/e2tree")

Dependencies installed automatically: Rcpp, dplyr. Recommended: randomForest or ranger, rpart.plot, partykit.

Quick start

Classification in 5 steps.

          
library(e2tree)
library(randomForest)
library(rsample)
library(dplyr)

# 1. Split data
set.seed(42)
iris_split <- iris %>% initial_split(prop = 0.75)
training   <- training(iris_split)
validation <- testing(iris_split)

# 2. Train a tree-based ensemble
ensemble <- randomForest(
  Species ~ .,
  data       = training,
  importance = TRUE,
  proximity  = TRUE
)

# 3. Compute the co-occurrence dissimilarity matrix
D <- createDisMatrix(
  ensemble,
  data     = training,
  label    = "Species",
  parallel = list(active = FALSE)
)

# 4. Fit the explainable tree
setting <- list(
  impTotal = 0.1, maxDec = 0.01,
  n = 2,         level  = 5
)
tree <- e2tree(Species ~ ., training, D, ensemble, setting)

# 5. Predict, validate, explain
pred <- predict(tree, newdata = validation)
ev   <- eValidation(tree, D, ensemble)
vi   <- vimp(tree, data = training)
plot(tree, ensemble = ensemble)

createDisMatrix()

Derives the co-occurrence dissimilarity matrix from the Random Forest. Performance-critical computation is implemented in C++ via Rcpp; supports optional parallel execution.

createDisMatrix( ensemble, data, label, parallel = list(active = FALSE, no_cores = NULL) )

Argument	Type	Description
ensemble	rf / ranger	A fitted Random Forest model. Supports objects from randomForest and ranger.
data	data.frame	The training dataset used to fit the ensemble.
label	character	Name of the response variable column.
parallel	list	`active`: logical; enable parallel computation. `no_cores`: number of cores (NULL = auto-detect).

Returns: A symmetric numeric matrix of dimensions n × n with values in [0, 1]. Zero diagonal. Can be passed directly to e2tree().

e2tree()

Grows a single decision tree guided by the ensemble's dissimilarity structure. Returns an object of class e2tree.

e2tree( formula, data, D, ensemble, setting = list(impTotal = 0.1, maxDec = 0.01, n = 2, level = 5) )

Argument	Type	Description
formula	formula	Standard R formula specifying the response and predictors, e.g. `Species ~ .`
data	data.frame	Training dataset. Must match the data used to compute `D`.
D	matrix	Dissimilarity matrix produced by `createDisMatrix()`.
ensemble	rf / ranger	The original ensemble model. Used to extract terminal node assignments.
setting	list	Stopping rules: `impTotal` (min impurity), `maxDec` (min decrease), `n` (min observations), `level` (max depth).

predict.e2tree()

Predicts responses for new observations by routing them through the e2tree's split rules.

## S3 method for class 'e2tree' predict(object, newdata, ...)

Argument	Type	Description
object	e2tree	A fitted e2tree model.
newdata	data.frame	New data to predict. Must contain the same predictor columns.

Also available: fitted(object) returns training predictions, residuals(object) returns training residuals.

eValidation()

Assesses structural fidelity between the e2tree and the original ensemble by comparing their proximity matrices.

eValidation(tree, D, ensemble)

Returns: An eValidation object. Use measures() for concordance metrics, proximity() for the heatmap matrix, and plot() for visualisation.

vimp()

Computes global variable importance from the e2tree's split structure, weighted by the impurity decrease at each split.

vimp(tree, data)

Returns: A list with $vimp (numeric named vector) and $g_imp (a ggplot2 importance plot).

loi()

Computes Local Observation Importance — observation-level attribution scores indicating which observations most strongly drive each split.

loi(tree, ensemble, data, label) ## Permutation-based significance testing loi_perm(tree, ensemble, data, label, B = 100)

Returns: An loi (or loi_perm) object with print(), summary(), and plot() methods.

S3 methods

Standard interface for e2tree objects.

Class	Methods
e2tree	`print, summary, plot, predict, fitted, residuals, as.rpart, as.party, nodes, e2splits`
eValidation	`print, summary, plot, measures, proximity`
loi	`print, summary, plot`
loi_perm	`print, summary, plot`

Interoperability

Convert to rpart and partykit.

e2tree objects can be converted to two widely-used R tree formats, unlocking the full ecosystem of tree visualization and inspection tools.

          
# Convert to rpart for rpart.plot
rpart_obj <- as.rpart(tree, ensemble)
rpart.plot::rpart.plot(rpart_obj)

# Convert to partykit constparty
if (requireNamespace("partykit", quietly = TRUE)) {
  party_obj <- partykit::as.party(tree)
  plot(party_obj)
}

Accessors

Inspect the tree structure.

          
# All nodes as a data frame
nodes(tree)

# Terminal nodes only
nodes(tree, terminal = TRUE)

# Split information at each internal node
e2splits(tree)

API reference & usage guide.

Get e2tree on CRAN or GitHub.

Classification in 5 steps.

Standard interface for e2tree objects.

Convert to rpart and partykit.

Inspect the tree structure.