Plot basis functions — draw.basis • gratia

Plots basis functions using ggplot2

Usage

# S3 method for class 'basis'
draw(
  object,
  legend = FALSE,
  labeller = NULL,
  ylab = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  ncol = NULL,
  nrow = NULL,
  angle = NULL,
  guides = "keep",
  contour = TRUE,
  n_contour = 10,
  contour_col = "black",
  ...,
  variables = NULL
)

Arguments

object: an object, the result of a call to basis().
legend: logical; should a legend by drawn to indicate basis functions?
labeller: a labeller function with which to label facets. The default is to use ggplot2::label_both().
ylab: character or expression; the label for the y axis. If not supplied, a suitable label will be generated from object.
title: character or expression; the title for the plot. See ggplot2::labs().
subtitle: character or expression; the subtitle for the plot. See ggplot2::labs().
caption: character or expression; the plot caption. See ggplot2::labs().
ncol, nrow: numeric; the numbers of rows and columns over which to spread the plots
angle: numeric; the angle at which the x axis tick labels are to be drawn passed to the angle argument of ggplot2::guide_axis().
guides: character; one of "keep" (the default), "collect", or "auto". Passed to patchwork::plot_layout()
contour: logical; should contours be draw on the plot using ggplot2::geom_contour().
n_contour: numeric; the number of contour bins. Will result in n_contour - 1 contour lines being drawn. See ggplot2::geom_contour().
contour_col: Deprecated; use gratia_theme_get() theme settings instead. Colour specification for contour lines.
...: arguments passed to other methods. Not used by this method.
variables: Character vector giving every covariate of the selected smooths exactly once, in plotting order: x, y, then the conditioning covariate for 3D smooths, or facet rows and columns for 4D smooths. When supplied, selected smooths must use the same covariates. Use fitted coordinate names, such as "log(x)" for a transformed covariate. The default, NULL, favours a two-variable tensor margin for x and y, otherwise retaining fitted order. Grid resolution follows this order. Supplied data are evaluated unchanged. Drawing saved estimates can change the order but uses only points already evaluated; evaluate again to change grid resolution or conditioning values. Continuous covariates must precede factors. Spherical smooths retain their latitude/longitude convention and do not support reordering.

Value

A patchwork object.

Details

For smooths of three or four covariates, each basis function has its own plot. The first two covariates define the surface axes. Three-covariate smooths have wrapped facets for the third covariate; four-covariate smooths have the third covariate in rows and the fourth in columns. ncol and nrow control the outer arrangement of plots. Fill scales share a range within each smooth. Use variables in basis() to choose the axes before grid generation, or here to rearrange existing evaluations without resampling. Surface plots include contour lines by default, matching draw.gam(). Use contour = FALSE to draw surfaces without contour lines.

Factor-by bases from smooth specifications are drawn once for the whole factor-by set, using evaluations from all available levels. For fitted models, basis(model) returns coefficient-weighted contributions, which remain separate for each level. Use basis(model, unweighted = TRUE) to draw the shared basis once. Subsetting the basis before drawing restricts the plot to the retained evaluations and basis functions.

Label layout

Pass label_control = draw_label_control(...) to draw() to wrap discrete axis labels and legend text, stagger discrete tick labels, or adjust legend and colour-bar layout. Settings apply to each panel, including unwrapped plot lists. See draw_label_control() for the available settings.

Author

Gavin L. Simpson

Examples

load_mgcv()
# Simulate an additive Gaussian response and fit a GAM
df <- data_sim("eg1", n = 200, seed = 42)
m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df, method = "REML")

# Plot the coefficient-weighted basis functions for one smooth
bf <- basis(m, select = "s(x2)")
draw(bf)