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

# NAG Toolbox: nag_nearest_correlation_shrinking (g02an)

## 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 $\alpha \in \left[0,1\right]$.
nag_nearest_correlation_shrinking (g02an) utilizes a shrinking method to find the minimum value of $\alpha$ 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:     $\mathrm{g}\left(\mathit{ldg},{\mathbf{n}}\right)$ – double array
ldg, the first dimension of the array, must satisfy the constraint $\mathit{ldg}\ge {\mathbf{n}}$.
$G$, the initial matrix.
2:     $\mathrm{k}$int64int32nag_int scalar
$k$, the order of the leading principle submatrix $A$.
Constraint: ${\mathbf{n}}\ge {\mathbf{k}}>0$.

### Optional Input Parameters

1:     $\mathrm{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: ${\mathbf{n}}>0$.
2:     $\mathrm{errtol}$ – double scalar
Default: $0.0$
The termination tolerance for the iteration.
If ${\mathbf{errtol}}\le 0$,  is used. See Accuracy for further details.
3:     $\mathrm{eigtol}$ – double scalar
Default: $0.0$
The tolerance used in determining the definiteness of $A$.
If ${\lambda }_{\mathrm{min}}\left(A\right)>{\mathbf{n}}×{\lambda }_{\mathrm{max}}\left(A\right)×{\mathbf{eigtol}}$, where ${\lambda }_{\mathrm{min}}\left(A\right)$ and ${\lambda }_{\mathrm{max}}\left(A\right)$ denote the minimum and maximum eigenvalues of $A$ respectively, $A$ is positive definite.
If ${\mathbf{eigtol}}\le 0$, machine precision is used.

### Output Parameters

1:     $\mathrm{g}\left(\mathit{ldg},{\mathbf{n}}\right)$ – double array
A symmetric matrix $\frac{1}{2}\left(G+{G}^{\mathrm{T}}\right)$ with the diagonal set to $I$.
2:     $\mathrm{x}\left(\mathit{ldx},{\mathbf{n}}\right)$ – double array
Contains the matrix $X$.
3:     $\mathrm{alpha}$ – double scalar
$\alpha$.
4:     $\mathrm{iter}$int64int32nag_int scalar
The number of iterations taken.
5:     $\mathrm{eigmin}$ – double scalar
The smallest eigenvalue of the leading principle submatrix $A$.
6:     $\mathrm{norm_p}$ – double scalar
The value of ${‖G-X‖}_{F}$ after the final iteration.
7:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{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:
${\mathbf{ifail}}=1$
Constraint: ${\mathbf{n}}>0$.
${\mathbf{ifail}}=2$
Constraint: $\mathit{ldg}\ge {\mathbf{n}}$.
${\mathbf{ifail}}=3$
Constraint: ${\mathbf{n}}\ge {\mathbf{k}}>0$.
${\mathbf{ifail}}=4$
Constraint: $\mathit{ldx}\ge {\mathbf{n}}$.
${\mathbf{ifail}}=5$
The $k$-by-$k$ principle leading submatrix of the initial matrix $G$ is not positive definite.
${\mathbf{ifail}}=6$
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

The algorithm uses a bisection method. It is terminated when the computed $\alpha$ 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 .$

Arrays are internally allocated by nag_nearest_correlation_shrinking (g02an). The total size of these arrays does not exceed $2×{n}^{2}+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 $\alpha$ 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
```