gratia: draw.gam – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

draw.gam

Plot estimated smooths from a fitted GAM

Description

Plots estimated smooths from a fitted GAM model in a similar way to mgcv::plot.gam() but instead of using base graphics, ggplot2::ggplot() is used instead.

Usage

## S3 method for class 'gam'
draw(
  object,
  parametric = NULL,
  select = NULL,
  residuals = FALSE,
  scales = c("free", "fixed"),
  ci_level = 0.95,
  n = 100,
  unconditional = FALSE,
  overall_uncertainty = TRUE,
  constant = NULL,
  fun = NULL,
  dist = 0.1,
  rug = TRUE,
  contour = TRUE,
  contour_col = "black",
  n_contour = NULL,
  partial_match = FALSE,
  discrete_colour = NULL,
  continuous_colour = NULL,
  continuous_fill = NULL,
  ncol = NULL,
  nrow = NULL,
  guides = "keep",
  ...
)

Arguments

`object`	a fitted GAM, the result of a call to `mgcv::gam()`.
`parametric`	logical; plot parametric terms also? Default is `TRUE`, only if `select` is `NULL`. If `select` is used, `parametric` is set to `FALSE` unless the user specifically sets `parametric = TRUE`.
`select`	character, logical, or numeric; which smooths to plot. If `NULL`, the default, then all model smooths are drawn. Numeric `select` indexes the smooths in the order they are specified in the formula and stored in `object`. Character `select` matches the labels for smooths as shown for example in the output from `summary(object)`. Logical `select` operates as per numeric `select` in the order that smooths are stored.
`residuals`	logical; should partial residuals for a smooth be drawn? Ignored for anything but a simple univariate smooth.
`scales`	character; should all univariate smooths be plotted with the same y-axis scale? The default, `scales = "fixed"`, ensures this is done. If `scales = "free"` each univariate smooth has its own y-axis scale. Currently does not affect the y-axis scale of plots of the parametric terms.
`ci_level`	numeric between 0 and 1; the coverage of credible interval.
`n`	numeric; the number of points over the range of the covariate at which to evaluate the smooth.
`unconditional`	logical; should confidence intervals include the uncertainty due to smoothness selection? If `TRUE`, the corrected Bayesian covariance matrix will be used.
`overall_uncertainty`	logical; should the uncertainty in the model constant term be included in the standard error of the evaluate values of the smooth?
`constant`	numeric; a constant to add to the estimated values of the smooth. `constant`, if supplied, will be added to the estimated value before the confidence band is computed.
`fun`	function; a function that will be applied to the estimated values and confidence interval before plotting. Can be a function or the name of a function. Function `fun` will be applied after adding any `constant`, if provided.
`dist`	numeric; if greater than 0, this is used to determine when a location is too far from data to be plotted when plotting 2-D smooths. The data are scaled into the unit square before deciding what to exclude, and `dist` is a distance within the unit square. See `mgcv::exclude.too.far()` for further details.
`rug`	logical; draw a rug plot at the botom of each plot?
`contour`	logical; should contours be draw on the plot using `ggplot2::geom_contour()`.
`contour_col`	colour specification for contour lines.
`n_contour`	numeric; the number of contour bins. Will result in `n_contour - 1` contour lines being drawn. See `ggplot2::geom_contour()`.
`partial_match`	logical; should smooths be selected by partial matches with `select`? If `TRUE`, `select` can only be a single string to match against.
`discrete_colour, continuous_colour, continuous_fill`	suitable scales for the types of data.
`ncol, nrow`	numeric; the numbers of rows and columns over which to spread the plots
`guides`	character; one of `"keep"` (the default), `"collect"`, or `"auto"`. Passed to `patchwork::plot_layout()`
`...`	additional arguments passed to `patchwork::wrap_plots()`.

Value

The object returned is created by patchwork::wrap_plots().

Note

Internally, plots of each smooth are created using ggplot2::ggplot() and composed into a single plot using patchwork::wrap_plots(). As a result, it is not possible to use + to add to the plots in the way one might typically work with ggplot() plots.

Author(s)

Gavin L. Simpson

Examples

load_mgcv()


dat <- gamSim(1, n = 400, dist = "normal", scale = 2)
m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = "REML")

draw(m1)

## can add partial residuals
draw(m1, residuals = TRUE)


dat <- gamSim(2, n = 1000, dist = "normal", scale = 1)
m2 <- gam(y ~ s(x, z, k = 40), data = dat$data, method = "REML")
draw(m2, contour = FALSE)

## change the number of contours drawn and the fill scale used for
## the surface
draw(m2, n_contour = 5,
     continuous_fill = ggplot2::scale_fill_distiller(palette = "Spectral",
                                                     type = "div"))

gratia

Graceful 'ggplot'-Based Graphics and Other Functions for GAMs Fitted Using 'mgcv'

v0.6.0

MIT + file LICENSE

Authors

Gavin L. Simpson [aut, cre] (<https://orcid.org/0000-0002-9084-8413>), Henrik Singmann [ctb] (<https://orcid.org/0000-0002-4842-3657>)

Initial release

2021-04-17