NAG FL Interface
g01nbf (moments_ratio_quad_forms)
1
Purpose
g01nbf computes the moments of ratios of quadratic forms in Normal variables and related statistics.
2
Specification
Fortran Interface
Subroutine g01nbf ( |
case, mean, n, a, lda, b, ldb, c, ldc, ela, emu, sigma, ldsig, l1, l2, lmax, rmom, abserr, eps, wk, ifail) |
Integer, Intent (In) |
:: |
n, lda, ldb, ldc, ldsig, l1, l2 |
Integer, Intent (Inout) |
:: |
ifail |
Integer, Intent (Out) |
:: |
lmax |
Real (Kind=nag_wp), Intent (In) |
:: |
a(lda,n), b(ldb,n), c(ldc,*), ela(*), emu(*), sigma(ldsig,n), eps |
Real (Kind=nag_wp), Intent (Out) |
:: |
rmom(l2-l1+1), abserr, wk(3*n*n+(8+l2)*n) |
Character (1), Intent (In) |
:: |
case, mean |
|
C Header Interface
#include <nag.h>
void |
g01nbf_ (const char *cas, const char *mean, const Integer *n, const double a[], const Integer *lda, const double b[], const Integer *ldb, const double c[], const Integer *ldc, const double ela[], const double emu[], const double sigma[], const Integer *ldsig, const Integer *l1, const Integer *l2, Integer *lmax, double rmom[], double *abserr, const double *eps, double wk[], Integer *ifail, const Charlen length_cas, const Charlen length_mean) |
|
C++ Header Interface
#include <nag.h> extern "C" {
void |
g01nbf_ (const char *cas, const char *mean, const Integer &n, const double a[], const Integer &lda, const double b[], const Integer &ldb, const double c[], const Integer &ldc, const double ela[], const double emu[], const double sigma[], const Integer &ldsig, const Integer &l1, const Integer &l2, Integer &lmax, double rmom[], double &abserr, const double &eps, double wk[], Integer &ifail, const Charlen length_cas, const Charlen length_mean) |
}
|
The routine may be called by the names g01nbf or nagf_stat_moments_ratio_quad_forms.
3
Description
Let
have an
-dimensional multivariate Normal distribution with mean
and variance-covariance matrix
. Then for a symmetric matrix
and symmetric positive semidefinite matrix
,
g01nbf computes a subset,
to
, of the first
moments of the ratio of quadratic forms
The
th moment (about the origin) is defined as
where
denotes the expectation. Alternatively, this routine will compute the following expectations:
and
where
is a vector of length
and
is an
by
symmetric matrix, if they exist. In the case of
(2) the moments are zero if
.
The conditions of theorems 1, 2 and 3 of
Magnus (1986) and
Magnus (1990) are used to check for the existence of the moments. If all the requested moments do not exist, the computations are carried out for those moments that are requested up to the maximum that exist,
.
This routine is based on the routine QRMOM written by
Magnus and Pesaran (1993a) and based on the theory given by
Magnus (1986) and
Magnus (1990). The computation of the moments requires first the computation of the eigenvectors of the matrix
, where
. The matrix
must be positive semidefinite and not null. Given the eigenvectors of this matrix, a function which has to be integrated over the range zero to infinity can be computed. This integration is performed using
d01amf.
4
References
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 (1990) On certain moments relating to quadratic forms in Normal variables: Further results Sankhyā, Ser. B 52 1–13
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
5
Arguments
-
1:
– Character(1)
Input
-
On entry: indicates the moments of which function are to be computed.
- (Ratio)
- is computed.
- (Linear with ratio)
- is computed.
- (Quadratic with ratio)
- is computed.
Constraint:
, or .
-
2:
– Character(1)
Input
-
On entry: indicates if the mean,
, is zero.
- is zero.
- The value of is supplied in emu.
Constraint:
or .
-
3:
– Integer
Input
-
On entry: , the dimension of the quadratic form.
Constraint:
.
-
4:
– Real (Kind=nag_wp) array
Input
-
On entry: the by symmetric matrix . Only the lower triangle is referenced.
-
5:
– Integer
Input
-
On entry: the first dimension of the array
a as declared in the (sub)program from which
g01nbf is called.
Constraint:
.
-
6:
– Real (Kind=nag_wp) array
Input
-
On entry: the by positive semidefinite symmetric matrix . Only the lower triangle is referenced.
Constraint:
the matrix must be positive semidefinite.
-
7:
– Integer
Input
-
On entry: the first dimension of the array
b as declared in the (sub)program from which
g01nbf is called.
Constraint:
.
-
8:
– Real (Kind=nag_wp) array
Input
-
Note: the second dimension of the array
c
must be at least
if
.
On entry: if
,
c must contain the
by
symmetric matrix
; only the lower triangle is referenced.
If
,
c is not referenced.
-
9:
– Integer
Input
-
On entry: the first dimension of the array
c as declared in the (sub)program from which
g01nbf is called.
Constraint:
if , .
-
10:
– Real (Kind=nag_wp) array
Input
-
Note: the dimension of the array
ela
must be at least
if
, and at least
otherwise.
On entry: if
,
ela must contain the vector
of length
, otherwise
ela is not referenced.
-
11:
– Real (Kind=nag_wp) array
Input
-
Note: the dimension of the array
emu
must be at least
if
, and at least
otherwise.
On entry: if
,
emu must contain the
elements of the vector
.
If
,
emu is not referenced.
-
12:
– Real (Kind=nag_wp) array
Input
-
On entry: the by variance-covariance matrix . Only the lower triangle is referenced.
Constraint:
the matrix must be positive definite.
-
13:
– Integer
Input
-
On entry: the first dimension of the array
sigma as declared in the (sub)program from which
g01nbf is called.
Constraint:
.
-
14:
– Integer
Input
-
On entry: the first moment to be computed, .
Constraint:
.
-
15:
– Integer
Input
-
On entry: the last moment to be computed, .
Constraint:
.
-
16:
– Integer
Output
-
On exit: the highest moment computed, . This will be if on exit.
-
17:
– Real (Kind=nag_wp) array
Output
-
On exit: the to moments.
-
18:
– Real (Kind=nag_wp)
Output
-
On exit: the estimated maximum absolute error in any computed moment.
-
19:
– Real (Kind=nag_wp)
Input
-
On entry: the relative accuracy required for the moments, this value is also used in the checks for the existence of the moments.
If , a value of where is the machine precision used.
Constraint:
or .
-
20:
– Real (Kind=nag_wp) array
Workspace
-
-
21:
– Integer
Input/Output
-
On entry:
ifail must be set to
,
. If you are unfamiliar with this argument you should refer to
Section 4 in the Introduction to the NAG Library FL Interface for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
is recommended. If the output of error messages is undesirable, then the value
is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if
on exit, the recommended value is
.
When the value is used it is essential to test the value of ifail on exit.
On exit:
unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
or
, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
Note: in some cases g01nbf may return useful information.
-
On entry, .
Constraint: , or .
On entry, .
Constraint: if , .
On entry, .
Constraint: .
On entry, and .
Constraint: .
On entry, .
Constraint: .
On entry, and .
Constraint: .
On entry, and .
Constraint: .
On entry, and .
Constraint: .
On entry, and .
Constraint: .
On entry, .
Constraint: or .
On entry, .
Constraint: .
-
On entry,
b is not positive semidefinite or is null.
On entry,
sigma is not positive definite.
-
Only moments exist, less than , therefore none of the required moments can be computed.
-
The matrix is not positive semidefinite or is null.
-
The computation to compute the eigenvalues required in the calculation of moments has failed to converge: this is an unlikely error exit.
-
Only some of the required moments have been computed, the highest is given by
lmax.
-
The required accuracy has not been achieved in the integration. An estimate of the accuracy is returned in
abserr.
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 7 in the Introduction to the NAG Library FL Interface for further information.
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library FL Interface for further information.
Dynamic memory allocation failed.
See
Section 9 in the Introduction to the NAG Library FL Interface for further information.
7
Accuracy
The relative accuracy is specified by
eps and an estimate of the maximum absolute error for all computed moments is returned in
abserr.
8
Parallelism and Performance
g01nbf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the
Users' Note for your implementation for any additional implementation-specific information.
None.
10
Example
This example is given by
Magnus and Pesaran (1993b) and considers the simple autoregression:
where
is a sequence of independent Normal variables with mean zero and variance one, and
is known. The least squares estimate of
,
, is given by
Thus
can be written as a ratio of quadratic forms and its moments computed using
g01nbf. The matrix
is given by
and the matrix
is given by
The value of
can be computed using the relationships
The values of , , , and the number of moments required are read in and the moments computed and printed.
10.1
Program Text
10.2
Program Data
10.3
Program Results