Skip to contents

Derivatives of estimated smooths via finite differences

Source: R/derivatives.R
derivatives.Rd

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 = NULL,
  interval = c("confidence", "simultaneous"),
  n_sim = 10000,
  level = 0.95,
  unconditional = FALSE,
  frequentist = FALSE,
  offset = NULL,
  ncores = 1,
  partial_match = FALSE,
  ...,
  newdata = NULL,
  envir = NULL,
  wrt = c("smooth", "covariate"),
  focal = 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 will 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

[Deprecated] 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

a positive finite number giving the absolute finite-difference step, or NULL (the default) to choose it automatically. The automatic step is the fitted range of the differentiation coordinate multiplied by .Machine$double.eps^(1 / (order + p)), where p = 2 for central differences and p = 1 for forward or backward differences. A constant coordinate uses its absolute value (or one if zero) instead of its range. The step is rounded upwards and bounded below so that adding it to the coordinates produces a representable change. Stored transformed values or raw covariate summaries supply the range; supplied data are used if neither is available. This is a scale-aware heuristic, not an error bound; unusual function scales or domain boundaries may require explicit eps. For first central differences the two points are separated by eps; for second central differences they are each eps from the target.

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.

envir

optional environment for functions and constants in model expressions; see smooth_estimates().

wrt

differentiation coordinate: "smooth" (the default) uses the smooth expression, such as log(x); "covariate" uses a raw covariate, such as x, and reevaluates expressions at each finite-difference point.

focal

name of the differentiation coordinate, or a vector with one name per selected smooth. For raw-covariate derivatives it must be supplied when a smooth depends on multiple raw inputs. A single name can be used for all selected univariate smooths.

Value

A tibble, currently with the following variables:

  • .smooth: the smooth each row refers to,

  • .by: the name of any factor by variable involved in the smooth,

  • .fs: the name of any random factor variable involved in the smooth,

  • .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_ci: the lower bound of the confidence or simultaneous interval,

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

  • plus one or more columns of data containing the values of covariates at which the derivative was evaluated.

Note

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

Author

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")
#> # A tibble: 400 x 12
#>    .smooth .by   .fs   .derivative   .se .crit .lower_ci .upper_ci      x0    x1
#>    <chr>   <chr> <chr>       <dbl> <dbl> <dbl>     <dbl>     <dbl>   <dbl> <dbl>
#>  1 s(x0)   NA    NA           7.41  3.33  1.96     0.874      13.9 2.42e-4    NA
#>  2 s(x0)   NA    NA           7.40  3.33  1.96     0.884      13.9 1.03e-2    NA
#>  3 s(x0)   NA    NA           7.39  3.30  1.96     0.929      13.8 2.04e-2    NA
#>  4 s(x0)   NA    NA           7.36  3.24  1.96     1.01       13.7 3.04e-2    NA
#>  5 s(x0)   NA    NA           7.32  3.15  1.96     1.14       13.5 4.05e-2    NA
#>  6 s(x0)   NA    NA           7.26  3.04  1.96     1.30       13.2 5.06e-2    NA
#>  7 s(x0)   NA    NA           7.18  2.90  1.96     1.49       12.9 6.06e-2    NA
#>  8 s(x0)   NA    NA           7.09  2.76  1.96     1.69       12.5 7.07e-2    NA
#>  9 s(x0)   NA    NA           6.99  2.61  1.96     1.87       12.1 8.08e-2    NA
#> 10 s(x0)   NA    NA           6.87  2.47  1.96     2.03       11.7 9.08e-2    NA
#> # i 390 more rows
#> # i 2 more variables: x2 <dbl>, x3 <dbl>

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