Package 'mggd'

Title: Multivariate Generalised Gaussian Distribution; Kullback-Leibler Divergence
Description: Distance between multivariate generalised Gaussian distributions, as presented by N. Bouhlel and A. Dziri (2019) <doi:10.1109/LSP.2019.2915000>. Manipulation of multivariate generalised Gaussian distributions (methods presented by Gomez, Gomez-Villegas and Marin (1998) <doi:10.1080/03610929808832115> and Pascal, Bombrun, Tourneret and Berthoumieu (2013) <doi:10.1109/TSP.2013.2282909>).
Authors: Pierre Santagostini [aut, cre], Nizar Bouhlel [aut]
Maintainer: Pierre Santagostini <[email protected]>
License: GPL (>= 3)
Version: 1.3.1
Built: 2024-11-03 03:34:52 UTC
Source: https://github.com/cran/mggd

Help Index

Tools for Multivariate Generalized Gaussian Distributions

Description

This package provides tools for multivariate generalized Gaussian distributions (MGGD):

  • Calculation of distances/divergences between multivariate generalized Gaussian distributions:

    • Kullback-Leibler divergence: kldggd

  • Tools for MGGD:

Author(s)

Pierre Santagostini [email protected], Nizar Bouhlel [email protected]

References

N. Bouhlel, A. Dziri, Kullback-Leibler Divergence Between Multivariate Generalized Gaussian Distributions. IEEE Signal Processing Letters, vol. 26 no. 7, July 2019. doi:10.1109/LSP.2019.2915000

E. Gomez, M. Gomez-Villegas, H. Marin. A Multivariate Generalization of the Power Exponential Family of Distribution. Commun. Statist. 1998, Theory Methods, col. 27, no. 23, p 589-600. doi:10.1080/03610929808832115

F. Pascal, L. Bombrun, J.Y. Tourneret, Y. Berthoumieu. Parameter Estimation For Multivariate Generalized Gaussian Distribution. IEEE Trans. Signal Processing, vol. 61 no. 23, p. 5960-5971, Dec. 2013. doi:10.1109/TSP.2013.2282909 #' @keywords internal

See Also

Useful links:

Contour Plot of the Bivariate Generalised Gaussian Density

Description

Draws the contour plot of the probability density of the generalised Gaussian distribution with 2 variables with mean vector mu, dispersion matrix Sigma and shape parameter beta.

Usage

contourmggd(mu, Sigma, beta,
                    xlim = c(mu[1] + c(-10, 10)*Sigma[1, 1]),
                    ylim = c(mu[2] + c(-10, 10)*Sigma[2, 2]),
                    zlim = NULL, npt = 30, nx = npt, ny = npt,
                    main = "Multivariate generalised Gaussian density",
                    sub = NULL, nlevels = 10,
                    levels = pretty(zlim, nlevels), tol = 1e-6, ...)

Arguments

mu

length 2 numeric vector.
Sigma

symmetric, positive-definite square matrix of order 2. The dispersion matrix.
beta

positive real number. The shape of the first distribution.
xlim, ylim

x-and y- limits.
zlim

z- limits. If NULL, it is the range of the values of the density on the x and y values within xlim and ylim.
npt

number of points for the discretisation.
nx, ny

number of points for the discretisation among the x- and y- axes.
main, sub

main and sub title, as for title.
nlevels, levels

arguments to be passed to the contour function.
tol

tolerance (relative to largest variance) for numerical lack of positive-definiteness in Sigma, for the estimation of the density. see dmggd.
...

additional arguments to plot.window, title, Axis and box, typically graphical parameters such as cex.axis.

Value

Returns invisibly the probability density function.

Author(s)

Pierre Santagostini, Nizar Bouhlel

References

E. Gomez, M. Gomez-Villegas, H. Marin. A Multivariate Generalization of the Power Exponential Family of Distribution. Commun. Statist. 1998, Theory Methods, col. 27, no. 23, p 589-600. doi:10.1080/03610929808832115

See Also

plotmggd: plot of a bivariate generalised Gaussian density.

dmggd: Probability density of a multivariate generalised Gaussian distribution.

Examples

mu <- c(1, 4)
Sigma <- matrix(c(0.8, 0.2, 0.2, 0.2), nrow = 2)
beta <- 0.74
contourmggd(mu, Sigma, beta)

Density of a Multivariate Generalized Gaussian Distribution

Description

Density of the multivariate (pp variables) generalized Gaussian distribution (MGGD) with mean vector mu, dispersion matrix Sigma and shape parameter beta.

Usage

dmggd(x, mu, Sigma, beta, tol = 1e-6)

Arguments

x

length pp numeric vector.
mu

length pp numeric vector. The mean vector.
Sigma

symmetric, positive-definite square matrix of order pp. The dispersion matrix.
beta

positive real number. The shape of the distribution.
tol

tolerance (relative to largest variance) for numerical lack of positive-definiteness in Sigma.

Details

The density function of a multivariate generalized Gaussian distribution is given by:

f(x∣μ,Σ,β)=Γ(p2)πp2Γ(p2β)2p2ββ∣Σ∣12e−12((x−μ)TΣ−1(x−μ))β\displaystyle{ f(\mathbf{x}|\boldsymbol{\mu}, \Sigma, \beta) = \frac{\Gamma\left(\frac{p}{2}\right)}{\pi^\frac{p}{2} \Gamma\left(\frac{p}{2 \beta}\right) 2^\frac{p}{2\beta}} \frac{\beta}{|\Sigma|^\frac{1}{2}} e^{-\frac{1}{2}\left((\mathbf{x}-\boldsymbol{\mu})^T \Sigma^{-1} (\mathbf{x}-\boldsymbol{\mu})\right)^\beta} }

When p=1p=1 (univariate case) it becomes:

f(x∣μ,σ,β)=Γ(12)π12Γ(12β)212ββσ12 e−12((x−μ)22σ)β=βΓ(12β)212βσ e−12((x−μ)2σ)β\displaystyle{ f(x|\mu, \sigma, \beta) = \frac{\Gamma\left(\frac{1}{2}\right)}{\pi^\frac{1}{2} \Gamma\left(\frac{1}{2 \beta}\right) 2^\frac{1}{2\beta}} \frac{\beta}{\sigma^\frac{1}{2}} \ e^{-\frac{1}{2} \left(\frac{(x - \mu)^2}{2 \sigma}\right)^\beta} = \frac{\beta}{\Gamma\left(\frac{1}{2 \beta}\right) 2^\frac{1}{2 \beta} \sqrt{\sigma}} \ e^{-\frac{1}{2} \left(\frac{(x - \mu)^2}{\sigma}\right)^\beta} }

Value

The value of the density.

Author(s)

Pierre Santagostini, Nizar Bouhlel

References

E. Gomez, M. Gomez-Villegas, H. Marin. A Multivariate Generalization of the Power Exponential Family of Distribution. Commun. Statist. 1998, Theory Methods, col. 27, no. 23, p 589-600. doi:10.1080/03610929808832115

See Also

rmggd: random generation from a MGGD.

estparmggd: estimation of the parameters of a MGGD.

plotmggd, contourmggd: plot of the probability density of a bivariate generalised Gaussian distribution.

Examples

mu <- c(0, 1, 4)
Sigma <- matrix(c(0.8, 0.3, 0.2, 0.3, 0.2, 0.1, 0.2, 0.1, 0.2), nrow = 3)
beta <- 0.74
dmggd(c(0, 1, 4), mu, Sigma, beta)
dmggd(c(1, 2, 3), mu, Sigma, beta)

Estimation of the Parameters of a Multivariate Generalized Gaussian Distribution

Description

Estimation of the mean vector, dispersion matrix and shape parameter of a multivariate generalized Gaussian distribution (MGGD).

Usage

estparmggd(x, eps = 1e-6, display = FALSE, plot = display)

Arguments

x

numeric matrix or data frame.
eps

numeric. Precision for the estimation of the beta parameter.
display

logical. When TRUE the value of the beta parameter at each iteration is printed.
plot

logical. When TRUE the successive values of the beta parameter are plotted, allowing to visualise its convergence.

Details

The μ\mu parameter is the mean vector of x.

The dispersion matrix Σ\Sigma and shape parameter: β\beta are computed using the method presented in Pascal et al., using an iterative algorithm.

The precision for the estimation of beta is given by the eps parameter.

Value

A list of 3 elements:

  • mu the mean vector.

  • Sigma: symmetric positive-definite matrix. The dispersion matrix.

  • beta non-negative numeric value. The shape parameter.

with two attributes attr(, "epsilon") (precision of the result) and attr(, "k") (number of iterations).

Author(s)

Pierre Santagostini, Nizar Bouhlel

References

F. Pascal, L. Bombrun, J.Y. Tourneret, Y. Berthoumieu. Parameter Estimation For Multivariate Generalized Gaussian Distribution. IEEE Trans. Signal Processing, vol. 61 no. 23, p. 5960-5971, Dec. 2013. doi: 10.1109/TSP.2013.2282909

See Also

dmggd: probability density of a MGGD.

rmggd: random generation from a MGGD.

Examples

mu <- c(0, 1, 4)
Sigma <- matrix(c(0.8, 0.3, 0.2, 0.3, 0.2, 0.1, 0.2, 0.1, 0.2), nrow = 3)
beta <- 0.74
x <- rmggd(100, mu, Sigma, beta)

# Estimation of the parameters
estparmggd(x)

Kullback-Leibler Divergence between Centered Multivariate generalized Gaussian Distributions

Description

Computes the Kullback- Leibler divergence between two random variables distributed according to multivariate generalized Gaussian distributions (MGGD) with zero means.

Usage

kldggd(Sigma1, beta1, Sigma2, beta2, eps = 1e-06)

Arguments

Sigma1

symmetric, positive-definite matrix. The dispersion matrix of the first distribution.
beta1

positive real number. The shape parameter of the first distribution.
Sigma2

symmetric, positive-definite matrix. The dispersion matrix of the second distribution.
beta2

positive real number. The shape parameter of the second distribution.
eps

numeric. Precision for the computation of the Lauricella function (see lauricella). Default: 1e-06.

Details

Given X1\mathbf{X}_1, a random vector of Rp\mathbb{R}^p (p>1p > 1) distributed according to the MGGD with parameters (0,Σ1,β1)(\mathbf{0}, \Sigma_1, \beta_1) and X2\mathbf{X}_2, a random vector of Rp\mathbb{R}^p distributed according to the MGGD with parameters (0,Σ2,β2)(\mathbf{0}, \Sigma_2, \beta_2).

The Kullback-Leibler divergence between X1X_1 and X2X_2 is given by:

KL(X1∣∣X2)=ln⁡(β1∣Σ1∣−1/2Γ(p2β2)β2∣Σ2∣−1/2Γ(p2β1))+p2(1β2−1β1)ln⁡2−p2β2+2β2β1−1Γ(β2β1+pβ1)Γ(p2β1)λpβ2\displaystyle{ KL(\mathbf{X}_1||\mathbf{X}_2) = \ln{\left(\frac{\beta_1 |\Sigma_1|^{-1/2} \Gamma\left(\frac{p}{2\beta_2}\right)}{\beta_2 |\Sigma_2|^{-1/2} \Gamma\left(\frac{p}{2\beta_1}\right)}\right)} + \frac{p}{2} \left(\frac{1}{\beta_2} - \frac{1}{\beta_1}\right) \ln{2} - \frac{p}{2\beta_2} + 2^{\frac{\beta_2}{\beta_1}-1} \frac{\Gamma{\left(\frac{\beta_2}{\beta_1} + \frac{p}{\beta_1}\right)}}{\Gamma{\left(\frac{p}{2 \beta_1}\right)}} \lambda_p^{\beta_2} }

×FD(p−1)(−β1;12,…,12⏟p−1;p2;1−λp−1λp,…,1−λ1λp)\displaystyle{ \times F_D^{(p-1)}\left(-\beta_1; \underbrace{\frac{1}{2},\dots,\frac{1}{2}}_{p-1}; \frac{p}{2}; 1-\frac{\lambda_{p-1}}{\lambda_p},\dots,1-\frac{\lambda_{1}}{\lambda_p}\right) }

where λ1<...<λp−1<λp\lambda_1 < ... < \lambda_{p-1} < \lambda_p are the eigenvalues of the matrix Σ1Σ2−1\Sigma_1 \Sigma_2^{-1}
and FD(p−1)F_D^{(p-1)} is the Lauricella DD-hypergeometric Function.

This computation uses the lauricella function.

When p=1p = 1 (univariate case): let X1X_1, a random variable distributed according to the generalized Gaussian distribution with parameters (0,σ1,β1)(0, \sigma_1, \beta_1) and X2X_2, a random variable distributed according to the generalized Gaussian distribution with parameters (0,σ2,β2)(0, \sigma_2, \beta_2).

KL(X1∣∣X2)=ln⁡(β1σ1Γ(12β2)β2σ2Γ(12β1))+12(1β2−1β1)ln⁡2−12β2+2β2β1−1Γ(β2β1+1β1)Γ(12β1)(σ1σ2)β2KL(X_1||X_2) = \displaystyle{ \ln{\left(\frac{\frac{\beta_1}{\sqrt{\sigma_1}} \Gamma\left(\frac{1}{2\beta_2}\right)}{\frac{\beta_2}{\sqrt{\sigma_2}} \Gamma\left(\frac{1}{2\beta_1}\right)}\right)} + \frac{1}{2} \left(\frac{1}{\beta_2} - \frac{1}{\beta_1}\right) \ln{2} - \frac{1}{2\beta_2} + 2^{\frac{\beta_2}{\beta_1}-1} \frac{\Gamma{\left(\frac{\beta_2}{\beta_1} + \frac{1}{\beta_1}\right)}}{\Gamma{\left(\frac{1}{2 \beta_1}\right)}} \left(\frac{\sigma_1}{\sigma_2}\right)^{\beta_2} }

Value

A numeric value: the Kullback-Leibler divergence between the two distributions, with two attributes attr(, "epsilon") (precision of the result of the Lauricella function; 0 if the distributions are univariate) and attr(, "k") (number of iterations).

Author(s)

Pierre Santagostini, Nizar Bouhlel

References

N. Bouhlel, A. Dziri, Kullback-Leibler Divergence Between Multivariate Generalized Gaussian Distributions. IEEE Signal Processing Letters, vol. 26 no. 7, July 2019. doi:10.1109/LSP.2019.2915000

See Also

dmggd: probability density of a MGGD.

Examples

beta1 <- 0.74
beta2 <- 0.55
Sigma1 <- matrix(c(0.8, 0.3, 0.2, 0.3, 0.2, 0.1, 0.2, 0.1, 0.2), nrow = 3)
Sigma2 <- matrix(c(1, 0.3, 0.2, 0.3, 0.5, 0.1, 0.2, 0.1, 0.7), nrow = 3)

# Kullback-Leibler divergence
kl12 <- kldggd(Sigma1, beta1, Sigma2, beta2)
kl21 <- kldggd(Sigma2, beta2, Sigma1, beta1)
print(kl12)
print(kl21)

# Distance (symmetrized Kullback-Leibler divergence)
kldist <- as.numeric(kl12) + as.numeric(kl21)
print(kldist)

Lauricella DD-Hypergeometric Function

Description

Computes the Lauricella DD-hypergeometric Function function.

Usage

lauricella(a, b, g, x, eps = 1e-06)

Arguments

a

numeric.
b

numeric vector.
g

numeric.
x

numeric vector. x must have the same length as b.
eps

numeric. Precision for the nested sums (default 1e-06).

Details

If nn is the length of the bb and x vectors, the Lauricella DD-hypergeometric Function function is given by:

FD(n)(a,b1,...,bn,g;x1,...,xn)=∑m1≥0...∑mn≥0(a)m1+...+mn(b1)m1...(bn)mn(g)m1+...+mnx1m1m1!...xnmnmn!\displaystyle{F_D^{(n)}\left(a, b_1, ..., b_n, g; x_1, ..., x_n\right) = \sum_{m_1 \geq 0} ... \sum_{m_n \geq 0}{ \frac{ (a)_{m_1+...+m_n}(b_1)_{m_1} ... (b_n)_{m_n} }{ (g)_{m_1+...+m_n} } \frac{x_1^{m_1}}{m_1!} ... \frac{x_n^{m_n}}{m_n!} } }

where (x)p(x)_p is the Pochhammer symbol (see pochhammer).

If ∣xi∣<1,i=1,…,n|x_i| < 1, i = 1, \dots, n, this sum converges. Otherwise there is an error.

The eps argument gives the required precision for its computation. It is the attr(, "epsilon") attribute of the returned value.

Sometimes, the convergence is too slow and the required precision cannot be reached. If this happens, the attr(, "epsilon") attribute is the precision that was really reached.

Value

A numeric value: the value of the Lauricella function, with two attributes attr(, "epsilon") (precision of the result) and attr(, "k") (number of iterations).

Author(s)

Pierre Santagostini, Nizar Bouhlel

References

N. Bouhlel, A. Dziri, Kullback-Leibler Divergence Between Multivariate Generalized Gaussian Distributions. IEEE Signal Processing Letters, vol. 26 no. 7, July 2019. doi:10.1109/LSP.2019.2915000

Logarithm of the Pochhammer Symbol

Description

Computes the logarithm of the Pochhammer symbol.

Usage

lnpochhammer(x, n)

Arguments

x

numeric.
n

positive integer.

Details

The Pochhammer symbol is given by:

(x)n=Γ(x+n)Γ(x)=x(x+1)...(x+n−1)\displaystyle{ (x)_n = \frac{\Gamma(x+n)}{\Gamma(x)} = x (x+1) ... (x+n-1) }

So, if n>0n > 0:

log((x)n)=log(x)+log(x+1)+...+log(x+n−1)\displaystyle{ log\left((x)_n\right) = log(x) + log(x+1) + ... + log(x+n-1) }

If n=0n = 0, log((x)n)=log(1)=0\displaystyle{ log\left((x)_n\right) = log(1) = 0}

Value

Numeric value. The logarithm of the Pochhammer symbol.

Author(s)

Pierre Santagostini, Nizar Bouhlel

See Also

pochhammer()

Examples

lnpochhammer(2, 0)
lnpochhammer(2, 1)
lnpochhammer(2, 3)

Plot of the Bivariate Generalised Gaussian Density

Description

Plots the probability density of the generalised Gaussian distribution with 2 variables with mean vector mu, dispersion matrix Sigma and shape parameter beta.

Usage

plotmggd(mu, Sigma, beta, xlim = c(mu[1] + c(-10, 10)*Sigma[1, 1]),
                 ylim = c(mu[2] + c(-10, 10)*Sigma[2, 2]), n = 101,
                 xvals = NULL, yvals = NULL, xlab = "x", ylab = "y",
                 zlab = "f(x,y)", col = "gray", tol = 1e-6, ...)

Arguments

mu

length 2 numeric vector.
Sigma

symmetric, positive-definite square matrix of order 2. The dispersion matrix.
beta

positive real number. The shape of the distribution.
xlim, ylim

x-and y- limits.
n

A one or two element vector giving the number of steps in the x and y grid, passed to plot3d.function.
xvals, yvals

The values at which to evaluate x and y. If used, xlim and/or ylim are ignored.
xlab, ylab, zlab

The axis labels.
col

The color to use for the plot. See plot3d.function.
tol

tolerance (relative to largest variance) for numerical lack of positive-definiteness in Sigma, for the estimation of the density. see dmggd.
...

Additional arguments to pass to plot3d.function.

Value

Returns invisibly the probability density function.

Author(s)

Pierre Santagostini, Nizar Bouhlel

References

E. Gomez, M. Gomez-Villegas, H. Marin. A Multivariate Generalization of the Power Exponential Family of Distribution. Commun. Statist. 1998, Theory Methods, col. 27, no. 23, p 589-600. doi:10.1080/03610929808832115

See Also

contourmggd: contour plot of a bivariate generalised Gaussian density.

dmggd: Probability density of a multivariate generalised Gaussian distribution.

Examples

mu <- c(1, 4)
Sigma <- matrix(c(0.8, 0.2, 0.2, 0.2), nrow = 2)
beta <- 0.74
plotmggd(mu, Sigma, beta)

Pochhammer Symbol

Description

Computes the Pochhammer symbol.

Usage

pochhammer(x, n)

Arguments

x

numeric.
n

positive integer.

Details

The Pochhammer symbol is given by:

(x)n=Γ(x+n)Γ(x)=x(x+1)...(x+n−1)\displaystyle{ (x)_n = \frac{\Gamma(x+n)}{\Gamma(x)} = x (x+1) ... (x+n-1) }

Value

Numeric value. The value of the Pochhammer symbol.

Author(s)

Pierre Santagostini, Nizar Bouhlel

Examples

pochhammer(2, 0)
pochhammer(2, 1)
pochhammer(2, 3)

Simulate from a Multivariate Generalized Gaussian Distribution

Description

Produces one or more samples from a multivariate (pp variables) generalized Gaussian distribution (MGGD).

Usage

rmggd(n = 1 , mu, Sigma, beta, tol = 1e-6)

Arguments

n

integer. Number of observations.
mu

length pp numeric vector. The mean vector.
Sigma

symmetric, positive-definite square matrix of order pp. The dispersion matrix.
beta

positive real number. The shape of the distribution.
tol

tolerance (relative to largest variance) for numerical lack of positive-definiteness in Sigma.

Details

A sample from a centered MGGD with dispersion matrix Σ\Sigma and shape parameter β\beta can be generated using:

X=τ Σ1/2 U\displaystyle{X = \tau \ \Sigma^{1/2} \ U}

where UU is a random vector uniformly distributed on the unit sphere and τ\tau is such that τ2β\tau^{2\beta} is generated from a distribution Gamma with shape parameter p2β\displaystyle{\frac{p}{2\beta}} and scale parameter 22.

This property is used to generate a sample from a MGGD.

Value

A matrix with pp columns and n rows.

Author(s)

Pierre Santagostini, Nizar Bouhlel

References

E. Gomez, M. Gomez-Villegas, H. Marin. A Multivariate Generalization of the Power Exponential Family of Distribution. Commun. Statist. 1998, Theory Methods, col. 27, no. 23, p 589-600. doi:10.1080/03610929808832115

See Also

dmggd: probability density of a MGGD..

estparmggd: estimation of the parameters of a MGGD.

Examples

mu <- c(0, 0, 0)
Sigma <- matrix(c(0.8, 0.3, 0.2, 0.3, 0.2, 0.1, 0.2, 0.1, 0.2), nrow = 3)
beta <- 0.74
rmggd(100, mu, Sigma, beta)