QuadraticFormsMGHyp

Tail probabilities and expected shortfalls of a quadratic form in a multivariate generalized hyperbolic vector. The import name matches the Julia package QuadraticFormsMGHyp.jl. The numerical work is a C routine. The Fortran and Matlab code for the paper is s-broda/es4mgh.

The API and the quadrature are documented separately.

The random variable

\[ L = a_0 + a^\top X + X^\top A X, \]

where \(X\) has the stochastic representation

\[ X = \mu + W \gamma + \sqrt{W}\, C Z. \]

\(Z\) is standard normal, \(\mu\) and \(\gamma\) are constant vectors, \(C\) is a square matrix, and \(W\) is generalized inverse Gaussian with density proportional to

\[ w^{\lambda - 1} \exp\left\{-\frac12\left(\chi w^{-1} + \psi w\right)\right\}. \]

Special cases include the variance-gamma law (\(\lambda > 0\)), Student’s \(t\) (\(\lambda = -\nu/2\), \(\chi = \nu\), \(\psi = 0\)), the normal-inverse Gaussian (\(\lambda = -1/2\)), and the hyperbolic law (\(\lambda = 1\)).

At a threshold \(x\) one evaluation returns \(\mathrm{P}(L \le x)\), \(\mathrm{P}(L > x)\), the upper partial moment \(\mathrm{E}[L 1_{L > x}]\), and the expected shortfall \(\mathrm{E}[L \mid L > x]\). The algorithm is the Gil-Pelaez inversion from Broda and Zambrano, Biometrika 108 (2021). It generalizes Imhof (1961) and Broda (2012).

Installation

pip install QuadraticFormsMGHyp

Python 3.9 or newer is required. Wheels cover Linux x86_64 and arm64 (manylinux and musllinux), macOS x86_64 and arm64, and Windows amd64. Windows arm64 wheels start at Python 3.11. NumPy is installed as a dependency.

A source install needs a C compiler and Python headers, because the extension is compiled on the machine. On macOS the build links Accelerate. On Windows it uses clang-cl from LLVM and the Microsoft linker. Install LLVM and the Microsoft C++ build tools.

pip install "git+https://github.com/s-broda/QuadraticFormsMGHyp-py.git"

From a checkout, pip install . does the same thing.

pip install ".[test]"   # pytest
pip install ".[docs]"   # this site
sphinx-build -b html docs docs/_build/html

Usage

Construct a QuadraticFormsMGHyp.QuadraticForm once. Each QuadraticFormsMGHyp.QuadraticForm.eval() integrates that grid once. QuadraticFormsMGHyp.QuadraticForm.from_spectral() skips the reduction and takes the eigenvalues and the two coefficient vectors directly.

import numpy as np
from QuadraticFormsMGHyp import QuadraticForm

qf = QuadraticForm(
    0.0,
    np.array([1.0]),
    np.zeros((1, 1)),
    np.ones((1, 1)),
    np.zeros(1),
    np.zeros(1),
    -0.5,
    1.0,
    1.0,
)
cdf, ccdf, pm, es = qf.eval(np.linspace(-1.0, 3.0, 5))

cdf is \(\mathrm{P}(L \le x)\) and ccdf is \(\mathrm{P}(L > x)\). pm is \(\mathrm{E}[L 1_{L > x}]\) and es is \(\mathrm{E}[L \mid L > x]\). A with block releases the C object.

Citation

Please cite Broda and Zambrano (2021). The repository contains CITATION.bib and CITATION.cff.

The package is released under the MIT License.