Derivatives of estimated smooths via finite differences
Source:R/derivatives.R, R/gamm4-methods.R, R/scam-methods.R
derivatives.RdDerivatives 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,
interval_method = c("auto", "gaussian", "bootstrap"),
simultaneous_method = c("simulation", "tube"),
simultaneous_domain = NULL,
tube_control = list()
)
# S3 method for class 'gamm4'
derivatives(object, ...)
# S3 method for class 'scam'
derivatives(object, ..., unconditional = FALSE)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 inmodelwill be sampled from. If supplied, a character vector of requested terms. Can be a partial match to a smooth term; see argumentpartial_matchbelow.- term
![[Deprecated]](figures/lifecycle-deprecated.svg)
Use selectinstead.- 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)), wherep = 2for central differences andp = 1for 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; supplieddataare used if neither is available. This is a scale-aware heuristic, not an error bound; unusual function scales or domain boundaries may require expliciteps. For first central differences the two points are separated byeps; for second central differences they are eachepsfrom 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 is0.95for 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 currentR).- partial_match
logical; should smooths be selected by partial matches with
term? IfTRUE,termcan only be a single string to match against.- newdata
Deprecated: use
datainstead.- envir
optional environment for functions and constants in model expressions; see
smooth_estimates().- wrt
differentiation coordinate:
"smooth"(the default) uses the smooth expression, such aslog(x);"covariate"uses a raw covariate, such asx, 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.
- interval_method
character; use stored scasm bootstrap draws for pointwise intervals with
"auto"(the default), or explicitly select"gaussian"or"bootstrap". Bootstrap simultaneous bands are unavailable.- simultaneous_method
character; calibration for simultaneous bands. The default,
"simulation", uses coefficient draws on the evaluation grid."tube"uses a conservative Gaussian threshold-crossing bound over a continuous interval for supported one-dimensional cubic splines. See simultaneous_bands.- simultaneous_domain
numeric pair of increasing finite endpoints, or a named list of such pairs keyed by spline coordinate. For tube bands,
NULLuses the range of returned evaluation coordinates, including gaps. All returned points must lie inside the interval and the interval must lie inside the fitted spline support. Requires tube calibration.- tube_control
named list controlling numerical tube calibration:
rel_tol(default1e-6),abs_tol(1e-8),subdivisions(1000L), androot_tol(1e-8). Requires tube calibration. Simulation controlsn_sim,n_cores(orncores), andseedare ignored by tube calibration.
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 (givenlevel);NAfor bootstrap limits,.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.
Parallel calculation
With mirai and carrier installed, configure workers with
mirai::daemons() to distribute calculations across selected smooths.
difference_smooths() distributes factor-level comparisons instead.
Without configured workers, or with only one calculation, evaluation is
serial. These functions leave the caller's worker pool running.
Model selection, evaluation of model expressions and random draws are
prepared in the caller. Workers receive the coordinates and coefficient
columns needed for their calculation. Custom prediction methods are evaluated
in the caller, including custom tensor margins and factor-smooth bases;
workers receive their prediction matrices. Simultaneous intervals use successive
draws in selection order, so set.seed() gives the same results with or
without workers, independently of their number or completion order.
derivatives() uses set.seed(); the other functions also accept seed,
which restores the caller's random number state on exit.
smooth_samples() draws coefficients jointly once, then reuses those draws
for every smooth, preserving dependence and chain identities. Sampling
finishes before smooth calculations start, so MH chains and smooth workers
are not nested. Sampling thread controls keep their existing meanings.
Workers use their configured BLAS thread settings; when using a threaded
BLAS, limit its threads before starting daemons to avoid competing threads.
Parallel work is most useful for expensive bases or interval calculations. Small grids can be slower because of transfer and scheduling costs. Large grids and many draws also require memory for worker inputs and returned results, in addition to the final output.
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>
# \donttest{
if (requireNamespace("mirai", quietly = TRUE) &&
requireNamespace("carrier", quietly = TRUE)) {
library("mirai")
library("gratia")
local({
mirai::daemons(2)
on.exit(mirai::daemons(0))
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