deriv                 package:stats                 R Documentation

_S_y_m_b_o_l_i_c _a_n_d _A_l_g_o_r_i_t_h_m_i_c _D_e_r_i_v_a_t_i_v_e_s _o_f _S_i_m_p_l_e _E_x_p_r_e_s_s_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     Compute derivatives of simple expressions, symbolically.

_U_s_a_g_e:

         D (expr, name)
      deriv(expr, ...)
     deriv3(expr, ...)

      ## Default S3 method:
      deriv(expr, namevec, function.arg = NULL, tag = ".expr",
            hessian = FALSE, ...)
      ## S3 method for class 'formula':
      deriv(expr, namevec, function.arg = NULL, tag = ".expr",
            hessian = FALSE, ...)

     ## Default S3 method:
     deriv3(expr, namevec, function.arg = NULL, tag = ".expr",
            hessian = TRUE, ...)
     ## S3 method for class 'formula':
     deriv3(expr, namevec, function.arg = NULL, tag = ".expr",
            hessian = TRUE, ...)

_A_r_g_u_m_e_n_t_s:

    expr: A 'expression' or 'call' or (except 'D') a formula with no
          lhs.

name,namevec: character vector, giving the variable names (only one for
          'D()') with respect to which derivatives will be computed.

function.arg: If specified and non-'NULL', a character vector of
          arguments for a function return, or a function (with empty
          body) or 'TRUE', the latter indicating that a function with
          argument names 'namevec' should be used.

     tag: character; the prefix to be used for the locally created
          variables in result.

 hessian: a logical value indicating whether the second derivatives
          should be calculated and incorporated in the return value.

     ...: arguments to tbe passed to or from methods.

_D_e_t_a_i_l_s:

     'D' is modelled after its S namesake for taking simple symbolic
     derivatives.

     'deriv' is a _generic_ function with a default and a 'formula'
     method.  It returns a 'call' for computing the 'expr' and its
     (partial) derivatives, simultaneously.  It uses so-called
     _algorithmic derivatives_.  If 'function.arg' is a function, its
     arguments can have default values, see the 'fx' example below.

     Currently, 'deriv.formula' just calls 'deriv.default' after
     extracting the expression to the right of '~'.

     'deriv3' and its methods are equivalent to 'deriv' and its methods
     except that 'hessian' defaults to 'TRUE' for 'deriv3'.

     The internal code knows about the arithmetic operators '+', '-',
     '*', '/' and '^', and the single-variable functions 'exp', 'log',
     'sin', 'cos', 'tan', 'sinh', 'cosh', 'sqrt', 'pnorm', 'dnorm',
     'asin', 'acos', 'atan', 'gamma', 'lgamma', 'digamma' and
     'trigamma', as well as 'psigamma' for one or two arguments (but
     derivative only with respect to the first). (Note that only the
     standard normal distribution is considered.)

_V_a_l_u_e:

     'D' returns a call and therefore can easily be iterated for higher
     derivatives.

     'deriv' and 'deriv3' normally return an 'expression' object whose
     evaluation returns the function values with a '"gradient"'
     attribute containing the gradient matrix.  If 'hessian' is 'TRUE'
     the evaluation also returns a '"hessian"' attribute containing the
     Hessian array.

     If 'function.arg' is not 'NULL', 'deriv' and 'deriv3' return a
     function with those arguments rather than an expression.

_R_e_f_e_r_e_n_c_e_s:

     Griewank, A.  and  Corliss, G. F. (1991) _Automatic
     Differentiation of Algorithms: Theory, Implementation, and
     Application_. SIAM proceedings, Philadelphia.

     Bates, D. M. and Chambers, J. M. (1992) _Nonlinear models._
     Chapter 10 of _Statistical Models in S_ eds J. M. Chambers and T.
     J. Hastie, Wadsworth & Brooks/Cole.

_S_e_e _A_l_s_o:

     'nlm' and 'optim' for numeric minimization which could make use of
     derivatives,

_E_x_a_m_p_l_e_s:

     ## formula argument :
     dx2x <- deriv(~ x^2, "x") ; dx2x
     ## Not run: 
     expression({
              .value <- x^2
              .grad <- array(0, c(length(.value), 1), list(NULL, c("x")))
              .grad[, "x"] <- 2 * x
              attr(.value, "gradient") <- .grad
              .value
     })
     ## End(Not run)
     mode(dx2x)
     x <- -1:2
     eval(dx2x)

     ## Something 'tougher':
     trig.exp <- expression(sin(cos(x + y^2)))
     ( D.sc <- D(trig.exp, "x") )
     all.equal(D(trig.exp[[1]], "x"), D.sc)

     ( dxy <- deriv(trig.exp, c("x", "y")) )
     y <- 1
     eval(dxy)
     eval(D.sc)

     ## function returned:
     deriv((y ~ sin(cos(x) * y)), c("x","y"), func = TRUE)

     ## function with defaulted arguments:
     (fx <- deriv(y ~ b0 + b1 * 2^(-x/th), c("b0", "b1", "th"),
                  function(b0, b1, th, x = 1:7){} ) )
     fx(2,3,4)

     ## Higher derivatives
     deriv3(y ~ b0 + b1 * 2^(-x/th), c("b0", "b1", "th"),
          c("b0", "b1", "th", "x") )

     ## Higher derivatives:
     DD <- function(expr,name, order = 1) {
        if(order < 1) stop("'order' must be >= 1")
        if(order == 1) D(expr,name)
        else DD(D(expr, name), name, order - 1)
     }
     DD(expression(sin(x^2)), "x", 3)
     ## showing the limits of the internal "simplify()" :
     ## Not run: 
     -sin(x^2) * (2 * x) * 2 + ((cos(x^2) * (2 * x) * (2 * x) + sin(x^2) *
         2) * (2 * x) + sin(x^2) * (2 * x) * 2)
     ## End(Not run)

