gratia: smooth_samples – R documentation

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

smooth_samples

Posterior draws for individual smooths

Description

Returns draws from the posterior distributions of smooth functions in a GAM. Useful, for example, for visualising the uncertainty in individual estimated functions.

Usage

smooth_samples(model, ...)

## S3 method for class 'gam'
smooth_samples(
  model,
  term = NULL,
  n = 1,
  newdata = NULL,
  seed = NULL,
  freq = FALSE,
  unconditional = FALSE,
  ncores = 1L,
  n_vals = 200,
  ...
)

Arguments

`model`	a fitted model of the supported types
`...`	arguments passed to other methods. For `fitted_samples()`, these are passed on to `predict.gam()`.
`term`	character; select which smooth's posterior to draw from. The default (`NULL`) means the posteriors of all smooths in `model` wil be sampled from. If supplied, a character vector of requested terms.
`n`	numeric; the number of posterior samples to return.
`newdata`	data frame; new observations at which the posterior draws from the model should be evaluated. If not supplied, the data used to fit the model will be used for `newdata`, if available in `model`.
`seed`	numeric; a random seed for the simulations.
`freq`	logical; `TRUE` to use the frequentist covariance matrix of the parameter estimators, `FALSE` to use the Bayesian posterior covariance matrix of the parameters.
`unconditional`	logical; if `TRUE` (and `freq == FALSE`) then the Bayesian smoothing parameter uncertainty corrected covariance matrix is used, if available.
`ncores`	number of cores for generating random variables from a multivariate normal distribution. Passed to `mvnfast::rmvn()`. Parallelization will take place only if OpenMP is supported (but appears to work on Windows with current `R`).
`n_vals`	numeric; how many locations to evaluate the smooth at if `newdata` not supplied

Value

A tibble with additional classes "smooth_samples" and '"posterior_samples".

For the "gam" method, the columns currently returned (not in this order) are:

smooth; character vector. Indicates the smooth function for that particular draw,
term; character vector. Similar to smooth, but will contain the full label for the smooth, to differentiate factor-by smooths for example.
by_variable; character vector. If the smooth involves a by term, the by variable will be named here, NA_character_ otherwise.
row; integer. A vector of values seq_len(n_vals), repeated if n > 1L. Indexes the row in newdata for that particular draw.
draw; integer. A vector of integer values indexing the particular posterior draw that each row belongs to.
value; numeric. The value of smooth function for this posterior draw and covariate combination.
.xN; numeric. A series of one or more columns containing data required for the smooth. .x1 will always be present and contains the values of the covariate in the smooth. For example if smooth is s(z) then .x1 will contain the values of covariate z at which the smooth was evaluated. Further covariates for multi-dimensional thin plate splines (e.g. s(x, z)) or tensor product smooths (e.g. te(x,z,a)) will result in variables .x1 and .x2, and .x1, .x2, and .x3 respectively, with the number (1, 2, etc) representing the order in which the covariates were specified in the smooth.
Additional columns will be present in the case of factor by smooths, which will contain the level for the factor named in by_variable for that particular posterior draw.

Warning

The set of variables returned and their order in the tibble is subject to change in future versions. Don't rely on position.

Author(s)

Gavin L. Simpson

Examples

load_mgcv()

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

smooth_samples(m1, term = "s(x0)", n = 5, seed = 42)

## A factor by example (with a spurious covariate x0)

dat <- gamSim(4)

## fit model...
m2 <- gam(y ~ fac + s(x2, by = fac) + s(x0), data = dat)
sms <- smooth_samples(m2, n = 5, seed = 42)
draw(sms)

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