Numerical and Symbolic Derivatives

Computes symbolic derivatives based on the D function, or numerical derivatives based on finite differences.

derivative(
  f,
  var,
  params = list(),
  order = 1,
  accuracy = 4,
  stepsize = NULL,
  drop = TRUE,
  deparse = TRUE
)

Arguments

f

array of characters or a function returning a numeric array.

var

vector giving the variable names with respect to which the derivatives are to be computed and/or the point where the derivatives are to be evaluated. See details.

params

list of additional parameters passed to f.

order

integer vector, giving the differentiation order for each variable. See details.

accuracy

degree of accuracy for numerical derivatives.

stepsize

finite differences stepsize for numerical derivatives. It is based on the precision of the machine by default.

drop

if TRUE, return the array of derivatives without adding a dummy dimension when order is of length 1.

deparse

if TRUE, return character instead of expression.

Value

array.

Details

The function behaves differently depending on the arguents order, the order of differentiation, and var, the variable names with respect to which the derivatives are computed.

When multiple variables are provided and order is a single integer \(n\), then the \(n\)-th order derivative is computed for each element of f with respect to each variable:

$$D = \partial^{(n)} \otimes F$$

that is:

$$D_{i,\dots,j,k} = \partial^{(n)}_{k} F_{i,\dots,j}$$

where \(F\) is the array of functions and \(\partial_k^{(n)}\) denotes the \(n\)-th order partial derivative with respect to the \(k\)-th variable.

When order matches the length of var, it is assumed that the differentiation order is provided for each variable. In this case, each element is derived \(n_k\) times with respect to the \(k\)-th variable, for each of the \(m\) variables.

$$D_{i,\dots,j} = \partial^{(n_1)}_1\cdots\partial^{(n_m)}_m F_{i,\dots,j}$$

The same applies when order is a named vector giving the differentiation order for each variable. For example, order = c(x=1, y=2) differentiates once with respect to \(x\) and twice with respect to \(y\). A call with order = c(x=1, y=0) is equivalent to order = c(x=1).

To compute numerical derivatives or to evaluate symbolic derivatives at a point, the function accepts a named vector for the argument var; e.g. var = c(x=1, y=2) evaluates the derivatives in \(x=1\) and \(y=2\). For functions where the first argument is used as a parameter vector, var should be a numeric vector indicating the point at which the derivatives are to be calculated.

References

Guidotti E (2022). "calculus: High-Dimensional Numerical and Symbolic Calculus in R." Journal of Statistical Software, 104(5), 1-37. doi:10.18637/jss.v104.i05

See also

Other derivatives: taylor()

Other differential operators: curl(), divergence(), gradient(), hessian(), jacobian(), laplacian()

Examples

### symbolic derivatives
derivative(f = "sin(x)", var = "x")
#> [1] "cos(x)"

### numerical derivatives
f <- function(x) sin(x)
derivative(f = f, var = c(x=0))
#> [1] 1

### higher order derivatives
f <- function(x) sin(x)
derivative(f = f, var = c(x=0), order = 3)
#> [1] -1

### multivariate functions 
##  - derive once with respect to x
##  - derive twice with respect to y
##  - evaluate in x=0 and y=0
f <- function(x, y) y^2*sin(x)
derivative(f = f, var = c(x=0, y=0), order = c(1,2))
#> [1] 2

### vector-valued functions
##  - derive each element twice with respect to each variable
##  - evaluate in x=0 and y=0
f <- function(x, y) c(x^2, y^2)
derivative(f, var = c(x=0, y=0), order = 2)
#>      [,1] [,2]
#> [1,]    2    0
#> [2,]    0    2

### vectorized interface
f <- function(x) c(sum(x), prod(x))
derivative(f, var = c(0,0,0), order = 1)
#>      [,1] [,2] [,3]
#> [1,]    1    1    1
#> [2,]    0    0    0