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.
# S3 method for gam
draw(
object,
data = NULL,
select = NULL,
parametric = FALSE,
terms = NULL,
residuals = FALSE,
scales = c("free", "fixed"),
ci_level = 0.95,
n = 100,
n_3d = 16,
n_4d = 4,
unconditional = FALSE,
overall_uncertainty = TRUE,
constant = NULL,
fun = NULL,
dist = 0.1,
rug = TRUE,
contour = TRUE,
grouped_by = FALSE,
ci_alpha = 0.2,
ci_col = "black",
smooth_col = "black",
resid_col = "steelblue3",
contour_col = "black",
n_contour = NULL,
partial_match = FALSE,
discrete_colour = NULL,
discrete_fill = NULL,
continuous_colour = NULL,
continuous_fill = NULL,
position = "identity",
angle = NULL,
ncol = NULL,
nrow = NULL,
guides = "keep",
widths = NULL,
heights = NULL,
crs = NULL,
default_crs = NULL,
lims_method = "cross",
wrap = TRUE,
envir = environment(formula(object)),
...
)The object returned is created by patchwork::wrap_plots().
a fitted GAM, the result of a call to mgcv::gam().
a optional data frame that may or may not be used? FIXME!
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.
logical; plot parametric terms also? Note that select is
used for selecting which smooths to plot. The terms argument is used to
select which parametric effects are plotted. The default, as with
mgcv::plot.gam(), is to not draw parametric effects.
character; which model parametric terms should be drawn? The
Default of NULL will plot all parametric terms that can be drawn.
logical; should partial residuals for a smooth be drawn? Ignored for anything but a simple univariate smooth.
character; should all univariate smooths be plotted with the
same y-axis scale? If scales = "free", the default, each univariate
smooth has its own y-axis scale. If scales = "fixed", a common y axis
scale is used for all univariate smooths.
Currently does not affect the y-axis scale of plots of the parametric terms.
numeric between 0 and 1; the coverage of credible interval.
numeric; the number of points over the range of the covariate at which to evaluate the smooth.
numeric; the number of new observations to generate for the third dimension of a 3D smooth.
numeric; the number of new observations to generate for the
dimensions higher than 2 (!) of a kD smooth (k >= 4). For example, if
the smooth is a 4D smooth, each of dimensions 3 and 4 will get n_4d
new observations.
logical; should confidence intervals include the
uncertainty due to smoothness selection? If TRUE, the corrected Bayesian
covariance matrix will be used.
logical; should the uncertainty in the model constant term be included in the standard error of the evaluate values of the smooth?
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.
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.
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.
logical; draw a rug plot at the bottom of each plot for 1-D smooths or plot locations of data for higher dimensions.
logical; should contours be draw on the plot using
ggplot2::geom_contour().
logical; should factor by smooths be drawn as one panel
per level of the factor (FALSE, the default), or should the individual
smooths be combined into a single panel containing all levels (TRUE)?
numeric; alpha transparency for confidence or simultaneous interval.
colour specification for the confidence/credible intervals band. Affects the fill of the interval.
colour specification for the smooth line.
colour specification for the partial residuals.
colour specification for contour lines.
numeric; the number of contour bins. Will result in
n_contour - 1 contour lines being drawn. See ggplot2::geom_contour().
logical; should smooths be selected by partial matches
with select? If TRUE, select can only be a single string to match
against.
a suitable colour scale to be used when plotting discrete variables.
a suitable fill scale to be used when plotting discrete variables.
a suitable colour scale to be used when plotting continuous variables.
a suitable fill scale to be used when plotting continuous variables.
Position adjustment, either as a string, or the result of a call to a position adjustment function.
numeric; the angle at which the x axis tick labels are to be
drawn passed to the angle argument of ggplot2::guide_axis().
numeric; the numbers of rows and columns over which to spread the plots
character; one of "keep" (the default), "collect", or
"auto". Passed to patchwork::plot_layout()
The relative widths and heights of each column and
row in the grid. Will get repeated to match the dimensions of the grid. If
there is more than 1 plot and widths = NULL, the value of widths will
be set internally to widths = 1 to accommodate plots of smooths that
use a fixed aspect ratio.
the coordinate reference system (CRS) to use for the plot. All
data will be projected into this CRS. See ggplot2::coord_sf() for
details.
the coordinate reference system (CRS) to use for the
non-sf layers in the plot. If left at the default NULL, the CRS used is
4326 (WGS84), which is appropriate for spline-on-the-sphere smooths, which
are parameterized in terms of latitude and longitude as coordinates. See
ggplot2::coord_sf() for more details.
character; affects how the axis limits are determined. See
ggplot2::coord_sf(). Be careful; in testing of some examples, changing
this to "orthogonal" for example with the chlorophyll-a example from
Simon Wood's GAM book quickly used up all the RAM in my test system and the
OS killed R. This could be incorrect usage on my part; right now the grid
of points at which SOS smooths are evaluated (if not supplied by the user)
can produce invalid coordinates for the corners of tiles as the grid is
generated for tile centres without respect to the spacing of those tiles.
logical; wrap plots as a patchwork? If FALSE, a list of
ggplot objects is returned, 1 per term plotted.
an environment to look up the data within.
additional arguments passed to patchwork::wrap_plots().
Gavin L. Simpson
load_mgcv()
# simulate some data
df1 <- data_sim("eg1", n = 400, dist = "normal", scale = 2, seed = 2)
# fit GAM
m1 <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = df1, method = "REML")
# plot all smooths
draw(m1)
# can add partial residuals
draw(m1, residuals = TRUE)
df2 <- data_sim("eg2", n = 1000, dist = "normal", scale = 1, seed = 2)
m2 <- gam(y ~ s(x, z, k = 40), data = df2, method = "REML")
draw(m2, contour = FALSE, n = 50)
# See https://gavinsimpson.github.io/gratia/articles/custom-plotting.html
# for more examples and for details on how to modify the theme of all the
# plots produced by draw(). To modify all panels, for example to change the
# theme, use the & operator
Run the code above in your browser using DataLab