Derivatives of estimated smooths via finite differences

Usage

derivatives(object, ...)

# S3 method for default
derivatives(object, ...)

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

# S3 method for gam
derivatives(
  object,
  term,
  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.
term: character; vector of one or more smooth terms for which derivatives are required. If missing, derivatives for all smooth terms will be returned. Can be a partial match to a smooth term; see argument partial_match below.
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

Gavin L. Simpson

Examples


load_mgcv()
# \dontshow{
op <- options(pillar.sigfig = 3, cli.unicode = FALSE)
# }
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")
#> # A tibble: 400 x 10
#>    smooth var   by_var fs_var     data derivative    se  crit lower upper
#>    <chr>  <chr> <chr>  <chr>     <dbl>      <dbl> <dbl> <dbl> <dbl> <dbl>
#>  1 s(x0)  x0    NA     NA     0.000239       7.41  3.33  1.96 0.874  13.9
#>  2 s(x0)  x0    NA     NA     0.0103         7.40  3.33  1.96 0.884  13.9
#>  3 s(x0)  x0    NA     NA     0.0204         7.39  3.30  1.96 0.929  13.8
#>  4 s(x0)  x0    NA     NA     0.0304         7.36  3.24  1.96 1.01   13.7
#>  5 s(x0)  x0    NA     NA     0.0405         7.32  3.15  1.96 1.14   13.5
#>  6 s(x0)  x0    NA     NA     0.0506         7.26  3.04  1.96 1.30   13.2
#>  7 s(x0)  x0    NA     NA     0.0606         7.18  2.90  1.96 1.49   12.9
#>  8 s(x0)  x0    NA     NA     0.0707         7.09  2.76  1.96 1.69   12.5
#>  9 s(x0)  x0    NA     NA     0.0807         6.99  2.61  1.96 1.87   12.1
#> 10 s(x0)  x0    NA     NA     0.0908         6.87  2.47  1.96 2.03   11.7
#> # ... with 390 more rows

## derivatives for a selected smooth
derivatives(mod, type = "central", term = "s(x1)")
#> # A tibble: 100 x 10
#>    smooth var   by_var fs_var     data derivative    se  crit lower upper
#>    <chr>  <chr> <chr>  <chr>     <dbl>      <dbl> <dbl> <dbl> <dbl> <dbl>
#>  1 s(x1)  x1    NA     NA     0.000405     -0.907  3.12  1.96 -7.02  5.20
#>  2 s(x1)  x1    NA     NA     0.0105       -0.906  3.11  1.96 -7.01  5.20
#>  3 s(x1)  x1    NA     NA     0.0205       -0.898  3.10  1.96 -6.97  5.17
#>  4 s(x1)  x1    NA     NA     0.0306       -0.880  3.06  1.96 -6.88  5.12
#>  5 s(x1)  x1    NA     NA     0.0406       -0.849  3.00  1.96 -6.73  5.03
#>  6 s(x1)  x1    NA     NA     0.0507       -0.803  2.92  1.96 -6.52  4.92
#>  7 s(x1)  x1    NA     NA     0.0607       -0.740  2.81  1.96 -6.25  4.77
#>  8 s(x1)  x1    NA     NA     0.0708       -0.659  2.69  1.96 -5.93  4.61
#>  9 s(x1)  x1    NA     NA     0.0809       -0.557  2.56  1.96 -5.57  4.46
#> 10 s(x1)  x1    NA     NA     0.0909       -0.436  2.42  1.96 -5.19  4.32
#> # ... with 90 more rows
## or via a partial match
derivatives(mod, type = "central", term = "x1", partial_match = TRUE)
#> # A tibble: 100 x 10
#>    smooth var   by_var fs_var     data derivative    se  crit lower upper
#>    <chr>  <chr> <chr>  <chr>     <dbl>      <dbl> <dbl> <dbl> <dbl> <dbl>
#>  1 s(x1)  x1    NA     NA     0.000405     -0.907  3.12  1.96 -7.02  5.20
#>  2 s(x1)  x1    NA     NA     0.0105       -0.906  3.11  1.96 -7.01  5.20
#>  3 s(x1)  x1    NA     NA     0.0205       -0.898  3.10  1.96 -6.97  5.17
#>  4 s(x1)  x1    NA     NA     0.0306       -0.880  3.06  1.96 -6.88  5.12
#>  5 s(x1)  x1    NA     NA     0.0406       -0.849  3.00  1.96 -6.73  5.03
#>  6 s(x1)  x1    NA     NA     0.0507       -0.803  2.92  1.96 -6.52  4.92
#>  7 s(x1)  x1    NA     NA     0.0607       -0.740  2.81  1.96 -6.25  4.77
#>  8 s(x1)  x1    NA     NA     0.0708       -0.659  2.69  1.96 -5.93  4.61
#>  9 s(x1)  x1    NA     NA     0.0809       -0.557  2.56  1.96 -5.57  4.46
#> 10 s(x1)  x1    NA     NA     0.0909       -0.436  2.42  1.96 -5.19  4.32
#> # ... with 90 more rows
# \dontshow{
options(op)
# }