sns.fghEval.numaug: Utility function for augmentation of a log-density function with numerical gradient and Hessian as needed

Description

Augmenting a log-density with numerical gradient and Hessian, so it can be used by sns or sns.run. This augmentation will also be done inside the function, if the value of numderiv parameter passed to sns and sns.run is 1 or 2. The advantage of using sns.fghEval.numaug outside these functions is efficiency, since the agumentation code will not have to be executed in every function call. Users must set numderiv to 0 when calling sns or sns.run if calling sns.fghEval.numaug first. See example.

Usage

sns.fghEval.numaug(fghEval, numderiv = 0
  , numderiv.method = c("Richardson", "simple")
  , numderiv.args = list())

Value

A function, accepting same arguments as fghEval, but guaranteed to return the original log-density, plus gradient and Hessian (both of which could possibly by numerically calculated). If numderiv=0, fghEval is returned without change. The function will return log-density, gradient and Hessian as elements f, g and h of a list.

Arguments

fghEval: Log-density to be sampled from. A valid log-density can have one of 3 forms: 1) return log-density, but no gradient or Hessian, 2) return a list of f and g for log-density and its gradient vector, respectively, 3) return a list of f, g, and h for log-density, gradient vector, and Hessian matrix. Missing derivatives are computed numerically.
numderiv: This must be matched with fghEval: Integer with value from the set 0,1,2. If 0, no numerical differentiation is performed, and thus fghEval is expected to supply f, g and h. If 1, we expect fghEval to provide f amd g, and Hessian will be calculated numerically. If 2, fghEval only returns log-density, and numerical differentiation is needed to calculate gradient and Hessian.
numderiv.method: Method used for numeric differentiation. This is passed to the grad and hessian functions in numDeriv package. See the package documentation for details.
numderiv.args: Arguments to the numeric differentiation method chosen in numderiv.method, passed to grad and hessian functions in numDeriv. See package documentation for details.

Author

Alireza S. Mahani, Asad Hasan, Marshall Jiang, Mansour T.A. Sharabiani

References