nlsDeriv {nlsr}

nlsDeriv Functions to take symbolic derivatives.

Description

Compute derivatives of simple expressions symbolically, allowing user-specified derivatives.

Usage

nlsDeriv(expr, name, derivEnv = sysDerivs, do_substitute = FALSE, verbose = FALSE, ...)

codeDeriv(expr, namevec, hessian = FALSE, derivEnv = sysDerivs, 
          do_substitute = FALSE, verbose = FALSE, ...)

fnDeriv(expr, namevec, args = all.vars(expr), env = environment(expr), 
          do_substitute = FALSE, verbose = FALSE, ...)

Arguments

expr

An expression represented in a variety of ways. See Details.

name

The name of the variable with respect to which the derivative will be computed.

derivEnv

The environment in which derivatives are stored.

do_substitute

If TRUE, use substitute to get the expression passed as expr, otherwise evaluate it.

verbose

If TRUE, then diagnostic output will be printed as derivatives and simplifications are recognized.

...

Additional parameters which will be passed to codeDeriv from fnDeriv, and to nlsSimplify from nlsDeriv and codeDeriv.

namevec

Character vector giving the variable names with respect to which the derivatives will be taken.

hessian

Logical indicator of whether the 2nd derivatives should also be computed.

args

Desired arguments for the function. See Details below.

env

The environment to be attached to the created function. If NULL, the caller's frame is used.

Details

Functions nlsDeriv and codeDeriv are designed as replacements for the stats package functions D and deriv respectively, though the argument lists do not match exactly.

The nlsDeriv function computes a symbolic derivative of an expression or language object. Known derivatives are stored in derivEnv; the default sysDerivs contains expressions for all of the derivatives recognized by deriv, but in addition allows differentiation with respect to any parameter where it makes sense. It also allows the derivative of abs and sign, using an arbitrary choice of 0 at the discontinuities.

The codeDeriv function computes an expression for efficient calculation of the expression value together with its gradient and optionally the Hessian matrix.

The fnDeriv function wraps the codeDeriv result in a function. If the args are given as a character vector (the default), the arguments will have those names, with no default values. Alternatively, a custom argument list with default values can be created using alist; see the example below.

The expr argument will be converted to a language object using dex (but note the different default for do_substitute). Normally it should be a formula with no left hand side, e.g. ~ x^2 , or an expression vector e.g. expression(x, x^2, x^3) , or a language object e.g. quote(x^2). In codeDeriv and fnDeriv the expression vector must be of length 1.

The newDeriv function is used to define a new derivative. The expr argument should match the header of the function as a call to it (e.g. as in the help pages), and the deriv argument should be an expression giving the derivative, including calls to D(arg), which will not be evaluated, but will be substituted with partial derivatives of that argument with respect to name. See the examples below.

If expr or deriv is missing in a call to newDeriv(), it will return the currently saved derivative record from derivEnv. If name is missing in a call to nlsDeriv with a function call, it will print a message describing the derivative formula and return NULL.

To handle functions which act differently if a parameter is missing, code the default value of that parameter to .MissingVal, and give a derivative that is conditional on missing() applied to that parameter. See the derivatives of "-" and "+" in the file derivs.R for an example.

Value

If expr is an expression vector, nlsDeriv and nlsSimplify return expression vectors containing the response. For formulas or language objects, a language object is returned.

codeDeriv always returns a language object.

fnDeriv returns a closure (i.e. a function).

nlsDeriv returns the symbolic derivative of the expression.

newDeriv with expr and deriv specified is called for the side effect of recording the derivative in derivEnv. If expr is missing, it will return the list of names of functions for which derivatives are recorded. If deriv is missing, it will return its record for the specified function.

Note

newDeriv(expr, deriv, ...) will issue a warning if a different definition for the derivative exists in the derivative table.

Author(s)

Duncan Murdoch

See Also

deriv

Examples

 nlsDeriv(~ sin(x+y), "x")

 f <- function(x) x^2
 newDeriv(f(x), 2*x*D(x))
 nlsDeriv(~ f(abs(x)), "x")
 
 nlsDeriv(~ pnorm(x, sd=2, log = TRUE), "x")
 fnDeriv(~ pnorm(x, sd = sd, log = TRUE), "x")
 f <- fnDeriv(~ pnorm(x, sd = sd, log = TRUE), "x", args = alist(x =, sd = 2))
 f
 f(1)
 100*(f(1.01) - f(1))  # Should be close to the gradient
 
       # The attached gradient attribute (from f(1.01)) is
       # meaningless after the subtraction.
       
 # Multiple point example
 xvals <- c(1, 3, 4.123)
 print(f(xvals))
 # Getting a hessian matrix
 f2 <- ~ (x-2)^3*y - y^2
 mydf2 <- fnDeriv(f2, c("x","y"), hessian=TRUE)
 # display the resulting function
 print(mydf2)
 x <- c(1, 2)
 y <- c(0.5, 0.1)
 evalmydf2 <- mydf2(x, y)
 print(evalmydf2)
 # the first index of the hessian attribute is the point at which we want the hessian
 hmat1 <- as.matrix(attr(evalmydf2,"hessian")[1,,])
 print(hmat1)
 hmat2 <- as.matrix(attr(evalmydf2,"hessian")[2,,])
 print(hmat2)