curves

curves is an experimental R package for plotting response curves from fitted models with ggplot2. The package is intentionally small and model-agnostic: supply a fitted model, predictor data, and, when needed, a custom prediction function.

The figure above shows partial dependence curves from the included species distribution vignette.

Current package scope

The current API is centred around four exported functions:

• univariate() for one-predictor response curves with method = "profile", "pdp", "ice", "ice+pdp", or "ale".
• bivariate() for two-predictor profile, PDP, or ALE surfaces as static heatmaps, filled contours, or interactive 3D plotly surfaces.
• multimodel() for ensemble profile, PDP, or ALE curves across multiple fitted models, with optional interval ribbons and member-model overlays.
• mapcurve() for Shiny-based exploration that links a prediction raster to response curves at clicked map cells.

A few practical details are worth calling out:

• Predictor inputs can be ordinary data frames or terra::SpatRaster objects.
• Numeric and factor predictors are supported. For method = "ale", factor predictors or predictor pairs are currently ignored with a warning and only numeric effects are plotted.
• If predict() returns multiple columns, response can be used to choose the column to plot.
• Static plots return ggplot2 objects, so they can be styled or combined in downstream workflows.

In short, profile curves use one reference row, PDP averages predictions over sampled rows, ICE keeps those row-level curves visible, and ALE accumulates local prediction differences within the observed predictor distribution.

Installation

curves is not on CRAN. Install the development version from GitHub:

install.packages("remotes")
remotes::install_github("rvalavi/curves")

Optional packages:

• terra for raster-backed predictor inputs.
• plotly for interactive 3D surfaces.
• mgcv for the GAM ensemble example below.
• randomForest and disdat for the species distribution vignette.

Quick start

library(curves)

model <- lm(
  Sepal.Length ~ Sepal.Width + Petal.Length + Petal.Width,
  data = iris
)

predictors <- iris[, c("Sepal.Width", "Petal.Length", "Petal.Width")]

# Single-profile response curves
univariate(model, predictors)

# Partial dependence curves
univariate(
  model,
  predictors,
  method = "pdp",
  n = 50,
  background_n = 200
)

# Accumulated local effects curves
univariate(model, predictors, method = "ale", n = 40)

# Bivariate response surface
bivariate(
  model,
  predictors,
  pairs = c("Sepal.Width", "Petal.Length"),
  method = "pdp",
  background_n = 50,
  rug = TRUE,
  plot_type = "heatmap"
)

For ensemble modelling, pass a list of fitted models to multimodel(). The ensemble members should be fitted to the same response and compatible predictors, and their predictions should be on the same response scale. If a set of models shares the same prediction interface, pass non-default prediction arguments through .... For mixed model types, supply fun as a list of wrappers, one per model. If a shared prediction function returns multiple prediction columns, either set response or provide a small wrapper through fun. Use agg, weights, interval, and show_models to control how the ensemble curves are combined and displayed.

models <- list(
  lm(Sepal.Length ~ Sepal.Width + Petal.Length, data = iris),
  mgcv::gam(Sepal.Length ~ s(Sepal.Width) + s(Petal.Length), data = iris)
)

multimodel(
  models,
  predictors[, c("Sepal.Width", "Petal.Length")],
  method = "pdp",
  background_n = 200,
  show_models = TRUE
)

Species distribution vignette

The package includes a fuller species distribution vignette built around a down-sampled random forest classifier. It demonstrates:

• class-probability plots with response = "1"
• profile, PDP, ICE, and ALE workflows through univariate()
• bivariate profile, PDP, and ALE surfaces with an optional 3D surface

You can open it after installation with:

vignette("random-forest-species-distribution", package = "curves")

The bivariate figure shows a centred ALE surface for two predictors from the same random forest example.

Interactive map-linked curves

mapcurve() opens a Shiny explorer that links a predicted map to fitted response curves. Clicking a raster cell marks that site's predictor values on the curve panels, which helps compare local conditions with profile, PDP, ICE, or ALE summaries.