Plot the result of a call to smooth_estimates() — draw.smooth

Plot the result of a call to smooth_estimates()

Usage

# S3 method for class 'smooth_estimates'
draw(
  object,
  constant = NULL,
  fun = NULL,
  contour = TRUE,
  grouped_by = deprecated(),
  contour_col = "black",
  n_contour = NULL,
  ci_alpha = 0.2,
  ci_col = "black",
  smooth_col = "black",
  resid_col = "steelblue3",
  decrease_col = "#56B4E9",
  increase_col = "#E69F00",
  change_lwd = 1.75,
  partial_match = FALSE,
  discrete_colour = NULL,
  discrete_fill = NULL,
  continuous_colour = NULL,
  continuous_fill = NULL,
  angle = NULL,
  ylim = NULL,
  crs = NULL,
  default_crs = NULL,
  lims_method = "geometry_bbox",
  caption = TRUE,
  surface = c("raster", "tile", "3d"),
  surface_3d = list(),
  ci_3d = FALSE,
  ci_3d_alpha = 0.15,
  ci_3d_col = "grey60",
  back_transform = FALSE,
  re_levels = NULL,
  mrf_plot = c("effects", "qq"),
  interval = NULL,
  ...,
  variables = NULL,
  cyclic = c("cartesian", "polar"),
  polar_args = list(),
  grouped = c("sz", "fs"),
  show_ci = c("factor-by", "sz")
)

Arguments

object: a fitted GAM, the result of a call to mgcv::gam().
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. For simultaneous bands it must be monotone over the entire band; endpoint transformation alone does not preserve non-monotone band coverage. Function fun will be applied after adding any constant, if provided.
contour: logical; should contours be draw on the plot using ggplot2::geom_contour().
grouped_by: Deprecated; use grouped. Explicit TRUE adds "factor-by" to grouped; FALSE removes it, retaining the other types.
contour_col: Deprecated; use gratia_theme_get() theme settings instead. 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().
ci_alpha: Deprecated; use gratia_theme_get() theme settings instead. Numeric; alpha transparency for confidence or simultaneous interval.
ci_col: Deprecated; use gratia_theme_get() theme settings instead. Colour specification for the confidence/credible intervals band. Affects the fill of the interval.
smooth_col: Deprecated; use gratia_theme_get() theme settings instead. Colour specification for the smooth line.
resid_col: Deprecated; use gratia_theme_get() theme settings instead. Colour specification for the partial residuals.
decrease_col, increase_col: Deprecated; use gratia_theme_get() theme settings instead. Colour specifications to use for indicating periods of change. col_change is used when change_type = "change", while col_decrease and col_increase are used when `change_type = "sizer"“.
change_lwd: Deprecated; use gratia_theme_get() theme settings instead. Numeric; the value to set the linewidth to in ggplot2::geom_line(), used to represent the periods of change.
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: a suitable colour scale to be used when plotting discrete variables.
discrete_fill: a suitable fill scale to be used when plotting discrete variables.
continuous_colour: a suitable colour scale to be used when plotting continuous variables.
continuous_fill: a suitable fill scale to be used when plotting continuous variables.
angle: numeric; the angle at which the x axis tick labels are to be drawn passed to the angle argument of ggplot2::guide_axis().
ylim: numeric; vector of y axis limits to use all all panels drawn.
crs: the coordinate reference system (CRS) to use for the plot. All data will be projected into this CRS. See ggplot2::coord_sf() for details.
default_crs: the coordinate reference system (CRS) to use for non-sf layers added to spherical plots. The default, NULL, uses 4326 (WGS84). Internally generated surface cells, contours and observation points have their own geographic CRS, with longitude on the horizontal axis and latitude on the vertical axis. See ggplot2::coord_sf() for more details.
lims_method: character; affects how spherical plot axis limits are determined. The default, "geometry_bbox", uses the rendered geometry. Passed to ggplot2::coord_sf(). Spherical surfaces use explicit geographic cells with valid polar and date-line boundaries. Orthographic plots clip cells, contours and observation points to the visible hemisphere before projection. Explicit prediction data on a rectilinear grid retain their actual spacing; scattered or singleton coordinates are drawn as points, with a message, because they do not define surface cells. Incomplete observation rug coordinates are omitted. Grouped factor-by spherical surfaces use separate facets for each factor level.
caption: logical; show the smooth type in the caption of each plot?
surface: character; one of "raster" (the default), "tile", or "3d". Raster surfaces keep large PDF plots compact; tiles are borderless vector rectangles. Three-dimensional surfaces use the optional ggcube package, with the displayed partial effect as height and fill. Numeric smooth and parametric surfaces, including conditioning facets and soap films, are supported. Curves and factor estimates keep their usual display; spherical smooths retain their geographic rendering. Covariate scale changes that produce irregular spacing use rectangles bounded by adjacent coordinate midpoints for flat surfaces.
surface_3d: named list of view options passed to ggcube::coord_3d(), for example list(yaw = 45, persp = FALSE). The default list() uses the default view with ggcube::light(backface_scale = 1), preserving equal horizontal units for isotropic smooths. Supply light = ggcube::light(...) in this list to override lighting; ggcube::light(method = "none") disables it. An explicitly supplied light replaces the entire default light. Only the coordinate system is used; ggcube's theme settings are not applied. These options affect all 3D panels in a call. For different views per term, modify individual plots returned by assemble(). The dist entry here controls perspective; the top-level dist argument controls masking.
ci_3d: logical; add lower and upper interval surfaces to numeric smooth and parametric effect panels when surface = "3d"? Defaults to FALSE. Applies across supported model classes and conditioning facets. Other panel types, including standard errors, retain their usual display. Smooth bounds follow interval; parametric bounds remain pointwise.
ci_3d_alpha: Deprecated; use gratia_theme_get() theme settings instead. Numeric between 0 and 1; opacity of both interval surfaces, independent of ci_alpha. Defaults to 0.15.
ci_3d_col: Deprecated; use gratia_theme_get() theme settings instead. One R colour; fill of both interval surfaces, independent of ci_col and the estimate's continuous fill scale. Defaults to "grey60".
back_transform: logical; plot covariates on their original scale? Defaults to FALSE, using model coordinates such as log(x) for a term containing log(x). With TRUE, recover the raw covariates, generate a grid on their original scale and evaluate the model expressions forwards. Applies to axes, rugs, partial-residual locations and conditioning facets, including tensor products and parametric interactions. Each smooth axis must depend on one distinct original model covariate. Functions such as foo(x) are supported when their raw inputs and functions can be recovered; no inverse function is needed. Missing raw data or unavailable functions produce an error; supply data or envir as appropriate. With supplied prediction data, unavailable raw fitting observations omit rugs and partial residuals; prediction rows are never used as observations. For precomputed smooth estimates, prepare raw grids with smooth_estimates(model, back_transform = TRUE) before drawing with back_transform = TRUE. Raw inputs supplied through data also retain their coordinates. Transformed-only estimates cannot be relabelled on the raw scale, including grids carrying typical values from include_all = TRUE. Transformed soap-film boundaries lack retained raw coordinates and must be drawn with back_transform = FALSE. Parametric estimates retain both scales; multi-column basis expansions retain raw axes on either setting. Does not transform estimated effects or their intervals; use fun for that.
re_levels: named list of factor level labels to retain in tensor products with random-effect margins, for example list(species = c("a", "b")). Fitted factor order and ordered status are retained.
mrf_plot: character; display Markov random field smooths as area-labelled estimates and intervals ("effects", the default), or a descriptive Gaussian quantile plot ("qq"). MRF effects are correlated and need not have equal marginal variances; the QQ display is not a test of independent normal effects. Specialist maps and graph plots are outside the scope of this display.
interval: character or NULL; the default draws stored interval bounds unchanged, adding pointwise bounds if absent. An explicit choice validates stored interval metadata; "credible" aliases "confidence". Simultaneous bands must first be computed from the fitted model by smooth_estimates(). Method and uncertainty controls such as interval_method, shape_source, frequentist, and unconditional also require the fitted model; they cannot change intervals when drawing saved estimates.
...: additional arguments passed to patchwork::wrap_plots().
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.
cyclic: character; use Cartesian coordinates ("cartesian", the default) or polar coordinates ("polar") for one-dimensional cyclic smooths. Other smooths and parametric terms keep their usual displays.
polar_args: named list of options passed to ggplot2::coord_radial(). Accepts start, reverse, inner.radius, r.axis.inside, rotate.angle and clip. The radial axis is inside the circle by default (r.axis.inside = TRUE); supplied values override this default. Other options use their ggplot2 defaults. Requires cyclic = "polar" when nonempty. The angular variable, fitted cycle boundaries, full-circle extent and angular expansion are set by gratia.
grouped: character or FALSE; factor smooth types whose curves share a panel. Choose any of "factor-by", "sz", and "fs", or FALSE to separate all their curves. The default, c("sz", "fs"), overlays sz and fs curves and separates factor-by curves. "factor-by" includes ordered factors. In reference-plus-deviation models the reference smooth remains separate; only fitted nonreference deviations are grouped. For sz terms with several factors, separate plots show each evaluated combination of levels. Applies to curves with one continuous covariate; existing surface displays are unchanged. Separate curves use the usual univariate styling: a black line and a translucent black interval by default, with colours and opacity controlled by the smooth theme settings.
show_ci: character or FALSE; factor smooth types whose curves show intervals. Choose any of "factor-by", "sz", and "fs", or FALSE to hide all their ribbons. The default, c("factor-by", "sz"), retains existing interval visibility; including "fs" enables its intervals. Controls display only, independently of interval and grouped. Ordinary smooths and parametric effects retain their intervals.

Details

cyclic = "polar" uses fitted cycle boundaries stored in the cyclic_info attribute. Evaluation points are unchanged: estimates covering only part of a cycle leave a gap. To draw a complete cycle, supply both fitted boundary values when computing estimates, or use draw(model, cyclic = "polar") to generate the full-cycle grid. Recompute older saved estimates with smooth_estimates() if their fitted cycle boundaries are unavailable. See draw.gam() for supported smooths and coordinate options.

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.

Examples

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

# Evaluate one smooth and plot its estimates and interval
sm <- smooth_estimates(m, select = "s(x2)")
draw(sm)