ixsurface: Interactive 3D Surface Plots for Multi-Factor Interaction Visualization

Description

Visualize interactions between multiple experimental factors using interactive 3D surface plots powered by 'plotly'. Instead of examining combinatorial pairwise interaction plots, map factor combinations to response surfaces and use surface crossings as geometric indicators of interaction effects. Supports continuous, categorical, and mixed factor designs with automatic binning for continuous conditioning variables.

Author(s)

Maintainer: Chris Brantner cjbrantn@gmail.com

See Also

Useful links:

• https://github.com/cjbrant/ixsurface

• Report bugs at https://github.com/cjbrant/ixsurface/issues

Assign observations to the nearest surface group

Description

For color-coding observed data by facet_by level. Handles both categorical and binned continuous facet_by variables.

Usage

assign_obs_to_surface(obs, by_vars, by_combos, binned_by)

Arguments

Value

Integer vector of surface indices (1-indexed).

Bin a continuous variable into discrete levels

Description

Used when a continuous variable appears in facet_by to produce a manageable number of surfaces.

Usage

bin_continuous(x, n_bins = 3, method = c("quantile", "equal", "pretty"))

Arguments

Value

A factor with descriptive level labels.

Examples

x = rnorm(100, mean = 50, sd = 15)
bin_continuous(x, n_bins = 3, method = "quantile")
bin_continuous(x, n_bins = 4, method = "equal")

Compute approximate surface crossing points

Description

For each pair of surfaces, finds grid cells where the z-difference changes sign, indicating the surfaces cross in that region.

Usage

compute_crossings(
  z_matrices,
  x_vals,
  y_vals,
  by_combos,
  by_vars,
  binned_by = list(),
  tolerance = NULL
)

Arguments

Value

A data.frame with columns cx, cy, cz, pair_label.

Detect whether a variable in a model is continuous or categorical

Description

Detect whether a variable in a model is continuous or categorical

Usage

detect_factor_type(model, varname)

Arguments

Value

Character: "continuous" or "categorical".

Find Crossing Regions Between Interaction Surfaces

Description

Identifies where predicted response surfaces cross for different levels of conditioning factors. Returns a data frame of approximate crossing locations.

Usage

find_crossings(
  model,
  x,
  y,
  facet_by,
  n = 50,
  n_bins = 3,
  bin_method = "quantile",
  tolerance = NULL
)

Arguments

Value

A data.frame with columns:

cx

x-coordinate of crossing

cy

y-coordinate of crossing

cz

predicted response at crossing (average of both surfaces)

pair_label

which surface pair crosses

Examples

dat = sim_factorial(design = "mixed", seed = 42)
fit = lm(y ~ temp * pressure * catalyst, data = dat)
crossings = find_crossings(fit, "temp", "pressure", "catalyst")
head(crossings)

Interactive 3D Surface Plot for Multi-Factor Interactions

Description

Generates an interactive plotly surface plot from a fitted model. Two focal variables are mapped to the x and y aesthetics, with the predicted response on z. Additional conditioning factors (facet_by) generate separate surfaces — where surfaces cross indicates interaction effects.

Usage

interaction_surface(
  model,
  x,
  y,
  facet_by = NULL,
  n = 50,
  n_bins = 3,
  bin_method = "quantile",
  alpha = 0.6,
  show_points = FALSE,
  show_crossings = TRUE,
  show_contour = FALSE,
  contour_z = NULL,
  labs = NULL,
  title = NULL,
  theme = "default",
  ...
)

Arguments

Details

Geometric interpretation:

• Parallel surfaces \to no interaction between facet_by and the focal variables

• Crossing surfaces \to interaction present

• Twisted/warped surfaces \to higher-order or nonlinear interaction

For categorical focal variables, the surface is constructed over an integer grid with axis tick labels showing level names.

Non-focal, non-facet_by variables are held at their median (continuous) or mode (categorical).

For GLM family models, predictions are returned on the response scale via predict(..., type = "response").

Value

A plotly htmlwidget object.

Examples

dat = sim_factorial(design = "mixed", seed = 42)
fit = lm(y ~ temp * pressure * catalyst, data = dat)
interaction_surface(fit, x = "temp", y = "pressure", facet_by = "catalyst")

# with GLM
dat$success = rbinom(nrow(dat), 1, plogis(scale(dat$y)))
gfit = glm(success ~ temp * pressure * catalyst, data = dat, family = binomial)
interaction_surface(gfit, x = "temp", y = "pressure", facet_by = "catalyst")

Generate All Pairwise Interaction Surface Plots

Description

For a model with multiple factors, generates interaction surface plots for every pair of focal variables, using remaining variables as conditioning factors (facet_by). Useful for exploratory analysis.

Usage

interaction_surface_grid(
  model,
  factors = NULL,
  facet_max = 2,
  n = 30,
  n_bins = 3,
  alpha = 0.6,
  ...
)

Arguments

Value

A named list of plotly objects. Names use pattern "x__y".

Examples

dat = sim_factorial(design = "mixed", seed = 42)
fit = lm(y ~ temp * pressure * catalyst, data = dat)
plots = interaction_surface_grid(fit)
plots$temp__pressure

Lighten a hex color

Description

Lighten a hex color

Usage

lighten_color(hex_color, amount = 0.3)

Arguments

Value

Character hex color.

Generate a label for a facet_by combination

Description

Generate a label for a facet_by combination

Usage

make_by_label(row, by_vars, binned_by = list())

Arguments

Value

A character label.

Build a prediction grid over two focal variables

Description

For continuous variables, generates a regular sequence across the observed range. For categorical/factor variables, uses all observed levels. Continuous facet_by variables are binned, and predictions use bin midpoints.

Usage

make_prediction_grid(
  model,
  x,
  y,
  facet_by = NULL,
  n = 50,
  n_bins = 3,
  bin_method = "quantile"
)

Arguments

Value

A list with components:

grid

data.frame suitable for predict()

binned_by

named list of bin info for continuous facet_by variables

Examples

dat = sim_factorial(design = "mixed", seed = 42)
fit = lm(y ~ temp * pressure * catalyst, data = dat)
result = make_prediction_grid(fit, x = "temp", y = "pressure",
                              facet_by = "catalyst", n = 10)
str(result$grid)

Plot Crossing Regions as a Standalone 3D Scatter

Description

Visualizes only the crossing points between interaction surfaces as an interactive 3D scatter plot, color-coded by surface pair. This isolates where interaction effects are strongest, without the surfaces themselves.

Usage

plot_crossings(
  model,
  x,
  y,
  facet_by,
  n = 50,
  n_bins = 3,
  bin_method = "quantile",
  tolerance = NULL,
  labs = NULL,
  title = NULL,
  marker_size = 3,
  marker_opacity = 0.7
)

Arguments

Value

A plotly htmlwidget object. If no crossings are found, returns an empty plot with a "No crossings detected" annotation.

Examples

dat = sim_factorial(design = "mixed", seed = 42)
fit = lm(y ~ temp * pressure * catalyst, data = dat)
plot_crossings(fit, "temp", "pressure", "catalyst")

# with custom labels
plot_crossings(fit, "temp", "pressure", "catalyst",
               labs = list(x = "Temp (C)", y = "Press (psi)", z = "Yield"))

Safe prediction wrapper with GLM/GAM support

Description

Dispatches predict() with type = "response" for GLMs and GAMs to return predictions on the response scale (e.g., probabilities for logistic regression). Falls back to plain predict() for lm and others.

Usage

safe_predict(model, newdata)

Arguments

Value

Numeric vector of predictions.

Simulate a Multi-Factor Experimental Dataset

Description

Generates synthetic data from a factorial design with known interaction structure. Useful for demonstrating and testing interaction_surface.

Usage

sim_factorial(
  n = 200,
  design = c("mixed", "continuous", "categorical"),
  noise = 0.5,
  seed = NULL
)

Arguments

Details

The data generating process includes main effects for all factors, two-way interactions between the first two factors, and a three-way interaction (weaker) involving all factors. This makes it straightforward to verify that interaction_surface correctly detects the embedded structure.

Value

A data.frame with factor columns and a response column y.

Examples

dat = sim_factorial(design = "mixed", seed = 42)
head(dat)

Get a qualitative color palette for surfaces

Description

Get a qualitative color palette for surfaces

Usage

surface_palette(n)

Arguments

Value

Character vector of hex colors.