Package 'classbound'

Description

Wraps a pre-fitted model in a classbound object, adding the feature metadata (names, types, ranges, imputation values) required by boundary_compute() and plot_boundary(). This is the entry point for "bring your own model" (BYO) workflows, including native tidymodels workflows and parsnip model fits.

Usage

as_classbound(model, data, response = NULL, ...)

Arguments

Details

Unlike fit_model(), as_classbound() does not refit the model or call preprocess_data(). Feature metadata is extracted solely from the data argument, which should be the same data used to fit the model. If the model was fitted on scaled or transformed data, ensure data reflects that transformation.

as_classbound() dispatches on the class of model:

• Default: wraps any fitted model object (e.g., rpart, lda).

• workflow: requires the workflow to already be trained (via fit()). Use boundary_workflow_set() to train and wrap an entire workflow set at once.

• model_fit: wraps a fitted parsnip model.

Value

A classbound object ready for use with boundary_compute() and plot_boundary().

See Also

fit_model(), boundary_workflow_set(), boundary_compute()

Examples

library(palmerpenguins)
data(penguins)
peng_data <- na.omit(penguins[, c("species", "bill_length_mm", "bill_depth_mm")])

# Wrap any pre-fitted model
raw_model <- rpart::rpart(species ~ ., data = peng_data)
cb_model <- as_classbound(raw_model, data = peng_data, response = "species")

# Tidymodels: wrap a fitted workflow
# (boundary_workflow_set() does this automatically for entire workflow sets)

Description

Generates a 2D grid of predicted class labels (and optionally class probabilities) for a fitted classbound model. The resulting boundary data is stored in the returned object and consumed directly by plot_boundary().

Usage

boundary_compute(
  model,
  feature_range = NULL,
  resolution = 100,
  predfun = NULL,
  projection = NULL,
  reference = NULL,
  ...
)

Arguments

Details

2D slice (two-feature visualization)

When projection is NULL, boundary_compute() generates a regular grid over the two features named in feature_range. If the model was trained on more than two features, all remaining numeric features are fixed at their training-set median and categorical features at their training-set mode, unless you supply explicit values via reference.

This is a 2D slice of the full multivariate decision boundary. Two observations that appear in the same region may still be separated in a dimension that is held fixed. Use this mode when you want to examine how two specific features interact, or when your model was trained on exactly two features.

Projection (high-dimensional visualization)

When projection is provided, the 2D grid is generated in the projected space and then inverse-projected back to the original feature space before prediction. This means the model uses all of its training features; only the visualization is collapsed to two dimensions.

The projection ⁠$basis⁠ must be a numeric matrix with:

• row count equal to the number of training features, row names matching feature names

• exactly two columns (the projected axes)

• orthonormal columns (crossprod(basis) must equal diag(2))

Suitable bases can be obtained from prcomp() or the tourr package.

Multi-model comparison

Pass a named list of classbound objects (all trained on the same features and class levels) to compute boundaries for multiple models at once. The result contains a model column, suitable for use with plot_boundary(facet_col = "model").

Value

A modified classbound object with the additional class "classbound_boundary". The boundary grid is stored in ⁠$boundary_data⁠ (columns: x, y, prediction, and per-class probability columns when available). For multi-model input, also contains a model column.

See Also

fit_model(), plot_boundary(), boundary_workflow_set()

Examples

library(palmerpenguins)
data(penguins)
peng_data <- na.omit(penguins[, c("species", "bill_length_mm", "bill_depth_mm")])

# Fit and compute 2D boundary with auto-detected ranges
m <- fit_model(peng_data, species ~ ., rpart::rpart)
m <- boundary_compute(m, resolution = 50)
head(m$boundary_data)

# Explicit axis ranges
m <- boundary_compute(m,
  feature_range = list(bill_length_mm = c(30, 60), bill_depth_mm = c(10, 25)),
  resolution = 100
)

# 3-feature model visualized as a 2D slice
peng3d <- na.omit(penguins[, c(
  "species", "bill_length_mm",
  "bill_depth_mm", "flipper_length_mm"
)])
m3d <- fit_model(peng3d, species ~ ., rpart::rpart)
m3d_slice <- boundary_compute(m3d,
  feature_range = list(bill_length_mm = c(30, 60), bill_depth_mm = c(10, 25)),
  resolution = 50
)

# 3-feature model visualized via PCA projection
feat_cols <- c("bill_length_mm", "bill_depth_mm", "flipper_length_mm")
pca <- prcomp(peng3d[, feat_cols], scale. = TRUE)
basis <- pca$rotation[, 1:2]
m3d_proj <- boundary_compute(m3d,
  feature_range = list(PC1 = c(-4, 4), PC2 = c(-3, 3)),
  resolution = 50,
  projection = list(basis = basis, center = pca$center, scale = pca$scale)
)

Description

Generates a high-dimensional uniform domain and identifies points near the decision boundaries of multiple models.

Usage

boundary_explore_nd(models, data, n_points = 10000, threshold = 0.05)

Arguments

Value

A data frame containing the simulated coordinates, the predicted classes for each model (prefixed with Y_), and a logical is_boundary column indicating if the point is near the boundary for ANY of the provided models.

Description

A dedicated helper to automatically fit and extract classification boundaries for an entire workflow_set. This avoids the need for manual iteration over models.

Usage

boundary_workflow_set(
  wf_set,
  data,
  feature_range = NULL,
  response,
  resolution = 100,
  ...
)

Arguments

Value

A data frame containing the combined boundary grid for all models, with a model column indicating the wflow_id.

Examples

library(palmerpenguins)
library(workflowsets)
library(parsnip)

data(penguins)
peng_data <- na.omit(penguins[, c("species", "bill_length_mm", "bill_depth_mm")])

# Define multiple engines
spec_rpart <- decision_tree() |>
  set_engine("rpart") |>
  set_mode("classification")
spec_glm <- multinom_reg() |>
  set_engine("nnet") |>
  set_mode("classification")

# Create a workflow set
wf_set <- workflow_set(
  preproc = list(base = species ~ bill_length_mm + bill_depth_mm),
  models = list(tree = spec_rpart, log_reg = spec_glm)
)

# Compute 2D boundaries for all models simultaneously (auto-range)
bounds <- boundary_workflow_set(wf_set, peng_data, response = "species", resolution = 30)

Description

A high-level unified wrapper to fit a model, compute its 2D decision boundary, and plot the results in a single step.

Usage

classbound(
  data,
  formula,
  classifier,
  interface = c("formula", "matrix", "custom"),
  projection = NULL,
  fit_args = list(),
  predict_args = list(),
  predfun = NULL,
  resolution = 100,
  ...
)

Arguments

Value

A ggplot object visualizing the 2D decision boundary and original observations.

Examples

library(palmerpenguins)
data(penguins)
peng_data <- na.omit(penguins[, c("species", "bill_length_mm", "bill_depth_mm")])

# Quick 2D boundary visualization for an SVM
classbound(peng_data, species ~ bill_length_mm + bill_depth_mm, e1071::svm)

Description

Returns a named character vector mapping class labels to hex color codes. Colors are assigned deterministically: class labels are sorted alphabetically before assignment, so the same class always receives the same color regardless of the order the classes are supplied.

Usage

classbound_palette(classes)

Arguments

Details

The first 20 classes are assigned colors from a curated palette of visually distinct hues designed for use on both light and dark backgrounds. For more than 20 classes, additional colors are generated using the golden-angle method (hue = (index * phi) %% 1 where ⁠phi = 0.618...⁠), which produces perceptually distinct colors with uniform spacing in HCL space.

plot_boundary() uses this palette by default. If an RColorBrewer palette is requested via ⁠palette =⁠ but cannot accommodate the number of classes (e.g., "Dark2" supports a maximum of 8), it automatically falls back to classbound_palette().

Value

A named character vector where names are the unique sorted class labels and values are hex color codes (e.g., "#E6194B").

See Also

plot_boundary()

Examples

# 3-class palette
classbound_palette(c("Adelie", "Chinstrap", "Gentoo"))

# Colors are alphabetically ordered, so order of input doesn't matter
identical(
  classbound_palette(c("B", "A", "C")),
  classbound_palette(c("C", "A", "B"))
)

# Use in plot_boundary() via the palette argument

library(palmerpenguins)
data(penguins)
peng_data <- na.omit(penguins[, c("species", "bill_length_mm", "bill_depth_mm")])
m <- fit_model(peng_data, species ~ ., rpart::rpart)
m <- boundary_compute(m, resolution = 50)
plot_boundary(m,
  obs_data = peng_data, x_col = "bill_length_mm",
  y_col = "bill_depth_mm", true_label = "species"
)

Description

A subset of the UCI Waveform Database Generator dataset (Version 1). Contains 5000 observations with 21 numeric features and a 3-class response variable. All 21 features contribute to class membership, making this a useful dataset for demonstrating high-dimensional boundary visualization, including 2D slice and projection-based approaches.

Usage

data(data69_1)

Format

A data frame with 5000 rows and 22 columns:

Y

Class label: a factor with 3 levels ("1", "2", "3")

V1

Numeric feature variable

V2

Numeric feature variable

V3

Numeric feature variable

V4

Numeric feature variable

V5

Numeric feature variable

V6

Numeric feature variable

V7

Numeric feature variable

V8

Numeric feature variable

V9

Numeric feature variable

V10

Numeric feature variable

V11

Numeric feature variable

V12

Numeric feature variable

V13

Numeric feature variable

V14

Numeric feature variable

V15

Numeric feature variable

V16

Numeric feature variable

V17

Numeric feature variable

V18

Numeric feature variable

V19

Numeric feature variable

V20

Numeric feature variable

V21

Numeric feature variable

Details

Each observation is generated from one of three waveform classes. All features are numeric; the response variable Y is a factor with levels "1", "2", and "3". Load the dataset with data(data69_1).

This dataset is included primarily to demonstrate high-dimensional boundary visualization with tools like PCA projection and tourr. For introductory 2D examples, the palmerpenguins::penguins dataset provides a more accessible alternative.

Source

https://archive.ics.uci.edu/dataset/107/waveform+database+generator+version+1

Examples

data(data69_1)
dim(data69_1) # 5000 x 22
levels(data69_1$Y) # "1" "2" "3"
head(data69_1[, 1:5])

Description

Shiny app to visually explore and compare classification boundaries for built-in, custom, and tidymodels algorithms in 2D

Usage

explorapp(data = NULL, target_col = NULL, custom_models = list())

Arguments

Value

No return value, called for side effects. Shinyapp is launched.

Examples

if (interactive()) {
  # Launch with default models
  explorapp()

  # Launch with a custom SVM model
  explorapp(custom_models = list(
    "SVM" = list(
      fn = e1071::svm,
      args = list(kernel = "linear")
    )
  ))
}

Description

Export data to CSV

Usage

export_data_csv(data, file)

Arguments

Value

The file path (invisibly).

Description

Export comparison metrics to CSV

Usage

export_metrics_csv(metrics, file)

Arguments

Value

The file path (invisibly).

Description

Export fitted models to RDS

Usage

export_models_rds(models, file)

Arguments

Value

The file path (invisibly).

Description

Export ggplot objects to a multi-page PDF

Usage

export_plots_pdf(plots, file, width = 8, height = 8)

Arguments

Value

The file path (invisibly).

Description

Export ggplot objects to individual PNG files in a directory

Usage

export_plots_png(plots, dir, dpi = 300, width = 8, height = 8)

Arguments

Value

The directory path (invisibly).

Description

Fits a classification model and wraps it in a classbound object, which carries the feature metadata needed by boundary_compute() and plot_boundary().

Usage

fit_model(data, formula, classifier, ...)

## Default S3 method:
fit_model(
  data,
  formula,
  classifier,
  interface = c("formula", "matrix", "custom"),
  fit_args = list(),
  ...
)

## S3 method for class ''function''
fit_model(
  data,
  formula,
  classifier,
  interface = c("formula", "matrix", "custom"),
  fit_args = list(),
  ...
)

## S3 method for class 'character'
fit_model(
  data,
  formula,
  classifier,
  interface = c("formula", "matrix", "custom"),
  fit_args = list(),
  ...
)

Arguments

Details

Interface modes

fit_model() supports three calling conventions via the interface argument:

• "formula" (default): passes formula and data directly to the classifier. Works for the vast majority of R classifiers (e.g., rpart::rpart, e1071::svm, stats::lda).

• "matrix": constructs a predictor matrix x and response vector y from the formula, then calls classifier(x, y, ...). Required for classifiers whose primary interface is matrix-based (e.g., randomForest::randomForest).

• "custom": passes only fit_args to the classifier, giving you full control over the call. Use this for non-standard APIs.

Tidymodels support

If classifier is a parsnip model specification (model_spec), a fitted model_fit, or a tidymodels workflow, fit_model() dispatches to the appropriate method automatically. The interface argument is not needed for these objects.

Preprocessing

fit_model() calls preprocess_data() internally to coerce response labels to a factor, handle missing values, and extract feature metadata. Do not call preprocess_data() manually before calling fit_model(); this will corrupt the stored metadata.

Value

A classbound object (a list of class "classbound") containing:

• ⁠$fit⁠: the raw fitted model object returned by the classifier

• ⁠$metadata⁠: a list with ⁠$features⁠ (names, types, ranges, imputation values) and ⁠$class_levels⁠ (sorted character vector of class labels)

• ⁠$boundary_data⁠: NULL until boundary_compute() is called

See Also

boundary_compute(), predict_model(), classbound()

Examples

library(palmerpenguins)
data(penguins)
peng_data <- na.omit(penguins[, c("species", "bill_length_mm", "bill_depth_mm")])

# Formula interface (most classifiers)
m_rpart <- fit_model(peng_data, species ~ ., rpart::rpart)

# Matrix interface (randomForest)
m_rf <- fit_model(peng_data, species ~ ., randomForest::randomForest,
  interface = "matrix"
)

# Additional fitting arguments via fit_args
m_rpart_cp <- fit_model(peng_data, species ~ ., rpart::rpart,
  fit_args = list(control = rpart::rpart.control(cp = 0.001))
)

Description

Renders a 2D ggplot of a classification decision boundary, optionally overlaying observed training data. Input must be a classbound object that has already been passed through boundary_compute().

Usage

plot_boundary(
  model,
  obs_data = NULL,
  x_col = NULL,
  y_col = NULL,
  true_label = NULL,
  facet_col = NULL,
  type = "2D",
  show_gradient = FALSE,
  agree_color = "#006666",
  disagree_color = "#FF8000",
  obs_alpha = 1,
  obs_size = 2.5,
  render = c("raster", "tile"),
  colors = NULL,
  palette = NULL,
  highlight_outliers = FALSE,
  xlim = NULL,
  ylim = NULL,
  ...
)

Arguments

Details

Probability surface (gradient)

When show_gradient = TRUE, decision regions are shaded by the predicted class probability: deep, saturated regions indicate high model confidence, while faded regions indicate uncertainty near the boundary. Probability shading is only possible when the underlying classifier returns class probabilities. Classifiers that return only class labels (e.g., standard SVMs or PPtree models) produce a flat boundary regardless of show_gradient.

High-dimensional projections and depth fading

When the classbound object contains a projection (from boundary_compute(..., projection = ...)), plot_boundary() automatically forward-projects any obs_data observations onto the 2D plane. It also computes each point's orthogonal distance from the projection plane and maps this distance to opacity: points lying exactly on the plane are fully opaque (alpha = 1.0), while points further away in the original feature space gradually fade toward alpha = 0.2. This depth-fading provides visual cues about how faithfully each point's position is captured by the current projection.

Rendering backend and plotly compatibility

The default render = "raster" uses ggplot2::geom_raster(), which is fast and produces high-quality static output. However, geom_raster() is not supported by plotly::ggplotly() and will produce a blank interactive plot. To convert a boundary plot to an interactive plotly figure, use render = "tile" instead:

p <- plot_boundary(model, render = "tile")
plotly::ggplotly(p)

Colors and palettes

By default, plot_boundary() uses classbound_palette(), a curated 20-color palette with deterministic (alphabetical) class-to-color assignment, ensuring consistent colors across multiple plots. Supply a palette name (e.g., "Dark2") to use an RColorBrewer palette, or supply colors as a named vector for explicit control. If an RColorBrewer palette cannot accommodate the number of classes, it falls back to classbound_palette().

Value

A ggplot2 object.

See Also

boundary_compute(), classbound(), classbound_palette()

Examples

library(palmerpenguins)
data(penguins)
peng_data <- na.omit(penguins[, c("species", "bill_length_mm", "bill_depth_mm")])

m <- fit_model(peng_data, species ~ ., rpart::rpart)
m <- boundary_compute(m, resolution = 50)

# Basic boundary plot with observations
plot_boundary(m,
  obs_data   = peng_data,
  x_col      = "bill_length_mm",
  y_col      = "bill_depth_mm",
  true_label = "species"
)

# Probability gradient (rpart supports probabilities)
plot_boundary(m,
  obs_data      = peng_data,
  x_col         = "bill_length_mm",
  y_col         = "bill_depth_mm",
  true_label    = "species",
  show_gradient = TRUE
)

# Plotly-compatible rendering
p <- plot_boundary(m,
  obs_data   = peng_data,
  x_col      = "bill_length_mm",
  y_col      = "bill_depth_mm",
  true_label = "species",
  render     = "tile"
)
# plotly::ggplotly(p)  # uncomment to convert to interactive

Description

A standard S3 plot method that delegates to plot_boundary().

Usage

## S3 method for class 'classbound'
plot(x, ...)

Arguments

Value

A ggplot2 object.

Description

An S3 plot method that delegates to plot_boundary() for objects that have had boundaries computed via boundary_compute().

Usage

## S3 method for class 'classbound_boundary'
plot(x, ...)

Arguments

Value

A ggplot2 object.

Description

Generates predictions using a unified interface across all classifiers. This function is a compatibility wrapper around the standard predict() method for "classbound" objects.

Usage

predict_model(model, newdata, predict_args = list(), predfun = NULL, ...)

Arguments

Value

A list containing class (a factor of predicted labels) and probs (a probability matrix, or strictly NULL if the classifier lacks probability support).

Examples

library(palmerpenguins)
data(penguins)
peng_data <- na.omit(penguins[, c("species", "bill_length_mm", "bill_depth_mm")])

m_rpart <- fit_model(peng_data, species ~ ., rpart::rpart)
preds <- predict_model(m_rpart, newdata = peng_data[1:5, ])

Description

Generates predictions using a unified interface across all classifiers. Dispatches natively on objects of class "classbound". Attempting to call predict() directly on a "classbound_multi" object will result in an error, as multi-model boundaries are evaluated internally by boundary_compute().

Usage

## S3 method for class 'classbound'
predict(object, newdata, predict_args = list(), predfun = NULL, ...)

## S3 method for class 'classbound_multi'
predict(object, newdata, predict_args = list(), predfun = NULL, ...)

Arguments

Value

A list containing class (a factor of predicted labels) and probs (a probability matrix, or strictly NULL if the classifier lacks probability support). Downstream functions like boundary_compute() are designed to handle probs = NULL gracefully.

Description

Applies standard preprocessing steps to a training dataset: validates structure, coerces character columns to factors, drops unused factor levels, rejects missing and infinite values, and converts response labels to a factor.

Usage

preprocess_data(data, labels = NULL, ...)

Arguments

Details

This function is called automatically by fit_model(). Do not call it manually before fit_model(), because doing so will result in feature metadata being extracted from the pre-processed data rather than the original data, which corrupts the imputation values used by boundary_compute() for 2D slicing.

It is exported for use in custom workflows and testing, but it is not typically needed in the standard fit_model() → boundary_compute() pipeline.

Value

A list with two elements:

• ⁠$data⁠: the preprocessed data frame

• ⁠$labels⁠: the processed factor labels (or NULL if not supplied)

Description

Prints a clean summary of a classbound model object, hiding the internal wrapper structure. For single models, it delegates to the native model's print method. For multi-model objects (classbound_multi), it prints a comparison summary of the included models.

Usage

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

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

Arguments

Value

The object, invisibly.

Description

Generates synthetic classification data by drawing independent multivariate normal samples for each class. Useful when you want explicit control over each class's mean and covariance structure.

Usage

simu_n(
  means,
  covs,
  ns,
  class_names = NULL,
  seed = NULL,
  noise_ratio = 0,
  test_ratio = 0
)

Arguments

Details

Test data

When test_ratio > 0, an additional independent test dataset is generated by drawing fresh samples of size round(ns * test_ratio) for each class using the same means and covs. This is not a split of the training data. The training set has sum(ns) observations; the test set has sum(round(ns * test_ratio)) independently generated observations.

Value

If test_ratio == 0 (default): a data frame with a Sim class column and feature columns (X1, X2, ...). If test_ratio > 0: a list with ⁠$train⁠ and ⁠$test⁠ data frames.

See Also

simulate_mixsim()

Examples

means <- list(c(0, 0), c(3, 3), c(0, 5))
covs <- list(diag(2), diag(2), diag(2))
ns <- c(60, 60, 60)

train_df <- simu_n(means, covs, ns, seed = 1)
head(train_df)

# With independent test data
sim <- simu_n(means, covs, ns, seed = 1, test_ratio = 0.3)
nrow(sim$train) # 180
nrow(sim$test) # 54 (independently generated, not split from train)

Description

Generates synthetic classification data using Gaussian mixture models constructed by the MixSim package. Useful for creating controlled datasets to explore decision boundary behavior when no real dataset is available.

Usage

simulate_mixsim(
  n,
  K,
  p,
  MaxOmega,
  class_names = NULL,
  seed = NULL,
  noise_ratio = 0,
  test_ratio = 0
)

Arguments

Details

Class distributions are randomly generated subject to the MaxOmega overlap constraint. The simulation is fully reproducible when seed is supplied.

Test data

When test_ratio > 0, an additional independent dataset is generated using the same mixture parameters but a fresh random draw. This is not a split of the training data: the training set has n observations and the test set has round(n * test_ratio) independently generated observations. The two sets are statistically independent, so the test set is a fair evaluation sample.

Value

If test_ratio == 0 (default): a data frame with a Sim class column and p feature columns (X1, X2, ...). If test_ratio > 0: a list with ⁠$train⁠ and ⁠$test⁠ data frames.

See Also

simu_n()

Examples

# Generate a 3-class, 2-dimensional training dataset
train_df <- simulate_mixsim(n = 200, K = 3, p = 2, MaxOmega = 0.05, seed = 42)
head(train_df)

# Generate training and independent test data
sim <- simulate_mixsim(
  n = 200, K = 3, p = 2, MaxOmega = 0.05,
  seed = 42, test_ratio = 0.3
)
nrow(sim$train) # 200
nrow(sim$test) # 60 (independently generated, not split from train)

Description

For single models, delegates the summary function directly to the native model wrapped inside the classbound object. For multi-model objects (classbound_multi), it returns a summary of the contained models.

Usage

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

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

Arguments

Value

The summary of the native model.