# dhyperb: Hyperbolic Distribution In HyperbolicDist: The hyperbolic distribution

## Description

Density function, distribution function, quantiles and random number generation for the hyperbolic distribution with parameter vector `Theta`. Utility routines are included for the derivative of the density function and to find suitable break points for use in determining the distribution function.

## Usage

 ```1 2 3 4 5 6 7 8``` ```dhyperb(x, Theta, KNu = NULL, logPars = FALSE) phyperb(q, Theta, small = 10^(-6), tiny = 10^(-10), deriv = 0.3, subdivisions = 100, accuracy = FALSE, ...) qhyperb(p, Theta, small = 10^(-6), tiny = 10^(-10), deriv = 0.3, nInterpol = 100, subdivisions = 100, ...) rhyperb(n, Theta) ddhyperb(x, Theta, KNu = NULL, ...) hyperbBreaks(Theta, small = 10^(-6), tiny = 10^(-10), deriv = 0.3, ...) ```

## Arguments

 `x,q` Vector of quantiles. `p` Vector of probabilities. `n` Number of observations to be generated. `Theta` Parameter vector taking the form `c(pi,zeta,delta,mu)`. `KNu` Sets the value of the Bessel function in the density or derivative of the density. See Details

.

 `logPars` Logical; if `TRUE` the second and third components of Theta are taken to be log(zeta) and log(delta) respectively. `small` Size of a small difference between the distribution function and zero or one. See Details. `tiny` Size of a tiny difference between the distribution function and zero or one. See Details. `deriv` Value between 0 and 1. Determines the point where the derivative becomes substantial, compared to its maximum value. See Details. `accuracy` Uses accuracy calculated by `integrate` to try and determine the accuracy of the distribution function calculation. `subdivisions` The maximum number of subdivisions used to integrate the density returning the distribution function. `nInterpol` The number of points used in qhyperb for cubic spline interpolation (see `splinefun`) of the distribution function. `...` Passes arguments to `uniroot`. See Details.

## Details

The hyperbolic distribution has density

f(x)=1/(2 sqrt(1+pi^2) K_1(zeta)) exp(-zeta(sqrt(1+pi^2) sqrt(1+((x-mu)/delta)^2)-pi (x-mu)/delta))

where K_1() is the modified Bessel function of the third kind with order 1.

A succinct description of the hyperbolic distribution is given in Barndorff-Nielsen and Bl<e6>sild (1983). Three different possibleparameterisations are described in that paper. A fourth parameterization is given in Prause (1999). All use location and scale parameters mu and delta. There are two other parameters in each case.

Use `hyperbChangePars` to convert from the (alpha,beta) (phi,gamma) or xi,chi) parameterisations to the (pi,zeta) parameterisation used above.

`phyperb` breaks the real line into eight regions in order to determine the integral of `dhyperb`. The break points determining the regions are found by `hyperbBreaks`, based on the values of `small`, `tiny`, and `deriv`. In the extreme tails of the distribution where the probability is `tiny` according to `hyperbCalcRange`, the probability is taken to be zero. In the range between where the probability is `tiny` and `small` according to `hyperbCalcRange`, an exponential approximation to the hyperbolic distribution is used. In the inner part of the distribution, the range is divided in 4 regions, 2 above the mode, and 2 below. On each side of the mode, the break point which forms the 2 regions is where the derivative of the density function is `deriv` times the maximum value of the derivative on that side of the mode. In each of the 4 inner regions the numerical integration routine `safeIntegrate` (which is a wrapper for `integrate`) is used to integrate the density `dhyperb`.

`qhyperb` uses the breakup of the real line into the same 8 regions as `phyperb`. For quantiles which fall in the 2 extreme regions, the quantile is returned as `-Inf` or `Inf` as appropriate. In the range between where the probability is `tiny` and `small` according to `hyperbCalcRange`, an exponential approximation to the hyperbolic distribution is used from which the quantile may be found in closed form. In the 4 inner regions `splinefun` is used to fit values of the distribution function generated by `phyperb`. The quantiles are then found using the `uniroot` function.

`phyperb` and `qhyperb` may generally be expected to be accurate to 5 decimal places.

The hyperbolic distribution is a special case of the generalized hyperbolic distribution (Barndorff-Nielsen and Bl<e6>sild (1983)). The generalized hyperbolic distribution can be represented as a particular mixture of the normal distribution where the mixing distribution is the generalized inverse Gaussian. `rhyperb` uses this representation to generate observations from the hyperbolic distribution. Generalized inverse Gaussian observations are obtained via the algorithm of Dagpunar (1989).

## Value

`dhyperb` gives the density, `phyperb` gives the distribution function, `qhyperb` gives the quantile function and `rhyperb` generates random variates. An estimate of the accuracy of the approximation to the distribution function may be found by setting `accuracy = TRUE` in the call to `phyperb` which then returns a list with components `value` and `error`.

`ddhyperb` gives the derivative of `dhyperb`.

`hyperbBreaks` returns a list with components:

 `xTiny` Value such that probability to the left is less than `tiny`. `xSmall` Value such that probability to the left is less than `small`. `lowBreak` Point to the left of the mode such that the derivative of the density is `deriv` times its maximum value on that side of the mode `highBreak` Point to the right of the mode such that the derivative of the density is `deriv` times its maximum value on that side of the mode `xLarge` Value such that probability to the right is less than `small`. `xHuge` Value such that probability to the right is less than `tiny`. `modeDist` The mode of the given hyperbolic distribution.

## Author(s)

David Scott d.scott@auckland.ac.nz, Ai-Wei Lee, Jennifer Tso, Richard Trendall

## References

Barndorff-Nielsen, O. and Bl<e6>sild, P (1983). Hyperbolic distributions. In Encyclopedia of Statistical Sciences, eds., Johnson, N. L., Kotz, S. and Read, C. B., Vol. 3, pp. 700–707. New York: Wiley.

Dagpunar, J.S. (1989). An easily implemented generalized inverse Gaussian generator Commun. Statist. -Simula., 18, 703–710.

Prause, K. (1999) The generalized hyperbolic models: Estimation, financial derivatives and risk measurement. PhD Thesis, Mathematics Faculty, University of Freiburg.

`safeIntegrate`, `integrate` for its shortfalls, `splinefun`, `uniroot` and `hyperbChangePars` for changing parameters to the (pi,zeta) parameterisation, `dghyp` for the generalized hyperbolic distribution.

## Examples

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31``` ```Theta <- c(2,1,1,0) hyperbRange <- hyperbCalcRange(Theta, tol = 10^(-3)) par(mfrow = c(1,2)) curve(dhyperb(x, Theta), from = hyperbRange[1], to = hyperbRange[2], n = 1000) title("Density of the\n Hyperbolic Distribution") curve(phyperb(x, Theta), from = hyperbRange[1], to = hyperbRange[2], n = 1000) title("Distribution Function of the\n Hyperbolic Distribution") dataVector <- rhyperb(500, Theta) curve(dhyperb(x, Theta), range(dataVector)[1], range(dataVector)[2], n = 500) hist(dataVector, freq = FALSE, add =TRUE) title("Density and Histogram\n of the Hyperbolic Distribution") logHist(dataVector, main = "Log-Density and Log-Histogram\n of the Hyperbolic Distribution") curve(log(dhyperb(x, Theta)), add = TRUE, range(dataVector)[1], range(dataVector)[2], n = 500) par(mfrow = c(2,1)) curve(dhyperb(x, Theta), from = hyperbRange[1], to = hyperbRange[2], n = 1000) title("Density of the\n Hyperbolic Distribution") curve(ddhyperb(x, Theta), from = hyperbRange[1], to = hyperbRange[2], n = 1000) title("Derivative of the Density\n of the Hyperbolic Distribution") par(mfrow = c(1,1)) hyperbRange <- hyperbCalcRange(Theta, tol = 10^(-6)) curve(dhyperb(x, Theta), from = hyperbRange[1], to = hyperbRange[2], n = 1000) bks <- hyperbBreaks(Theta) abline(v = bks) ```

### Example output

```
```

HyperbolicDist documentation built on May 1, 2019, 7:38 p.m.