derivatives {gratia}

Derivatives of estimated smooths via finite differences

Description

Derivatives of estimated smooths via finite differences

Usage

derivatives(object, ...)

## Default S3 method:
derivatives(object, ...)

## S3 method for class 'gamm'
derivatives(object, ...)

## S3 method for class 'gam'
derivatives(
  object,
  select = NULL,
  term = deprecated(),
  data = newdata,
  order = 1L,
  type = c("forward", "backward", "central"),
  n = 100,
  eps = 1e-07,
  interval = c("confidence", "simultaneous"),
  n_sim = 10000,
  level = 0.95,
  unconditional = FALSE,
  frequentist = FALSE,
  offset = NULL,
  ncores = 1,
  partial_match = FALSE,
  ...,
  newdata = NULL
)

Arguments

object

an R object to compute derivatives for.

...

arguments passed to other methods.

select

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. Can be a partial match to a smooth term; see argument partial_match below.

term

Use select instead.

data

a data frame containing the values of the model covariates at which to evaluate the first derivatives of the smooths.

order

numeric; the order of derivative.

type

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

n

numeric; the number of points to evaluate the derivative at.

eps

numeric; the finite difference.

interval

character; the type of interval to compute. One of "confidence" for point-wise intervals, or "simultaneous" for simultaneous intervals.

n_sim

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

level

numeric; ⁠0 < level < 1⁠; the confidence level of the point-wise or simultaneous interval. The default is 0.95 for a 95% interval.

unconditional

logical; use smoothness selection-corrected Bayesian covariance matrix?

frequentist

logical; use the frequentist covariance matrix?

offset

numeric; a value to use for any offset term

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).

partial_match

logical; should smooths be selected by partial matches with term? If TRUE, term can only be a single string to match against.

newdata

Deprecated: use data instead.

Value

A tibble, currently with the following variables:

• smooth: the smooth each row refers to,

• var: the name of the variable involved in the smooth,

• data: values of var at which the derivative was evaluated,

• derivative: the estimated derivative,

• se: the standard error of the estimated derivative,

• crit: the critical value such that derivative ± (crit * se) gives the upper and lower bounds of the requested confidence or simultaneous interval (given level),

• lower: the lower bound of the confidence or simultaneous interval,

• upper: the upper bound of the confidence or simultaneous interval.

Note

derivatives() will ignore any random effect smooths it encounters in object.

Author(s)

Gavin L. Simpson

Examples

load_mgcv()

dat <- data_sim("eg1", n = 400, dist = "normal", scale = 2, seed = 42)
mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = "REML")

## first derivatives of all smooths using central finite differences
derivatives(mod, type = "central")

## derivatives for a selected smooth
derivatives(mod, type = "central", select = "s(x1)")
## or via a partial match
derivatives(mod, type = "central", select = "x1", partial_match = TRUE)