compareDerivatives: function to compare analytic and numeric derivatives
In EBukin/maxLik-dev: Maximum Likelihood Estimation and Related Tools

Description Usage Arguments Details Value Author(s) See Also Examples

This function compares analytic and numerical derivative and prints related diagnostics information. It is intended for testing and debugging code for analytic derivatives for maximization algorithms.

1	compareDerivatives(f, grad, hess=NULL, t0, eps=1e-6, print=TRUE, ...)

`f`	function to be differentiated. The parameter (vector) of interest must be the first argument. The function may return a vector, in that case the derivative will be a matrix.
`grad`	analytic gradient. This may be either a function, returning the analytic gradient, or a numeric vector, the pre-computed gradient. The function must use the same set of parameters as `f`. If `f` is a vector-valued function, grad must return/be a matrix where the number of rows equals the number of components of `f`, and the number of columns must equal to the number of components in `t0`.
`hess`	function returning the analytic hessian. If present, hessian matrices are compared too. Only appropriate for scalar-valued functions.
`t0`	numeric vector, parameter at which the derivatives are compared. The derivative is taken with respect to this vector. both `f`m `grad` (if function) and `hess` (if present) must accept this value as the first parameter.
`eps`	numeric. Step size for numeric differentiation. Central derivative is used.
`print`	logical: TRUE to print a summary, FALSE to return the comparison only (invisibly).
`...`	further arguments to `f`, `grad` and `hess`.

Analytic derivatives (and Hessian) substantially improve the estimation speed and reliability. However, these are typically hard to program. This utility compares the programmed result and the (internally calculated) numeric derivative. For every component of f, it prints the parameter value, analytic and numeric derivative, and their relative difference

rel.diff = (analytic - numeric)/(0.5*(analytic + numeric)).

If analytic = 0 = numeric, the rel.diff = 0. If analytic derivatives are correct and the function is sufficiently smooth, expect the relative differences to be less than 1e-7.

A list with following components:

`t0`	the input argument `t0`
`f.t0`	f(t0)
`compareGrad`	a list with components `analytic` = grad(t0), `nmeric` = numericGradient(f, t0), and their `rel.diff`.
`maxRelDiffGrad`	max(abs(rel.diff))

If hess is also provided, the following optional components are also present:

`compareHessian`	a list with components `analytic` = hess(t0), `numeric` = numericGradient(grad, t0), and their `rel.diff`.
`maxRelDiffHess`	max(abs(rel.diff)) for the Hessian

Ott Toomet otoomet@ut.ee and Spencer Graves

numericGradient deriv

## A simple example with sin(x)' = cos(x)
f <- function(x)c(sin=sin(x))
Dsin <- compareDerivatives(f, cos, t0=c(angle=1))
##
## Example of normal log-likelihood.  Two-parameter
## function.
##
x <- rnorm(100, 1, 2) # generate rnorm x
l <- function(b) sum(dnorm(x, mean=b[1], sd=b[2], log=TRUE))
gradl <- function(b) {
    c(mu=sum(x - b[1])/b[2]^2,
    sigma=sum((x - b[1])^2/b[2]^3 - 1/b[2]))
}
gradl. <- compareDerivatives(l, gradl, t0=c(mu=1,sigma=2))

##
## An example with f returning a vector, t0 = a scalar
##
trig <- function(x)c(sin=sin(x), cos=cos(x))
Dtrig <- function(x)c(sin=cos(x), cos=-sin(x))
Dtrig. <- compareDerivatives(trig, Dtrig, t0=1)