NAG Toolbox: nag_stat_pdf_multi_normal_vector (g01lb)

Purpose

Syntax

Description

References

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$

$\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 $\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

   $\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$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: g01lb_example

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