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)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 25: k was made optional

## Description

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

None.

## Parameters

### Compulsory Input Parameters

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

### Optional Input Parameters

1:     $\mathrm{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$, the number of dimensions.
Constraint: ${\mathbf{n}}\ge 2$.

### Output Parameters

1:     $\mathrm{pdf}\left({\mathbf{k}}\right)$ – double array
$f\left(X:\mu ,\Sigma \right)$ or $\mathrm{log}\left(f\left(X:\mu ,\Sigma \right)\right)$ depending on the value of ilog.
2:     $\mathrm{rank}$int64int32nag_int scalar
$r$, rank of $\Sigma$.
3:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{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:
${\mathbf{ifail}}=11$
Constraint: ${\mathbf{ilog}}=0$ or $1$.
${\mathbf{ifail}}=21$
Constraint: ${\mathbf{k}}\ge 0$.
${\mathbf{ifail}}=31$
Constraint: ${\mathbf{n}}\ge 2$.
${\mathbf{ifail}}=51$
Constraint: $\mathit{ldx}\ge {\mathbf{n}}$.
${\mathbf{ifail}}=71$
Constraint: ${\mathbf{iuld}}=1$, $2$, $3$, $4$ or $5$.
${\mathbf{ifail}}=81$
On entry, $\Sigma$ is not positive semidefinite.
${\mathbf{ifail}}=82$
On entry, at least one diagonal element of $\Sigma$ is less than or equal to $0$.
${\mathbf{ifail}}=83$
On entry, $\Sigma$ is not positive definite and eigenvalue decomposition failed.
${\mathbf{ifail}}=91$
Constraint: if ${\mathbf{iuld}}=3$, $\mathit{ldsig}\ge 1$.
${\mathbf{ifail}}=92$
Constraint: if ${\mathbf{iuld}}\ne 3$, $\mathit{ldsig}\ge {\mathbf{n}}$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

Not applicable.

None.

## Example

This example prints the value of the multivariate Normal PDF at a number of different points.
```function g01lb_example

fprintf('g01lb example results\n\n');

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, 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

```
```g01lb example results

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
```