dhyperb: Hyperbolic Distribution

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

View source: R/dhyperb.R

Description

Density function, distribution function, quantiles and random number generation for the hyperbolic distribution with parameter vector param. 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
 9
10
11
12
13
14
15
16
17
dhyperb(x, mu = 0, delta = 1, alpha = 1, beta = 0,
        param = c(mu, delta, alpha, beta))
phyperb(q, mu = 0, delta = 1, alpha = 1, beta = 0,
        param = c(mu, delta, alpha, beta),
        small = 10^(-6), tiny = 10^(-10),
        deriv = 0.3, subdivisions = 100, accuracy = FALSE, ...)
qhyperb(p, mu = 0, delta = 1, alpha = 1, beta = 0,
        param = c(mu, delta, alpha, beta),
        small = 10^(-6), tiny = 10^(-10),
        deriv = 0.3, nInterpol = 100, subdivisions = 100, ...)
rhyperb(n, mu = 0, delta = 1, alpha = 1, beta = 0,
        param = c(mu, delta, alpha, beta))
ddhyperb(x, mu = 0, delta = 1, alpha = 1, beta = 0,
         param = c(mu, delta, alpha, beta))
hyperbBreaks(mu = 0, delta = 1, alpha = 1, beta = 0,
             param = c(mu, delta, alpha, beta),
             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.

mu

mu is the location parameter. By default this is set to 0.

delta

delta is the scale parameter of the distribution. A default value of 1 has been set.

alpha

alpha is the tail parameter, with a default value of 1.

beta

beta is the skewness parameter, by default this is 0.

param

Parameter vector taking the form c(mu, delta, alpha, beta).

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<c3><a6>sild (1983). Three different possible parameterisations 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 (pi, zeta) (phi, gamma) or xi, chi) parameterisations to the (alpha, beta) parameterisation used above.

Each of the functions are wrapper functions for their equivalent generalized hyperbolic. For example, dhyperb calls dghyp.

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<c3><a6>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<c3><a6>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.

See Also

safeIntegrate, integrate for its shortfalls, splinefun, uniroot and hyperbChangePars for changing parameters to the (alpha, beta) 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
param <- c(0, 2, 1, 0)
hyperbRange <- hyperbCalcRange(param = param, tol = 10^(-3))
par(mfrow = c(1, 2))
curve(dhyperb(x, param = param), from = hyperbRange[1], to = hyperbRange[2],
      n = 1000)
title("Density of the\n Hyperbolic Distribution")
curve(phyperb(x, param = param), from = hyperbRange[1], to = hyperbRange[2],
      n = 1000)
title("Distribution Function of the\n Hyperbolic Distribution")
dataVector <- rhyperb(500, param = param)
curve(dhyperb(x, param = param), 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, param = param)), add = TRUE,
      range(dataVector)[1], range(dataVector)[2], n = 500)
par(mfrow = c(2, 1))
curve(dhyperb(x, param = param), from = hyperbRange[1], to = hyperbRange[2],
      n = 1000)
title("Density of the\n Hyperbolic Distribution")
curve(ddhyperb(x, param = param), 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(param = param, tol = 10^(-6))
curve(dhyperb(x, param = param), from = hyperbRange[1], to = hyperbRange[2],
      n = 1000)
bks <- hyperbBreaks(param = param)
abline(v = bks)

sjp/GeneralizedHyperbolic documentation built on May 30, 2019, 12:06 a.m.