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_correg_corrmat_nearest_kfactor (g02ae)

## Purpose

nag_correg_corrmat_nearest_kfactor (g02ae) computes the factor loading matrix associated with the nearest correlation matrix with $k$-factor structure, in the Frobenius norm, to a given square, input matrix.

## Syntax

[g, x, iter, feval, nrmpgd, ifail] = g02ae(g, k, 'n', n, 'errtol', errtol, 'maxit', maxit)
[g, x, iter, feval, nrmpgd, ifail] = nag_correg_corrmat_nearest_kfactor(g, k, 'n', n, 'errtol', errtol, 'maxit', maxit)

## Description

A correlation matrix $C$ with $k$-factor structure may be characterised as a real square matrix that is symmetric, has a unit diagonal, is positive semidefinite and can be written as $C=X{X}^{\mathrm{T}}+\mathrm{diag}\left(I-X{X}^{\mathrm{T}}\right)$, where $I$ is the identity matrix and $X$ has $n$ rows and $k$ columns. $X$ is often referred to as the factor loading matrix.
nag_correg_corrmat_nearest_kfactor (g02ae) applies a spectral projected gradient method to the modified problem ${\mathrm{min}\phantom{\rule{0.25em}{0ex}}‖G-X{X}^{\mathrm{T}}+\mathrm{diag}\left(X{X}^{\mathrm{T}}-I\right)‖}_{F}$ such that ${‖{x}_{\mathit{i}}^{\mathrm{T}}‖}_{2}\le 1$, for $\mathit{i}=1,2,\dots ,n$, where ${x}_{i}$ is the $i$th row of the factor loading matrix, $X$, which gives us the solution.

## References

Birgin E G, Martínez J M and Raydan M (2001) Algorithm 813: SPG–software for convex-constrained optimization ACM Trans. Math. Software 27 340–349
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:     $\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 number of factors and columns of $X$.
Constraint: $0<{\mathbf{k}}\le {\mathbf{n}}$.

### 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.)
$n$, the order of the matrix $G$.
Constraint: ${\mathbf{n}}>0$.
2:     $\mathrm{errtol}$ – double scalar
Default: $0.0$
The termination tolerance for the projected gradient norm. See references for further details. If ${\mathbf{errtol}}\le 0.0$ then $0.01$ is used. This is often a suitable default value.
3:     $\mathrm{maxit}$int64int32nag_int scalar
Default: $0$
Specifies the maximum number of iterations in the spectral projected gradient method.
If ${\mathbf{maxit}}\le 0$, $40000$ 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 elements set to unity.
2:     $\mathrm{x}\left(\mathit{ldx},{\mathbf{k}}\right)$ – double array
Contains the matrix $X$.
3:     $\mathrm{iter}$int64int32nag_int scalar
The number of steps taken in the spectral projected gradient method.
4:     $\mathrm{feval}$int64int32nag_int scalar
The number of evaluations of ${‖G-X{X}^{\mathrm{T}}+\mathrm{diag}\left(X{X}^{\mathrm{T}}-I\right)‖}_{F}$.
5:     $\mathrm{nrmpgd}$ – double scalar
The norm of the projected gradient at the final iteration.
6:     $\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: $0<{\mathbf{k}}\le {\mathbf{n}}$.
Constraint: $\mathit{ldg}\ge {\mathbf{n}}$.
Constraint: $\mathit{ldx}\ge {\mathbf{n}}$.
Constraint: ${\mathbf{n}}>0$.
${\mathbf{ifail}}=2$
Spectral gradient method fails to converge in $_$ iterations.
${\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 returned accuracy is controlled by errtol and limited by machine precision.

Arrays are internally allocated by nag_correg_corrmat_nearest_kfactor (g02ae). The total size of these arrays is ${\mathbf{n}}×{\mathbf{n}}+4×{\mathbf{n}}×{\mathbf{k}}+\left(\mathit{nb}+3\right)×{\mathbf{n}}+{\mathbf{n}}+50$ double elements and $6×{\mathbf{n}}$ integer elements. Here $\mathit{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 = 2 -1 0 0 -1 2 -1 0 0 -1 2 -1 0 0 -1 2$
```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);

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

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

```