hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_nearest_correlation_shrinking (g02an)

 Contents

    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example

Purpose

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 = α A 0 0 I + 1-α G  
where A is the k by k leading principle submatrix of the input matrix G and positive definite, and α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:     gldgn – double array
ldg, the first dimension of the array, must satisfy the constraint ldgn.
G, the initial matrix.
2:     k int64int32nag_int scalar
k, the order of the leading principle submatrix A.
Constraint: nk>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 errtol0, 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 λminA>n×λmaxA×eigtol, where λminA and λmaxA denote the minimum and maximum eigenvalues of A respectively, A is positive definite.
If eigtol0, machine precision is used.

Output Parameters

1:     gldgn – double array
A symmetric matrix 12G+GT with the diagonal set to I.
2:     xldxn – 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-XF 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: ldgn.
   ifail=3
Constraint: nk>0.
   ifail=4
Constraint: ldxn.
   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:
log21errtol .  

Further Comments

Arrays are internally allocated by nag_nearest_correlation_shrinking (g02an). The total size of these arrays does not exceed 2×n2+3×n real elements. All allocated memory is freed before return of nag_nearest_correlation_shrinking (g02an).

Example

This example finds the smallest uniform perturbation α to G, such that the output is a correlation matrix and the k-by-k leading principle submatrix of the input is preserved,
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 .  
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

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015