Quickstart Guide to ROOT

Installation

# install.packages("devtools")
devtools::install_github("peterliu599/ROOT")

What is ROOT?

ROOT (Rashomon set of Optimal Trees) learns interpretable binary weight functions that minimize a user-specified global objective function and are represented as sparse decision trees. Each unit is either included (w = 1) or excluded (w = 0) based on the covariates.

Rather than returning a single solution, ROOT returns a Rashomon set of near-optimal trees and extracts a characteristic tree that summarizes the common patterns across them.

Basic usage

The main function is ROOT(). At minimum, you supply a data frame of covariates together with either a custom objective (global_objective_fn) or an auxiliary column for the default objective: vsq, a per-unit variance contribution, or v, a per-unit score that ROOT centers at the mean of the included units. In the example below, vsq is the auxiliary column and x1 and x2 are the covariates available for splitting; columns named vsq and v are never used for splitting.

library(ROOT)
set.seed(123)

# Simulate 80 units with two covariates and a variance-type objective
n <- 80
dat <- data.frame(
  vsq  = c(rnorm(40, mean = 0.01, sd = 0.005),   # low-variance group
            rnorm(40, mean = 0.08, sd = 0.02)),   # high-variance group
  x1   = c(runif(40, 0, 1), runif(40, 0, 1)),
  x2   = c(rep(0, 40), rep(1, 40))               # x2 = 1 flags high-variance units
)

fit <- ROOT(
  data        = dat,
  num_trees   = 20,
  top_k_trees = TRUE,
  k           = 10,
  seed        = 123
)

Inspecting results

print(fit)      # brief summary
#> ROOT object
#>   Generalizability mode: FALSE 
#> 
#> Summary classifier (f):
#> n= 80 
#> 
#> node), split, n, loss, yval, (yprob)
#>       * denotes terminal node
#> 
#> 1) root 80 40 0 (0.5000000 0.5000000)  
#>   2) x2>=0.5 40  0 0 (1.0000000 0.0000000) *
#>   3) x2< 0.5 40  0 1 (0.0000000 1.0000000) *

summary(fit)    # full summary including Rashomon set details
#> ROOT object
#>   Generalizability mode: FALSE 
#> 
#> Summary classifier (f):
#> n= 80 
#> 
#> node), split, n, loss, yval, (yprob)
#>       * denotes terminal node
#> 
#> 1) root 80 40 0 (0.5000000 0.5000000)  
#>   2) x2>=0.5 40  0 0 (1.0000000 0.0000000) *
#>   3) x2< 0.5 40  0 1 (0.0000000 1.0000000) *
#> 
#> Global objective function:
#>   User-supplied: No (default objective used)
#> 
#> Diagnostics:
#>   Number of trees grown: 20
#>   Rashomon set size: 10
#>   Split strategy: midpoint
#>   % observations with w_opt == 1: 50.0%

plot(fit)       # visualize the characteristic tree

In this example, ROOT excludes the units with x2 = 1 (the high-variance group) and keeps the units with x2 = 0, so half of the units receive \(w = 1\). The covariate x1, which is unrelated to vsq, does not appear in the tree.

Next steps

General optimization: See vignette("optimization_path_example") for a detailed walkthrough.
Generalizability/transportability analysis: See vignette("generalizability_path_example") for applying ROOT to treatment effect transportability.
Help: ?ROOT for full argument documentation.