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

## Purpose

nag_stat_moments_quad_form (g01na) computes the cumulants and moments of quadratic forms in Normal variates.

## Syntax

[rkum, rmom, ifail] = g01na(a, sigma, l, 'n', n, 'emu', emu)
[rkum, rmom, ifail] = nag_stat_moments_quad_form(a, sigma, l, 'n', n, 'emu', emu)
Note: the interface to this routine has changed since earlier releases of the toolbox:
Mark 23: mom and mean dropped from interface, emu now optional
.

## Description

Let x$x$ have an n$n$-dimensional multivariate Normal distribution with mean μ$\mu$ and variance-covariance matrix Σ$\Sigma$. Then for a symmetric matrix A$A$, nag_stat_moments_quad_form (g01na) computes up to the first 12$12$ moments and cumulants of the quadratic form Q = xTAx$Q={x}^{\mathrm{T}}Ax$. The s$s$th moment (about the origin) is defined as
 E(Qs), $E(Qs),$
where E$E$ denotes expectation. The s$s$th moment of Q$Q$ can also be found as the coefficient of ts / s ! ${t}^{s}/s!$ in the expansion of E(eQt)$E\left({e}^{Qt}\right)$. The s$s$th cumulant is defined as the coefficient of ts / s ! ${t}^{s}/s!$ in the expansion of log(E(eQt))$\mathrm{log}\left(E\left({e}^{Qt}\right)\right)$.
The function is based on the function CUM written by Magnus and Pesaran (1993a) and based on the theory given by Magnus (1978), Magnus (1979) and Magnus (1986).

## References

Magnus J R (1978) The moments of products of quadratic forms in Normal variables Statist. Neerlandica 32 201–210
Magnus J R (1979) The expectation of products of quadratic forms in Normal variables: the practice Statist. Neerlandica 33 131–136
Magnus J R (1986) The exact moments of a ratio of quadratic forms in Normal variables Ann. Économ. Statist. 4 95–109
Magnus J R and Pesaran B (1993a) The evaluation of cumulants and moments of quadratic forms in Normal variables (CUM): Technical description Comput. Statist. 8 39–45
Magnus J R and Pesaran B (1993b) The evaluation of moments of quadratic forms and ratios of quadratic forms in Normal variables: Background, motivation and examples Comput. Statist. 8 47–55

## Parameters

### Compulsory Input Parameters

1:     a(lda,n) – double array
lda, the first dimension of the array, must satisfy the constraint ldan$\mathit{lda}\ge {\mathbf{n}}$.
The n$n$ by n$n$ symmetric matrix A$A$. Only the lower triangle is referenced.
2:     sigma(ldsig,n) – double array
ldsig, the first dimension of the array, must satisfy the constraint ldsign$\mathit{ldsig}\ge {\mathbf{n}}$.
The n$n$ by n$n$ variance-covariance matrix Σ$\Sigma$. Only the lower triangle is referenced.
Constraint: the matrix Σ$\Sigma$ must be positive definite.
3:     l – int64int32nag_int scalar
The required number of cumulants, and moments if specified.
Constraint: 1l12$1\le {\mathbf{l}}\le 12$.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The first dimension of the arrays a, sigma and the second dimension of the arrays a, sigma. (An error is raised if these dimensions are not equal.)
n$n$, the dimension of the quadratic form.
Constraint: n > 1${\mathbf{n}}>1$.
2:     emu( : $:$) – double array
Note: the dimension of the array emu must be at least n${\mathbf{n}}$ if mean = 'M'$\mathit{mean}=\text{'M'}$, and at least 1$1$ otherwise.
If supplied, emu must contain the n$n$ elements of the vector μ$\mu$.

### Input Parameters Omitted from the MATLAB Interface

mom mean lda ldsig wk

### Output Parameters

1:     rkum(l) – double array
The l cumulants of the quadratic form.
2:     rmom( : $:$) – double array
Note: the dimension of the array rmom must be at least l${\mathbf{l}}$ if mom = 'M'$\mathit{mom}=\text{'M'}$, and at least 1$1$ otherwise.
If mom = 'M'$\mathit{mom}=\text{'M'}$, the l moments of the quadratic form.
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 = 1${\mathbf{ifail}}=1$
 On entry, n ≤ 1${\mathbf{n}}\le 1$, or l < 1${\mathbf{l}}<1$, or l > 12${\mathbf{l}}>12$, or lda < n$\mathit{lda}<{\mathbf{n}}$, or ldsig < n$\mathit{ldsig}<{\mathbf{n}}$, or mom ≠ 'C'$\mathit{mom}\ne \text{'C'}$ or 'M'$\text{'M'}$, or mean ≠ 'M'$\mathit{mean}\ne \text{'M'}$ or 'Z'$\text{'Z'}$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, the matrix Σ$\Sigma$ is not positive definite.

## Accuracy

In a range of tests the accuracy was found to be a modest multiple of machine precision. See Magnus and Pesaran (1993b).

None.

## Example

a = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0;
0.5, 0, 0, 0, 0, 0, 0, 0, 0, 0;
0, 0.5, 0, 0, 0, 0, 0, 0, 0, 0;
0, 0, 0.5, 0, 0, 0, 0, 0, 0, 0;
0, 0, 0, 0.5, 0, 0, 0, 0, 0, 0;
0, 0, 0, 0, 0.5, 0, 0, 0, 0, 0;
0, 0, 0, 0, 0, 0.5, 0, 0, 0, 0;
0, 0, 0, 0, 0, 0, 0.5, 0, 0, 0;
0, 0, 0, 0, 0, 0, 0, 0.5, 0, 0;
0, 0, 0, 0, 0, 0, 0, 0, 0.5, 0];
emu = [0.8;
0.64;
0.512;
0.4096;
0.32768;
0.262144;
0.2097152;
0.16777216;
0.134217728;
0.1073741824000001];
sigma = [1, 0, 0, 0, 0, 0, 0, 0, 0, 0;
0.8, 1.64, 0, 0, 0, 0, 0, 0, 0, 0;
0.64, 1.312, 2.0496, 0, 0, 0, 0, 0, 0, 0;
0.512, 1.0496, 1.63968, 2.311744, 0, 0, 0, 0, 0, 0;
0.4096, 0.83968, 1.311744, 1.8493952, 2.47951616, 0, 0, 0, 0, 0;
0.32768, 0.671744, 1.0493952, 1.47951616, 1.983612928, ...
2.5868903424, 0, 0, 0, 0;
0.262144, 0.5373952, 0.83951616, 1.183612928, ...
1.5868903424, 2.06951227392, 2.655609819136, 0, 0, 0;
0.2097152, 0.42991616, 0.671612928, 0.9468903424, ...
1.26951227392, 1.655609819136, ...
2.1244878553088, 2.69959028424704, 0, 0;
0.16777216, 0.343932928, 0.5372903424000002, 0.7575122739200002, ...
1.015609819136, 1.3244878553088, 1.699590284247041, 2.159672227397632, ...
2.727737781918106, 0;
0.134217728, 0.2751463424000002, 0.4298322739200002, ...
0.6060098191360002, ...
0.8124878553088003, 1.05959028424704, 1.359672227397632, ...
1.727737781918106, 2.182190225534485, 2.745752180427588];
l = int64(4);
[rkum, rmom, ifail] = nag_stat_moments_quad_form(a, sigma, l, 'emu', emu)

rkum =

1.0e+06 *

0.0000
0.0004
0.0161
1.1700

rmom =

1.0e+06 *

0.0000
0.0007
0.0399
3.4039

ifail =

0

function g01na_example
a = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0;
0.5, 0, 0, 0, 0, 0, 0, 0, 0, 0;
0, 0.5, 0, 0, 0, 0, 0, 0, 0, 0;
0, 0, 0.5, 0, 0, 0, 0, 0, 0, 0;
0, 0, 0, 0.5, 0, 0, 0, 0, 0, 0;
0, 0, 0, 0, 0.5, 0, 0, 0, 0, 0;
0, 0, 0, 0, 0, 0.5, 0, 0, 0, 0;
0, 0, 0, 0, 0, 0, 0.5, 0, 0, 0;
0, 0, 0, 0, 0, 0, 0, 0.5, 0, 0;
0, 0, 0, 0, 0, 0, 0, 0, 0.5, 0];
emu = [0.8;
0.64;
0.512;
0.4096;
0.32768;
0.262144;
0.2097152;
0.16777216;
0.134217728;
0.1073741824000001];
sigma = [1, 0, 0, 0, 0, 0, 0, 0, 0, 0;
0.8, 1.64, 0, 0, 0, 0, 0, 0, 0, 0;
0.64, 1.312, 2.0496, 0, 0, 0, 0, 0, 0, 0;
0.512, 1.0496, 1.63968, 2.311744, 0, 0, 0, 0, 0, 0;
0.4096, 0.83968, 1.311744, 1.8493952, 2.47951616, 0, 0, 0, 0, 0;
0.32768, 0.671744, 1.0493952, 1.47951616, 1.983612928, ...
2.5868903424, 0, 0, 0, 0;
0.262144, 0.5373952, 0.83951616, 1.183612928, ...
1.5868903424, 2.06951227392, 2.655609819136, 0, 0, 0;
0.2097152, 0.42991616, 0.671612928, 0.9468903424, ...
1.26951227392, 1.655609819136, ...
2.1244878553088, 2.69959028424704, 0, 0;
0.16777216, 0.343932928, 0.5372903424000002, 0.7575122739200002, ...
1.015609819136, 1.3244878553088, 1.699590284247041, 2.159672227397632, ...
2.727737781918106, 0;
0.134217728, 0.2751463424000002, 0.4298322739200002, ...
0.6060098191360002, ...
0.8124878553088003, 1.05959028424704, 1.359672227397632, ...
1.727737781918106, 2.182190225534485, 2.745752180427588];
l = int64(4);
[rkum, rmom, ifail] = g01na(a, sigma, l, 'emu', emu)

rkum =

1.0e+06 *

0.0000
0.0004
0.0161
1.1700

rmom =

1.0e+06 *

0.0000
0.0007
0.0399
3.4039

ifail =

0