Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_stat_pdf_multi_normal_vector (g01lb)

## Purpose

nag_stat_pdf_multi_normal_vector (g01lb) returns a number of values of the probability density function (PDF), or its logarithm, for the multivariate Normal (Gaussian) distribution.

## Syntax

[pdf, rank, ifail] = g01lb(ilog, k, x, xmu, iuld, sig, 'n', n)
[pdf, rank, ifail] = nag_stat_pdf_multi_normal_vector(ilog, k, x, xmu, iuld, sig, 'n', n)

## Description

The probability density function, f(X : μ,Σ)$f\left(X:\mu ,\Sigma \right)$ of an n$n$-dimensional multivariate Normal distribution with mean vector μ$\mu$ and n$n$ by n$n$ variance-covariance matrix Σ$\Sigma$, is given by
 f(X : μ,Σ) = ((2π)n|Σ|) − 1 / 2 exp( − (1/2)(X − μ)TΣ − 1(X − μ)) . $f(X:μ,Σ) = ( (2⁢π) n ⁢ |Σ| ) -1/2 ⁢ exp( -12 ⁢ (X-μ)T ⁢ Σ-1 ⁢ (X-μ) ) .$
If the variance-covariance matrix, Σ$\Sigma$, is not of full rank then the probability density function, is calculated as
 f(X : μ,Σ) = ((2π)rpdet(Σ)) − 1 / 2 exp( − (1/2)(X − μ)TΣ−(X − μ)) $f(X:μ,Σ) = ( (2⁢π) r ⁢ pdet( Σ ) ) -1/2 ⁢ exp( -12 ⁢ (X-μ)T ⁢ Σ- ⁢ (X-μ) )$
where pdet(Σ)$\text{pdet}\left(\Sigma \right)$ is the pseudo-determinant, Σ${\Sigma }^{-}$ a generalized inverse of Σ$\Sigma$ and r$r$ its rank.
nag_stat_pdf_multi_normal_vector (g01lb) evaluates the PDF at k$k$ points with a single call.

None.

## Parameters

### Compulsory Input Parameters

1:     ilog – int64int32nag_int scalar
The value of ilog determines whether the logarithmic value is returned in PDF.
ilog = 0${\mathbf{ilog}}=0$
f(X : μ,Σ)$f\left(X:\mu ,\Sigma \right)$, the probability density function is returned.
ilog = 1${\mathbf{ilog}}=1$
log(f(X : μ,Σ))$\mathrm{log}\left(f\left(X:\mu ,\Sigma \right)\right)$, the logarithm of the probability density function is returned.
Constraint: ilog = 0${\mathbf{ilog}}=0$ or 1$1$.
2:     k – int64int32nag_int scalar
k$k$, the number of points the PDF is to be evaluated at.
Constraint: k0${\mathbf{k}}\ge 0$.
3:     x(ldx, : $:$) – double array
The first dimension of the array x must be at least n${\mathbf{n}}$
The second dimension of the array must be at least k${\mathbf{k}}$
X$X$, the matrix of k$k$ points at which to evaluate the probability density function, with the i$i$th dimension for the j$j$th point held in x(i,j)${\mathbf{x}}\left(i,j\right)$.
4:     xmu(n) – double array
n, the dimension of the array, must satisfy the constraint n2${\mathbf{n}}\ge 2$.
μ$\mu$, the mean vector of the multivariate Normal distribution.
5:     iuld – int64int32nag_int scalar
Indicates the form of Σ$\Sigma$ and how it is stored in sig.
iuld = 1${\mathbf{iuld}}=1$
sig holds the lower triangular portion of Σ$\Sigma$.
iuld = 2${\mathbf{iuld}}=2$
sig holds the upper triangular portion of Σ$\Sigma$.
iuld = 3${\mathbf{iuld}}=3$
Σ$\Sigma$ is a diagonal matrix and sig only holds the diagonal elements.
iuld = 4${\mathbf{iuld}}=4$
sig holds the lower Cholesky decomposition, L$L$ such that LLT = Σ$L{L}^{\mathrm{T}}=\Sigma$.
iuld = 5${\mathbf{iuld}}=5$
sig holds the upper Cholesky decomposition, U$U$ such that UTU = Σ${U}^{\mathrm{T}}U=\Sigma$.
Constraint: iuld = 1${\mathbf{iuld}}=1$, 2$2$, 3$3$, 4$4$ or 5$5$.
6:     sig(ldsig, : $:$) – double array
The first dimension, ldsig, of the array sig must satisfy
• if iuld = 3${\mathbf{iuld}}=3$, ldsig1$\mathit{ldsig}\ge 1$;
• otherwise ldsign$\mathit{ldsig}\ge {\mathbf{n}}$.
The second dimension of the array must be at least n${\mathbf{n}}$
Information defining the variance-covariance matrix, Σ$\Sigma$.
iuld = 1${\mathbf{iuld}}=1$ or 2$2$
sig must hold the lower or upper portion of Σ$\Sigma$, with Σij${\Sigma }_{ij}$ held in sig(i,j)${\mathbf{sig}}\left(i,j\right)$. The supplied variance-covariance matrix must be positive semidefinite.
iuld = 3${\mathbf{iuld}}=3$
Σ$\Sigma$ is a diagonal matrix and the i$i$th diagonal element, Σii${\Sigma }_{ii}$, must be held in sig(1,i)${\mathbf{sig}}\left(1,i\right)$
iuld = 4${\mathbf{iuld}}=4$ or 5$5$
sig must hold L$L$ or U$U$, the lower or upper Cholesky decomposition of Σ$\Sigma$, with Lij${L}_{ij}$ or Uij${U}_{ij}$ held in sig(i,j)${\mathbf{sig}}\left(i,j\right)$, depending on the value of iuld. No check is made that LLT$L{L}^{\mathrm{T}}$ or UTU${U}^{\mathrm{T}}U$ is a valid variance-covariance matrix. The diagonal elements of the supplied L$L$ or U$U$ must be greater than zero

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The first dimension of the array x and the dimension of the array xmu and the first dimension of the array sig and the second dimension of the array sig. (An error is raised if these dimensions are not equal.)
n$n$, the number of dimensions.
Constraint: n2${\mathbf{n}}\ge 2$.

ldx ldsig

### Output Parameters

1:     pdf(k${\mathbf{k}}$) – double array
f(X : μ,Σ)$f\left(X:\mu ,\Sigma \right)$ or log(f(X : μ,Σ))$\mathrm{log}\left(f\left(X:\mu ,\Sigma \right)\right)$ depending on the value of ilog.
2:     rank – int64int32nag_int scalar
r$r$, rank of Σ$\Sigma$.
3:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:
ifail = 11${\mathbf{ifail}}=11$
On entry, ilog = _${\mathbf{ilog}}=_$.
Constraint: ilog = 0${\mathbf{ilog}}=0$ or 1$1$.
ifail = 21${\mathbf{ifail}}=21$
Constraint: k0${\mathbf{k}}\ge 0$.
ifail = 31${\mathbf{ifail}}=31$
Constraint: n2${\mathbf{n}}\ge 2$.
ifail = 51${\mathbf{ifail}}=51$
Constraint: ldxn$\mathit{ldx}\ge {\mathbf{n}}$.
ifail = 71${\mathbf{ifail}}=71$
On entry, iuld = _${\mathbf{iuld}}=_$.
Constraint: iuld = 1${\mathbf{iuld}}=1$, 2$2$, 3$3$, 4$4$ or 5$5$.
ifail = 81${\mathbf{ifail}}=81$
On entry, Σ$\Sigma$ is not positive semidefinite.
ifail = 82${\mathbf{ifail}}=82$
On entry, at least one diagonal element of Σ$\Sigma$ is less than or equal to 0$0$.
ifail = 83${\mathbf{ifail}}=83$
On entry, Σ$\Sigma$ is not positive definite and eigenvalue decomposition failed.
ifail = 91${\mathbf{ifail}}=91$
Constraint: if iuld = 3${\mathbf{iuld}}=3$, ldsig1$\mathit{ldsig}\ge 1$.
ifail = 92${\mathbf{ifail}}=92$
Constraint: if iuld3${\mathbf{iuld}}\ne 3$, ldsign$\mathit{ldsig}\ge {\mathbf{n}}$.

Not applicable.

None.

## Example

```function nag_stat_pdf_multi_normal_vector_example
ilog = int64(0);
k    = int64(2);
iuld = int64(1);
xmu  = [0.1; 0.2; 0.3; 0.4];
sig  = [4.16,  0,     0,     0;
-3.12,  5.03,  0,     0;
0.56, -0.83,  0.76,  0;
-0.10,  1.18,  0.34,  1.18];
x    = [1, 1;
1, 2;
1, 3;
1, 4];

[pdf, rnk, ifail] = nag_stat_pdf_multi_normal_vector(ilog, k, x, xmu, iuld, sig);

fprintf('\nRank of the covariance matrix: %d\n', rnk);
if ilog == 1
fprintf('     log(PDF)                  X\n');
else
fprintf('       PDF                     X\n');
end
for i=1:k
fprintf('%13.4e %8.4f %8.4f %8.4f %8.4f\n', pdf(i), x(:, i));
end
```
```

Rank of the covariance matrix: 4
PDF                     X
3.0307e-03   1.0000   1.0000   1.0000   1.0000
4.5232e-06   1.0000   2.0000   3.0000   4.0000

```
```function g01lb_example
ilog = int64(0);
k    = int64(2);
iuld = int64(1);
xmu  = [0.1; 0.2; 0.3; 0.4];
sig  = [4.16,  0,     0,     0;
-3.12,  5.03,  0,     0;
0.56, -0.83,  0.76,  0;
-0.10,  1.18,  0.34,  1.18];
x    = [1, 1;
1, 2;
1, 3;
1, 4];

[pdf, rnk, ifail] = g01lb(ilog, k, x, xmu, iuld, sig);

fprintf('\nRank of the covariance matrix: %d\n', rnk);
if ilog == 1
fprintf('     log(PDF)                  X\n');
else
fprintf('       PDF                     X\n');
end
for i=1:k
fprintf('%13.4e %8.4f %8.4f %8.4f %8.4f\n', pdf(i), x(:, i));
end
```
```

Rank of the covariance matrix: 4
PDF                     X
3.0307e-03   1.0000   1.0000   1.0000   1.0000
4.5232e-06   1.0000   2.0000   3.0000   4.0000

```