gratia (version 0.9.0)

derivative_samples: Posterior expectations of derivatives from an estimated model

Description

Posterior expectations of derivatives from an estimated model

Usage

derivative_samples(object, ...)
# S3 method for default
derivative_samples(object, ...)
# S3 method for gamm
derivative_samples(object, ...)
# S3 method for gam
derivative_samples(
  object,
  focal = NULL,
  data = NULL,
  order = 1L,
  type = c("forward", "backward", "central"),
  scale = c("response", "linear_predictor"),
  method = c("gaussian", "mh", "inla", "user"),
  n = 100,
  eps = 1e-07,
  n_sim = 10000,
  level = 0.95,
  seed = NULL,
  envir = environment(formula(object)),
  draws = NULL,
  ...
)

Value

A tibble, currently with the following variables:

• .derivative: the estimated partial derivative,

• additional columns containing the covariate values at which the derivative was evaluated.

Arguments

object

an R object to compute derivatives for

...

arguments passed to other methods and on to fitted_samples()

focal

character; name of the focal variable. The response derivative of the response with respect to this variable will be returned. All other variables involved in the model will be held at constant values. This can be missing if supplying data, in which case, the focal variable will be identified as the one variable that is not constant.

data

a data frame containing the values of the model covariates at which to evaluate the first derivatives of the smooths. If supplied, all but one variable must be held at a constant value.

order

numeric; the order of derivative.

type

character; the type of finite difference used. One of "forward", "backward", or "central".

scale

character; should the derivative be estimated on the response or the linear predictor (link) scale? One of "response" (the default), or "linear predictor".

method

character; which method should be used to draw samples from the posterior distribution. "gaussian" uses a Gaussian (Laplace) approximation to the posterior. "mh" uses a Metropolis Hastings sample that alternates t proposals with proposals based on a shrunken version of the posterior covariance matrix. "inla" uses a variant of Integrated Nested Laplace Approximation due to Wood (2019), (currently not implemented). "user" allows for user-supplied posterior draws (currently not implemented).

n

numeric; the number of points to evaluate the derivative at (if data is not supplied).

eps

numeric; the finite difference.

n_sim

integer; the number of simulations used in computing the simultaneous intervals.

level

numeric; 0 < level < 1; the coverage level of the credible interval. The default is 0.95 for a 95% interval.

seed

numeric; a random seed for the simulations.

envir

the environment within which to recreate the data used to fit object.

draws

matrix; user supplied posterior draws to be used when method = "user".

Author

Gavin L. Simpson

Examples

load_mgcv()
df <- data_sim("eg1", dist = "negbin", scale = 0.25, seed = 42)

# fit the GAM (note: for execution time reasons using bam())
m <- bam(y ~ s(x0) + s(x1) + s(x2) + s(x3),
  data = df, family = nb(), method = "fREML")

# data slice through data along x2 - all other covariates will be set to
# typical values (value closest to median)
ds <- data_slice(m, x2 = evenly(x2, n = 200))

# samples from posterior of derivatives
fd_samp <- derivative_samples(m,
  data = ds, type = "central",
  focal = "x2", eps = 0.01, seed = 21, n_sim = 100
)

# plot the first 20 posterior draws
if (requireNamespace("ggplot2") && requireNamespace("dplyr")) {
  library("ggplot2")
  fd_samp |>
    dplyr::filter(.draw <= 20) |>
    ggplot(aes(x = x2, y = .derivative, group = .draw)) +
    geom_line(alpha = 0.5)
}