nag_nearest_correlation_shrinking (g02an) computes a correlation matrix, subject to preserving a leading principle submatrix and applying the smallest uniform perturbation to the remainder of the approximate input matrix.

Syntax

[g, x, alpha, iter, eigmin, norm_p, ifail] = g02an(g, k, 'n', n, 'errtol', errtol, 'eigtol', eigtol)

[g, x, alpha, iter, eigmin, norm_p, ifail] = nag_nearest_correlation_shrinking(g, k, 'n', n, 'errtol', errtol, 'eigtol', eigtol)

Description

nag_nearest_correlation_shrinking (g02an) finds a correlation matrix,

X

, starting from an approximate correlation matrix,

G

, with positive definite leading principle submatrix of order

k

. The returned correlation matrix,

X

, has the following structure:

X = α (\begin{matrix} A & 0 \\ 0 & I \end{matrix}) + (1 - α) G

where

A

is the

k

k

leading principle submatrix of the input matrix

G

and positive definite, and

α \in [0, 1]

nag_nearest_correlation_shrinking (g02an) utilizes a shrinking method to find the minimum value of

α

such that

X

is positive definite with unit diagonal.

References

Higham N J, Strabić N and Šego V (2014) Restoring definiteness via shrinking, with an application to correlation matrices with a fixed block MIMS EPrint 2014.54 Manchester Institute for Mathematical Sciences, The University of Manchester, UK

Parameters

Compulsory Input Parameters

1: $g (ldg, n)$ – double array: ldg, the first dimension of the array, must satisfy the constraint $ldg \geq n$ .
$G$ , the initial matrix.
2: $k$ – int64int32nag_int scalar: $k$ , the order of the leading principle submatrix $A$ .

Constraint: $n \geq k > 0$ .

Optional Input Parameters

1: $n$ – int64int32nag_int scalar: Default: the first dimension of the array g and the second dimension of the array g. (An error is raised if these dimensions are not equal.)
The order of the matrix $G$ .

Constraint: $n > 0$ .
2: $errtol$ – double scalar: Default: $0.0$
The termination tolerance for the iteration.
If $errtol \leq 0$ , $\sqrt{machine precision}$ is used. See Accuracy for further details.
3: $eigtol$ – double scalar: Default: $0.0$
The tolerance used in determining the definiteness of $A$ .
If $λ_{\min} (A) > n \times λ_{\max} (A) \times eigtol$ , where $λ_{\min} (A)$ and $λ_{\max} (A)$ denote the minimum and maximum eigenvalues of $A$ respectively, $A$ is positive definite.

If $eigtol \leq 0$ , machine precision is used.

Output Parameters

1: $g (ldg, n)$ – double array: A symmetric matrix $\frac{1}{2} (G + G^{T})$ with the diagonal set to $I$ .
2: $x (ldx, n)$ – double array: Contains the matrix $X$ .
3: $alpha$ – double scalar: $α$ .
4: $iter$ – int64int32nag_int scalar: The number of iterations taken.
5: $eigmin$ – double scalar: The smallest eigenvalue of the leading principle submatrix $A$ .
6: $norm_p$ – double scalar: The value of ${‖G - X‖}_{F}$ after the final iteration.
7: $ifail$ – int64int32nag_int scalar: $ifail = 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$: Constraint: $n > 0$ .

$ifail = 2$: Constraint: $ldg \geq n$ .

$ifail = 3$: Constraint: $n \geq k > 0$ .

$ifail = 4$: Constraint: $ldx \geq n$ .

$ifail = 5$: The $k$ -by- $k$ principle leading submatrix of the initial matrix $G$ is not positive definite.

$ifail = 6$: Failure to solve intermediate eigenproblem. This should not occur. Please contact NAG.

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$ifail = - 999$: Dynamic memory allocation failed.

Accuracy

The algorithm uses a bisection method. It is terminated when the computed

α

is within errtol of the minimum value. The positive definiteness of

X

is such that it can be sucessfully factorized with a call to nag_lapack_dpotrf (f07fd).

The number of iterations taken for the bisection will be:

⌈\log_{2} (\frac{1}{errtol})⌉ .

Further Comments

Arrays are internally allocated by nag_nearest_correlation_shrinking (g02an). The total size of these arrays does not exceed

2 \times n^{2} + 3 \times n

real elements. All allocated memory is freed before return of nag_nearest_correlation_shrinking (g02an).

Example

This example finds the smallest uniform perturbation

α

G

, such that the output is a correlation matrix and the

k

-by-

k

leading principle submatrix of the input is preserved,

G = (\begin{array}{r} 1.0000 & - 0.0991 & 0.5665 & - 0.5653 & - 0.3441 \\ - 0.0991 & 1.0000 & - 0.4273 & 0.8474 & 0.4975 \\ 0.5665 & - 0.4273 & 1.0000 & - 0.1837 & - 0.0585 \\ - 0.5653 & 0.8474 & - 0.1837 & 1.0000 & - 0.2713 \\ - 0.3441 & 0.4975 & - 0.0585 & - 0.2713 & 1.0000 \end{array}) .

Open in the MATLAB editor: g02an_example

function g02an_example


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

% Approximate correlation matrix
g = [1.0000 -0.0991  0.5665 -0.5653 -0.3441;
    -0.0991  1.0000 -0.4273  0.8474  0.4975;
     0.5665 -0.4273  1.0000 -0.1837 -0.0585;
    -0.5653  0.8474 -0.1837  1.0000 -0.2713;
    -0.3441  0.4975 -0.0585 -0.2713  1.0000];
% Preserve the leading 3-by-3 principal submatrix
k = int64(3);

% Calculate nearest correlation matrix
[g, x, alpha, iter, eigmin, norm_p, ifail] = ...
  g02an(g,k);

fprintf('\nSymmetrised input matrix \n');
disp(g);
fprintf('Nearest Perturbed Correlation Matrix\n');
disp(x);
fprintf('k:                              %d\n', k);
fprintf('Number of iterations taken:     %d\n', iter);
fprintf('alpha:                    %12.4f\n', alpha);
fprintf('Norm value:               %12.4f\n', norm_p);
fprintf('Smallest eigenvalue of A: %12.4f\n', eigmin);

g02an example results


Symmetrised input matrix 
    1.0000   -0.0991    0.5665   -0.5653   -0.3441
   -0.0991    1.0000   -0.4273    0.8474    0.4975
    0.5665   -0.4273    1.0000   -0.1837   -0.0585
   -0.5653    0.8474   -0.1837    1.0000   -0.2713
   -0.3441    0.4975   -0.0585   -0.2713    1.0000

Nearest Perturbed Correlation Matrix
    1.0000   -0.0991    0.5665   -0.3826   -0.2329
   -0.0991    1.0000   -0.4273    0.5735    0.3367
    0.5665   -0.4273    1.0000   -0.1243   -0.0396
   -0.3826    0.5735   -0.1243    1.0000   -0.1836
   -0.2329    0.3367   -0.0396   -0.1836    1.0000

k:                              3
Number of iterations taken:     27
alpha:                          0.3232
Norm value:                     0.5624
Smallest eigenvalue of A:       0.3359

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox