Package {figsr}

Title:	Fast Interpretable Greedy-Tree Sums for Tree Ensembles
Version:	0.1.1
Description:	Flexible, interpretable machine learning algorithm for additive tree sums (FIGS). Fits a sum of shallow classification and regression trees (CART) by greedily minimizing residual impurity, growing a new tree or deepening an existing one at each step, whichever reduces the residuals most. Supports regression and two-class classification, variable importance, bootstrap ensembling and seamless integration with 'parsnip' and 'tidymodels' workflows. The method is described in Tan et al. (2023) <doi:10.1073/pnas.2310151122>.
License:	MIT + file LICENSE
URL:	https://github.com/bonijoao/figsr
BugReports:	https://github.com/bonijoao/figsr/issues
Depends:	R (≥ 4.1)
Imports:	dials, graphics, parsnip, rlang, stats, tibble
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder:	knitr, rmarkdown
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.3.3
NeedsCompilation:	no
Packaged:	2026-08-31 20:27:29 UTC; jpab2
Author:	João Paulo Assis Bonifácio [aut, cre, cph], Geraldo Magela da Cruz Pereira [aut, cph], Pedro Mambelli Fernandes [aut, cph], João Vitor Andrade Alves de Souza [aut, cph]
Maintainer:	João Paulo Assis Bonifácio <jpab.27@hotmail.com>
Repository:	CRAN
Date/Publication:	2026-08-31 22:30:16 UTC

Bagging-FIGS: Ensemble of FIGS Models

Description

bagging_figs() fits an ensemble of FIGS models using bootstrap resampling to increase stability and predictive performance on noisy datasets.

Usage

bagging_figs(
  formula,
  data,
  n_estimators = 10,
  max_splits = 6,
  min_n = 5,
  mode = "regression",
  ...
)

Arguments

Value

An object of class bagging_figs_fit.

Examples

set.seed(42)
df <- data.frame(x1 = rnorm(50), x2 = rnorm(50), y = rnorm(50))
bag_fit <- bagging_figs(y ~ x1 + x2, data = df, n_estimators = 3)

Fit Fast Interpretable Greedy-Tree Sums (FIGS)

Description

figs() fits a Fast Interpretable Greedy-Tree Sums model for regression or binary classification tasks.

Usage

figs(
  formula,
  data,
  max_splits = 10,
  max_trees = NULL,
  min_n = 5,
  mode = "regression",
  subset = NULL,
  na.action = stats::na.omit,
  ...
)

Arguments

Details

Trees are grown one split at a time. At each step every leaf of every existing tree, plus the root of a possible new tree, competes for the split that most reduces the residual sum of squares; the single best candidate is taken and the residuals are recomputed against the whole sum. Growth stops at max_splits splits or when no candidate improves the fit.

Classification is limited to two classes. A factor outcome with more than two levels raises an error. The binary case is fitted on the 0/1 encoding of the outcome using the same sum-of-squares criterion, so the sum of the leaf values already estimates the probability of the second level; it is clamped to the unit interval at prediction time rather than passed through a link function.

Predictors are used exactly as supplied: numeric features are split at midpoints between sorted unique values, capped at 30 sample quantiles, and factor features are split by enumerating subsets of their levels, which is skipped above 10 levels. A factor level that was not seen in training raises an error at prediction time, as it does for the other model-frame based fitting functions in stats. Rows with a missing value in a predictor are dropped at fit time by stats::model.frame() and raise an error at prediction time.

Value

An object of class figsr_fit containing fitted tree structures, predictions, and metadata.

Examples

set.seed(123)
df <- data.frame(
  x1 = rnorm(100),
  x2 = rnorm(100),
  y = rnorm(100)
)
fit <- figs(y ~ x1 + x2, data = df, max_splits = 4)
print(fit)

FIGS Model Specification for Parsnip

Description

figs_tree() defines a Fast Interpretable Greedy-Tree Sums model for use with the parsnip and tidymodels ecosystem.

Usage

figs_tree(
  mode = "regression",
  engine = "figsr",
  max_splits = NULL,
  max_trees = NULL,
  min_n = NULL
)

Arguments

Value

A parsnip model specification object.

Examples

library(parsnip)
spec <- figs_tree(max_splits = 8) |>
  set_engine("figsr") |>
  set_mode("regression")
spec

Calculate Variable Importance for a figsr_fit Model

Description

figsr_importance() computes the total reduction in residual impurity (Sum of Squares gain) attributable to each predictor feature across all trees in the fitted FIGS model.

Usage

figsr_importance(object, relative = TRUE)

Arguments

Details

Each split node stores the reduction in residual sum of squares it achieved at the moment it was chosen. Importance for a feature is the sum of those gains over every split made on that feature, across all trees in the sum. Features never selected receive a gain of zero.

Value

A tibble with one row per predictor and columns feature, gain (raw sum-of-squares reduction) and importance, sorted by decreasing importance.

Examples

set.seed(42)
df <- data.frame(x1 = rnorm(50), x2 = rnorm(50))
df$y <- 2 * (df$x1 > 0) + rnorm(50, sd = 0.2)
fit <- figs(y ~ x1 + x2, data = df, max_splits = 3)
figsr_importance(fit)

Fitting Bridge for the Parsnip Interface

Description

fit_figs() is the function parsnip calls when fitting a figs_tree() specification with the "figsr" engine. It accepts either the formula interface or the x/y interface and forwards to figs(). Users normally call figs() or fit() instead.

Usage

fit_figs(
  formula = NULL,
  data = NULL,
  x = NULL,
  y = NULL,
  max_splits = 10,
  max_trees = NULL,
  min_n = 5,
  mode = "regression",
  ...
)

Arguments

Value

An object of class figsr_fit.

Examples

set.seed(42)
df <- data.frame(x1 = rnorm(60), x2 = rnorm(60))
df$y <- 2 * (df$x1 > 0) + rnorm(60, sd = 0.2)
fit_figs(x = df[, c("x1", "x2")], y = df$y, max_splits = 3)

Dials Parameter for Maximum Splits

Description

Dials Parameter for Maximum Splits

Usage

max_splits(range = c(2L, 20L), trans = NULL)

Arguments

Value

A dials parameter object.

Examples

max_splits()
max_splits(range = c(2L, 40L))

Dials Parameter for Maximum Trees

Description

Dials Parameter for Maximum Trees

Usage

max_trees(range = c(1L, 10L), trans = NULL)

Arguments

Value

A dials parameter object.

Examples

max_trees()
max_trees(range = c(1L, 5L))

Plot Method for figsr_fit Models

Description

plot.figsr_fit() visualizes individual decision trees comprising the Fast Interpretable Greedy-Tree Sums (FIGS) model using 100% Base R graphics (zero external package dependencies).

Usage

## S3 method for class 'figsr_fit'
plot(x, tree_idx = NULL, style = c("scientific", "modern", "classic"), ...)

Arguments

Value

Invisible NULL.

Examples

set.seed(42)
df <- data.frame(x1 = rnorm(50), x2 = rnorm(50), y = rnorm(50))
fit <- figs(y ~ x1 + x2, data = df, max_splits = 3)
plot(fit)
plot(fit, style = "scientific")
plot(fit, tree_idx = 1)

Predict Method for bagging_figs_fit Models

Description

Predict Method for bagging_figs_fit Models

Usage

## S3 method for class 'bagging_figs_fit'
predict(object, new_data, type = NULL, ...)

Arguments

Value

A tibble containing averaged ensemble predictions.

Examples

set.seed(42)
df <- data.frame(x1 = rnorm(60), x2 = rnorm(60))
df$y <- 2 * (df$x1 > 0) + rnorm(60, sd = 0.2)
bag_fit <- bagging_figs(y ~ x1 + x2, data = df, n_estimators = 3)
predict(bag_fit, new_data = df)

Predict Method for figsr_fit Models

Description

Predict Method for figsr_fit Models

Usage

## S3 method for class 'figsr_fit'
predict(object, new_data, type = NULL, ...)

Arguments

Value

A tibble with predictions in standardized tidymodels format.

Examples

set.seed(42)
df <- data.frame(x1 = rnorm(50), y = rnorm(50))
fit <- figs(y ~ x1, data = df)
predict(fit, new_data = df)

Internal / Parsnip Predict Bridge Function for figsr_fit

Description

Internal / Parsnip Predict Bridge Function for figsr_fit

Usage

predict_figs(object, new_data, type = "numeric", ...)

Arguments

Value

A tibble of predictions.

Examples

set.seed(42)
df <- data.frame(x1 = rnorm(60))
df$y <- 2 * (df$x1 > 0) + rnorm(60, sd = 0.2)
fit <- figs(y ~ x1, data = df, max_splits = 3)
predict_figs(fit, new_data = df, type = "numeric")

Print Method for figsr_fit Models

Description

Print Method for figsr_fit Models

Usage

## S3 method for class 'figsr_fit'
print(x, ...)

Arguments

Value

x, invisibly. Called for the side effect of printing a summary of the fitted tree sum to the console.

Examples

set.seed(42)
df <- data.frame(x1 = rnorm(60), x2 = rnorm(60))
df$y <- 2 * (df$x1 > 0) + rnorm(60, sd = 0.2)
print(figs(y ~ x1 + x2, data = df, max_splits = 3))

Summary Method for figsr_fit Models

Description

summary.figsr_fit() prints human-readable decision rules for each tree in the sum.

Usage

## S3 method for class 'figsr_fit'
summary(object, ...)

Arguments

Value

object, invisibly. Called for the side effect of printing the IF-THEN decision rules of each tree to the console.

Examples

set.seed(42)
df <- data.frame(x1 = rnorm(60), x2 = rnorm(60))
df$y <- 2 * (df$x1 > 0) + rnorm(60, sd = 0.2)
summary(figs(y ~ x1 + x2, data = df, max_splits = 3))

Update a FIGS Model Specification

Description

update() changes the arguments of a figs_tree() specification in place, the way tidymodels users expect of any model specification.

Usage

## S3 method for class 'figs_tree'
update(
  object,
  max_splits = NULL,
  max_trees = NULL,
  min_n = NULL,
  fresh = FALSE,
  ...
)

Arguments

Value

An updated figs_tree() specification.

Examples

spec <- figs_tree(max_splits = 4)
update(spec, max_splits = 8)