VarianceGamma (version 0.4-2)

VarianceGammaDistribution: The Variance Gamma Distribution

Description

Density function, distribution function, quantiles and random number generation for the variance gamma distribution with parameters \(c\) (location), \(\sigma\) (spread), \(\theta\) (asymmetry) and \(\nu\) (shape). 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

dvg(x, vgC = 0, sigma = 1, theta = 0, nu = 1,
    param = c(vgC,sigma,theta,nu), log = FALSE,
    tolerance = .Machine$double.eps ^ 0.5, ...)
  pvg(q, vgC = 0, sigma = 1, theta = 0, nu = 1,
    param = c(vgC,sigma,theta,nu), lower.tail = TRUE, log.p = FALSE,
    small = 10^(-6), tiny = 10^(-10), deriv = 0.3, subdivisions = 100,
    accuracy = FALSE, ...)
  qvg(p, vgC = 0, sigma = 1, theta = 0, nu = 1,
    param = c(vgC,sigma,theta,nu), lower.tail = TRUE, log.p = FALSE,
    small = 10^(-6), tiny = 10^(-10), deriv = 0.3, nInterpol = 100,
    subdivisions = 100, ...)
  rvg(n, vgC = 0, sigma = 1, theta = 0, nu = 1,
    param = c(vgC,sigma,theta,nu))
  ddvg (x,  vgC = 0, sigma = 1, theta = 0, nu = 1,
    param = c(vgC,sigma,theta,nu), log = FALSE,
    tolerance = .Machine$double.eps ^ 0.5, ...)
  vgBreaks (vgC = 0, sigma = 1, theta = 0, nu = 1,
    param = c(vgC,sigma,theta,nu), small = 10^(-6), tiny = 10^(-10),
    deriv = 0.3, ...)

Value

dvg gives the density function, pvg gives the distribution function, qvg gives the quantile function and rvg

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 pvg which then returns a list with components value and error.

ddvg gives the derivative of dvg.

vgBreaks 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 variance gamma distribution.

Arguments

x,q

Vector of quantiles.

p

Vector of probabilities.

n

Number of observations to be generated.

vgC

The location parameter \(c\), default is 0.

sigma

The spread parameter \(\sigma\), default is 1, must be positive.

theta

The asymmetry parameter \(\theta\), default is 0.

nu

The shape parameter \(\nu\), default is 1, must be positive.

param

Specifying the parameters as a vector which takes the form c(vgC,sigma,theta,nu).

log, log.p

Logical; if TRUE, probabilities p are given as log(p); not yet implemented.

lower.tail

If TRUE (default), probabilities are \(P[X <= x]\), otherwise, \(P[X > x]\); not yet implemented.

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 qvg for cubic spline interpolation (see splinefun) of the distribution function.

tolerance

Size of a machine difference between two values. See Details.

...

Passes arguments to uniroot. See Details.

Author

David Scott , Christine Yang Dong

Details

Users may either specify the values of the parameters individually or as a vector. If both forms are specifed but with different values, then the values specified by vector param will always overwrite the other ones.

The variance gamma distribution has density

$$f(x)=c(c,\sigma,\theta,\nu)\times% {e^{[\theta(x-c)/\sigma^2]}}% {|x-c|^{1/\nu-1/2}}% {K_{1/\nu-1/2}}% \left(\frac{|x-c|\sqrt{2\sigma^2/\nu+\theta^2}}% {\sigma^2}\right)$$

where \(K_\nu()\) is the modified Bessel function of the third kind of order \(\nu\), and $$c(c,\sigma,\theta,\nu)=% \frac{2}% {\sigma\sqrt{2\pi}\nu^{1/\nu}\Gamma(1/\nu)}% \left(\frac{1}% {\sqrt{2\sigma^2/\nu+\theta^2}}\right) ^{1/\nu-1/2}$$

Special cases:

1. If \(\nu < 2\) and \(x = c\), then the density function is approximate to $$f(x)= \frac{\Gamma(1/\nu-1/2)}% {\sigma\sqrt{2\pi}\nu^{1/\nu}\Gamma(1/\nu)}% \left(\frac{2\sigma^2}% {\sqrt{2\sigma^2/\nu+\theta^2}}\right) ^{1/\nu-1/2}$$

2. If \(\nu\geq2\) and \(x = c\), then the density function is taken the value Inf.

Use vgChangePars to convert from the \((\mu, \sigma, \theta, \tau)\), or \((\theta, \sigma, \kappa, \tau)\) parameterisations given in Kotz et al. (2001) to the \((c, \sigma, \theta, \nu)\) parameterisation used above.

pvg breaks the real line into eight regions in order to determine the integral of dvg. The break points determining the regions are found by vgBreaks, based on the values of small, tiny, and deriv. In the extreme tails of the distribution where the probability is tiny according to vgCalcRange, the probability is taken to be zero. In the inner part of the distribution, the range is divided in 6 regions, 3 above the mode, and 3 below. On each side of the mode, there are two break points giving the required three regions. The outer break point is where the probability in the tail has the value given by the variable small. The inner break point 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 6 inner regions the numerical integration routine safeIntegrate (which is a wrapper for integrate) is used to integrate the density dvg.

qvg uses the breakup of the real line into the same 8 regions as pvg. For quantiles which fall in the 2 extreme regions, the quantile is returned as -Inf or Inf as appropriate. In the 6 inner regions splinefun is used to fit values of the distribution function generated by pvg. The quantiles are then found using the uniroot function.

pvg and qvg may generally be expected to be accurate to 5 decimal places.

The variance gamma distribution is discussed in Kotz et al (2001). It can be seen to be the weighted difference of two i.i.d. gamma variables shifted by the value of \(\theta\). rvg uses this representation to generate oberservations from the variance gamma distribution.

References

Seneta, E. (2004). Fitting the variance-gamma model to financial data. J. Appl. Prob., 41A:177--187. Kotz, S, Kozubowski, T. J., and Podgórski, K. (2001). The Laplace Distribution and Generalizations. Birkhauser, Boston, 349 p.

See Also

vgChangePars, vgCalcRange

Examples

## Use the following rules for vgCalcRange when plotting graphs for dvg,
## ddvg and pvg.
## if nu < 2, use:
##   maxDens <- dvg(vgMode(param = c(vgC, sigma, theta, nu)),
##   param = c(vgC, sigma, theta, nu), log = FALSE)
##   vgRange <- vgCalcRange(param = c(vgC, sigma, theta, nu),
##     tol = 10^(-2)*maxDens, density = TRUE)

## if nu >= 2 and theta < 0, use:
##   vgRange <- c(vgC-2,vgC+6)
## if nu >= 2 and theta > 0, use:
##   vgRange <- c(vgC-6,vgC+2)
## if nu >= 2 and theta = 0, use:
##   vgRange <- c(vgC-4,vgC+4)

# Example 1 (nu < 2)
## For dvg and pvg
param <- c(0,0.5,0,0.5)
maxDens <- dvg(vgMode(param = param), param = param, log = FALSE)
## Or to specify parameter values individually, use:
maxDens <- dvg(vgMode(0,0.5,0,0.5), 0,0.5,0,0.5, log = FALSE)

vgRange <- vgCalcRange(param = param, tol = 10^(-2)*maxDens, density = TRUE)
par(mfrow = c(1,2))
curve(dvg(x, param = param), from = vgRange[1], to = vgRange[2], n = 1000)
title("Density of the Variance Gamma Distribution")
curve(pvg(x, param = param), from = vgRange[1], to = vgRange[2], n = 1000)
title("Distribution Function of the Variance Gamma Distribution")

## For rvg
require(DistributionUtils)
dataVector <- rvg(500, param = param)
curve(dvg(x, param = param), range(dataVector)[1], range(dataVector)[2],
      n = 500)
hist(dataVector, freq = FALSE, add = TRUE)
title("Density and Histogram of the Variance Gamma Distribution")
logHist(dataVector, main =
   "Log-Density and Log-Histogram of the Generalized Hyperbolic Distribution")
curve(log(dvg(x, param = param)), add = TRUE,
      range(dataVector)[1], range(dataVector)[2], n = 500)

## For dvg and ddvg
par(mfrow = c(2,1))
curve(dvg(x, param = param), from = vgRange[1], to = vgRange[2],
      n = 1000)
title("Density of the Variance Gamma Distribution")
curve(ddvg(x, param = param), from = vgRange[1], to = vgRange[2],
      n = 1000)
title("Derivative of the Density of the Variance Gamma Distribution")

# Example 2 (nu > 2 and theta = 0)
## For dvg and pvg
param <- c(0,0.5,0,3)
vgRange <- c(0-4,0+4)
par(mfrow = c(1,2))
curve(dvg(x, param = param), from = vgRange[1], to = vgRange[2],
      n = 1000)
title("Density of the Variance Gamma Distribution")
curve(pvg(x, param = param), from = vgRange[1], to = vgRange[2],
      n = 1000)
title("Distribution Function of the Variance Gamma Distribution")

## For rvg
X2 <- rvg(500, param = param)
curve(dvg(x, param = param), min(X2), max(X2), n = 500)
hist(X2, freq = FALSE, add =TRUE)
title("Density and Histogram of the Variance Gamma Distribution")
DistributionUtils::logHist(X2, main =
   "Log-Density and Log-Histogramof the Generalized Hyperbolic Distribution")
curve(log(dvg(x, param = param)), add = TRUE, min(X2), max(X2), n = 500)

## For dvg and ddvg
par(mfrow = c(2,1))
curve(dvg(x, param = param), from = vgRange[1], to = vgRange[2],
      n = 1000)
title("Density of the Variance Gamma Distribution")
curve(ddvg(x, param = param), from = vgRange[1], to = vgRange[2],
      n = 1000)
title("Derivative of the Density of the Variance Gamma Distribution")



## Use the following rules for vgCalcRange when plotting graphs for vgBreaks.
## if (nu < 2), use:
##   maxDens <- dvg(vgMode(param =c(vgC, sigma, theta, nu)),
##     param = c(vgC, sigma, theta, nu), log = FALSE)
##   vgRange <- vgCalcRange(param = param, tol = 10^(-6)*maxDens, density = TRUE)
## if (nu >= 2) and theta < 0, use:
##    vgRange <- c(vgC-2,vgC+6)
## if (nu >= 2) and theta > 0, use:
##    vgRange <- c(vgC-6,vgC+2)
## if (nu >= 2) and theta = 0, use:
##    vgRange <- c(vgC-4,vgC+4)

## Example 3 (nu < 2)
## For vgBreaks
param <- c(0,0.5,0,0.5)
maxDens <- dvg(vgMode(param = param), param = param, log = FALSE)
vgRange <- vgCalcRange(param = param, tol = 10^(-6)*maxDens, density = TRUE)
curve(dvg(x, param = param), from = vgRange[1], to = vgRange[2],
      n = 1000)
bks <- vgBreaks(param = param)
abline(v = bks)
title("Density of the Variance Gamma Distribution with breaks")

## Example 4 (nu > 2 and theta = 0)
## For vgBreaks
param <- c(0,0.5,0,3)
vgRange <- c(0-4,0+4)
curve(dvg(x, param = param), from = vgRange[1], to = vgRange[2],
      n = 1000)
bks <- vgBreaks(param = param)
abline(v = bks)
title("Density of the Variance Gamma Distribution with breaks")