SkewHyperbolicDistribution {SkewHyperbolic}R Documentation

Skewed Hyperbolic Student t-Distribution

Description

Density function, distribution function, quantiles and random number generation for the skew hyperbolic Student t-distribution, with parameters beta (skewness), delta (scale), mu (location) and nu (shape). Also functions for the derivative of the distribution, and to calculate suitable break points.

Usage

dskewhyp(x, mu = 0, delta = 1, beta = 1, nu = 1,
         param = c(mu,delta,beta,nu), log = FALSE,
         tolerance = .Machine$double.eps^0.5)
pskewhyp(q, mu = 0, delta = 1, beta = 1, nu = 1,
         param = c(mu,delta,beta,nu), log = FALSE, lower.tail = TRUE,
         small = 10^(-6), tiny = 10^(-10), subdivisions = 100,
         accuracy = FALSE, ...)
qskewhyp(p, mu = 0, delta = 1, beta = 1, nu = 1,
         param = c(mu,delta,beta,nu), small = 10^(-6), tiny = 10^(-10),
         deriv = 0.3, nInterpol = 100, subdivisions = 100, ...)
rskewhyp(n, mu = 0, delta = 1, beta = 1, nu = 1,
         param = c(mu,delta,beta,nu), log = FALSE)
ddskewhyp(x, mu = 0, delta = 1, beta = 1, nu = 1,
          param = c(mu,delta,beta,nu),log = FALSE,
          tolerance = .Machine$double.eps ^ 0.5)
skewhypBreaks(mu = 0, delta = 1, beta = 1, nu = 1,
              param = c(mu,delta,beta,nu), small = 10^(-6),
              tiny = 10^(-10), deriv = 0.3, ...)

Arguments

x,q Vector of quantiles.
p Vector of probabilities.
n Number of random variates to be generated.
mu Location parameter mu, default is 0.
delta Scale parameter delta, default is 1.
beta Skewness parameter beta, default is 1.
nu Shape parameter nu, default is 1.
param Specifying the parameters as a vector of the form
c(mu,delta,beta,nu).
log Logical; if log = TRUE, probabilities are given as log(p).
lower.tail Logical; if lower.tail = TRUE, the cumulative density is taken from the lower tail.
tolerance Specified level of tolerance when checking if parameter beta is equal to 0.
small Size of a 'small' difference between the distribution function and 0 or 1.
tiny Size of a 'tiny' difference between the distribution function and 0 or 1.
subdivisions The maximum number of subdivisions used to integrate the density and determine the accuracy of the distribution function calculation.
accuracy Logical; if accuracy = TRUE, uses accuracy calculated by integrate to try and determine the accuracy of the distribution function calculation.
deriv Value between 0 and 1 which determines the point at which the value of the derivative becomes substantial compared to its maximal value, see Details.
nInterpol Number of points used in qskewhyp for cubic spline interpolation of the distribution function.
... Passes additional arguments to integrate in pskewhyp and qskewhyp, and to uniroot in skewhypBreaks.

Details

Users may either specify the values of the parameters individually or as a vector. If both forms are specified, then the values specified by the vector param will overwrite the other ones. In addition the parameter values are examined by calling the function skewhypCheckPars to see if they are valid.

The density function is

f(x) = (2^((1-nu)/2) delta^nu abs(beta)^((nu+1)/2) K_((nu+1)/2)(sqrt(beta^2 (delta^2+(x-mu)^2)) ) exp(beta (x-mu)))/ (gamma(nu/2) sqrt(pi) (sqrt(delta^2+(x-mu)^2))^((nu+1)/2))

when beta != 0, and

f(x)=(gamma((nu+1)/2)/(sqrt(pi) delta gamma(nu/2)))(1+((x-mu)^2)/(delta^2))^(-(nu+1)/2)

when beta = 0, where K_nu(.) is the modified Bessel function of the third kind with order nu, and gamma(.) is the gamma function.

pskewhyp breaks the real line in to 8 regions in order to determine the integral of dhyperb. The breakpoints determining the regions are calculated by skewhypBreaks, based on the values of small, tiny, and deriv.

The outer breakpoints, xTiny, xHuge, xSmall and xLarge and are calculated by calls to skewhypCalcRange, using the value tiny for the first two most extreme values, and small for the next two. The inner area is divided into two regions above and two below the mode. The breakpoint that divides these is calculated to be the point where the derivative of the density function is deriv times the value of the maximum derivative on that side of the mode. In the extreme tails of the distribution where the density is less than tiny the density is taken to be zero. In the remaining regions the integral of the density is calculated using the numerical routine safeIntegrate (a wrapper for integrate).

qhyperb uses the same breakup of the real line as pskewhyp. For quantiles that fall in the two extreme regions the quantile is returned as Inf or -Inf as appropriate. In the remaining regions splinefun is used to fit values of the distribution function calculated by pskewhyp. The quantiles are then found by the uniroot function.

Note that when small values of nu are used, and the density is skewed, there are often some extreme values generated by rskewhyp. These look like outliers, but are caused by the heaviness of the skewed tail, see Examples.

Value

dskewhyp gives the density function, pskewhyp gives the distribution function, qskewhyp gives the quantile function and rskewhyp generates random variates.
An estimate of the accuracy of the approximation to the distribution function can be found by setting accuracy = TRUE in the call to pskewyhp which returns a list with components value and error.
ddskewhyp gives the derivative of dskewhyp.
skewhypBreaks returns a list with components:

xTiny Value such that the probabilities to the left are less than tiny.
xSmall Value such that probabilities to the left are less than small.
lowBreak Point to the left of the mode such that the derivative of the density at that point 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 at that point is deriv times the value of the maximum value on that side of the mode.
xLarge Value such that the probabities to the right are less than xSmall.
xHuge Value such that probability to the right is less than tiny.
modeDist The mode of the given skewed hyperbolic distribution, calculated by skewhypMode.

Author(s)

David Scott d.scott@auckland.ac.nz, Fiona Grimson

References

Aas, K. and Haff, I. H. (2006). The Generalised Hyperbolic Skew Student's t-distribution, Journal of Financial Econometrics, 4, 275–309.

See Also

safeIntegrate, integrate for its shortfalls, skewhypBreaks, skewhypCheckPars, logHist. Also skewhypMean for information on moments and mode, and skewhypFit for fitting to data.

Examples

param <- c(0,1,40,10)
par(mfrow = c(1,2))
range <- skewhypCalcRange(param = param, tol = 10^(-2))

##curves of density and distribution
curve(dskewhyp(x, param = param), range[1], range[2], n = 1000)
title("Density of the \n Skew Hyperbolic Distribution")
curve(pskewhyp(x, param = param, small = 10^(-2), tiny = 10^(-4)),
      range[1], range[2], n = 500)
title("Distribution Function of the \n Skew Hyperbolic Distribution")

##curves of density and log density
par(mfrow = c(1,2))
data <- rskewhyp(1000, param = param)
curve(dskewhyp(x, param = param), range(data)[1], range(data)[2],
      n = 1000, col = 2)
hist(data, freq = FALSE, add = TRUE)
title("Density and Histogram of the\n Skew Hyperbolic Distribution")
logHist(data, main = "Log-Density and Log-Histogram of\n the Skew
      Hyperbolic Distribution")
curve(dskewhyp(x, param = param, log = TRUE),
      range(data)[1], range(data)[2],
      n = 500, add = TRUE, col = 2)

##plots of density and derivative
par(mfrow = c(2,1))
curve(dskewhyp(x, param = param), range[1], range[2], n = 1000)
title("Density of the Skew\n Hyperbolic Distribution")
curve(ddskewhyp(x, param = param), range[1], range[2], n = 1000)
title("Derivative of the Density\n of the Skew Hyperbolic Distribution")

##plot of the density marking the break points
par(mfrow = c(1,1))
range <- skewhypCalcRange(param = param, tol = 10^(-6))
curve(dskewhyp(x, param = param), range[1], range[2], n = 1000)
title("Density of the Skew Hyperbolic Distribution\n with Breakpoints")
breaks <- skewhypBreaks(param = param, small = 10^(-2), tiny = 10^(-4))
abline(v = breaks, col = 2)

##example of density and random numbers when nu is small
par(mfrow = c(1,2))
param1 <- c(0,1,10,1)
data1 <- rskewhyp(1000, param = param1)
curve(dskewhyp(x, param = param1), range(data1)[1], range(data1)[2],
      n = 1000, col = 2)
hist(data1, freq = FALSE, add = TRUE)
title("Density and Histogram\n when nu is small")
logHist(data1, main = "Log-Density and Log-Histogram\n when nu is small")
curve(dskewhyp(x, param = param1, log = TRUE),
      range(data1)[1], range(data1)[2],
      n = 500, add = TRUE, col = 2)

[Package SkewHyperbolic version 0.1-2 Index]