Borsdorf R, Higham N J and Raydan M (2010) Computing a nearest correlation matrix with factor structure. SIAM J. Matrix Anal. Appl. 31(5) 2603–2622

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 number of factors and columns of $X$ .

Constraint: $0 < k \leq n$ .

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.)
$n$ , the order of the matrix $G$ .

Constraint: $n > 0$ .
2: $errtol$ – double scalar: Default: $0.0$
The termination tolerance for the projected gradient norm. See references for further details. If $errtol \leq 0.0$ then $0.01$ is used. This is often a suitable default value.
3: $maxit$ – int64int32nag_int scalar: Default: $0$
Specifies the maximum number of iterations in the spectral projected gradient method.
If $maxit \leq 0$ , $40000$ is used.

Output Parameters

1: $g (ldg, n)$ – double array: A symmetric matrix $\frac{1}{2} (G + G^{T})$ with the diagonal elements set to unity.
2: $x (ldx, k)$ – double array: Contains the matrix $X$ .
3: $iter$ – int64int32nag_int scalar: The number of steps taken in the spectral projected gradient method.
4: $feval$ – int64int32nag_int scalar: The number of evaluations of ${‖G - X X^{T} + diag (X X^{T} - I)‖}_{F}$ .
5: $nrmpgd$ – double scalar: The norm of the projected gradient at the final iteration.
6: $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: $0 < k \leq n$ .

Constraint: $ldg \geq n$ .

Constraint: $ldx \geq n$ .

Constraint: $n > 0$ .

$ifail = 2$: Spectral gradient method fails to converge in $_$ iterations.

$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 returned accuracy is controlled by errtol and limited by machine precision.

Further Comments

Arrays are internally allocated by nag_correg_corrmat_nearest_kfactor (g02ae). The total size of these arrays is

n \times n + 4 \times n \times k + (nb + 3) \times n + n + 50

double elements and

6 \times n

integer elements. Here

nb

is the block size required for optimal performance by nag_lapack_dsytrd (f08fe) and nag_lapack_dormtr (f08fg) which are called internally. All allocated memory is freed before return of nag_correg_corrmat_nearest_kfactor (g02ae).

See nag_mv_factor (g03ca) for constructing the factor loading matrix from a known correlation matrix.

Example

This example finds the nearest correlation matrix with

k = 2

factor structure to:

G = (\begin{matrix} 2 & - 1 & 0 & 0 \\ - 1 & 2 & - 1 & 0 \\ 0 & - 1 & 2 & - 1 \\ 0 & 0 & - 1 & 2 \end{matrix})

Open in the MATLAB editor: g02ae_example

function g02ae_example


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

g = [2, -1,  0,  0;
    -1,  2, -1,  0;
     0, -1,  2, -1;
     0,  0, -1,  2];
k = int64(2);

% Calculate nearest correlation matrix
[g, x, iter, feval, nrmpgd, ifail] = ...
  g02ae(g, k);

fprintf('\n Factor Loading Matrix x:\n');
disp(x);
fprintf('\n Number of Newton steps taken:   %d\n', iter);
fprintf(' Number of function evaluations: %d\n', feval);

% Generate Nearest k factor correlation matrix

fprintf('\n Nearest Correlation Matrix:\n');
disp(x*transpose(x) + diag(diag(eye(4)-x*transpose(x))));

g02ae example results


 Factor Loading Matrix x:
    0.7665   -0.6271
   -0.4250    0.9052
   -0.4250   -0.9052
    0.7665    0.6271


 Number of Newton steps taken:   5
 Number of function evaluations: 6

 Nearest Correlation Matrix:
    1.0000   -0.8935    0.2419    0.1943
   -0.8935    1.0000   -0.6388    0.2419
    0.2419   -0.6388    1.0000   -0.8935
    0.1943    0.2419   -0.8935    1.0000

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

Chapter Contents

Chapter Introduction

NAG Toolbox