Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

# 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$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$C$ with k$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 = XXT + diag(IXXT)$C=X{X}^{\mathrm{T}}+\mathrm{diag}\left(I-X{X}^{\mathrm{T}}\right)$, where I$I$ is the identity matrix and X$X$ has n$n$ rows and k$k$ columns. X$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 min GXXT + diag(XXTI)F${\mathrm{min}\phantom{\rule{0.25em}{0ex}}‖G-X{X}^{\mathrm{T}}+\mathrm{diag}\left(X{X}^{\mathrm{T}}-I\right)‖}_{F}$ such that xiT21${‖{x}_{\mathit{i}}^{\mathrm{T}}‖}_{2}\le 1$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$, where xi${x}_{i}$ is the i$i$th row of the factor loading matrix, X$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:     g(ldg,n) – double array
ldg, the first dimension of the array, must satisfy the constraint ldgn$\mathit{ldg}\ge {\mathbf{n}}$.
G$G$, the initial matrix.
2:     k – int64int32nag_int scalar
k$k$, the number of factors and columns of X$X$.
Constraint: 0 < kn$0<{\mathbf{k}}\le {\mathbf{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$n$, the order of the matrix G$G$.
Constraint: n > 0${\mathbf{n}}>0$.
2:     errtol – double scalar
The termination tolerance for the projected gradient norm. See references for further details. If errtol0.0${\mathbf{errtol}}\le 0.0$ then 0.01$0.01$ is used. This is often a suitable default value.
Default: 0.0$0.0$
3:     maxit – int64int32nag_int scalar
Specifies the maximum number of iterations in the spectral projected gradient method.
If maxit0${\mathbf{maxit}}\le 0$, 40000$40000$ is used.
Default: 0$0$

ldg ldx

### Output Parameters

1:     g(ldg,n) – double array
ldgn$\mathit{ldg}\ge {\mathbf{n}}$.
A symmetric matrix (1/2)(G + GT)$\frac{1}{2}\left(G+{G}^{\mathrm{T}}\right)$ with the diagonal elements set to unity.
2:     x(ldx,k) – double array
ldxn$\mathit{ldx}\ge {\mathbf{n}}$.
Contains the matrix X$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 min GXXT + diag(XXTI)F${\mathrm{min}\phantom{\rule{0.25em}{0ex}}‖G-X{X}^{\mathrm{T}}+\mathrm{diag}\left(X{X}^{\mathrm{T}}-I\right)‖}_{F}$.
5:     nrmpgd – double scalar
The norm of the projected gradient at the final iteration.
6:     ifail – int64int32nag_int scalar
${\mathrm{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:
ifail = 1${\mathbf{ifail}}=1$
Constraint: 0 < kn$0<{\mathbf{k}}\le {\mathbf{n}}$.
Constraint: ldgn$\mathit{ldg}\ge {\mathbf{n}}$.
Constraint: ldxn$\mathit{ldx}\ge {\mathbf{n}}$.
Constraint: n > 0${\mathbf{n}}>0$.
ifail = 2${\mathbf{ifail}}=2$
Spectral gradient method fails to converge in _$_$ iterations.
ifail = 999${\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 n × n + 4 × n × k + (nb + 3) × n + n + 50${\mathbf{n}}×{\mathbf{n}}+4×{\mathbf{n}}×{\mathbf{k}}+\left(\mathit{nb}+3\right)×{\mathbf{n}}+{\mathbf{n}}+50$ double elements and 6 × n$6×{\mathbf{n}}$ integer elements. Here nb$\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

```function nag_correg_corrmat_nearest_kfactor_example
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] = nag_correg_corrmat_nearest_kfactor(g, k);

if (ifail == 0)
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))));
end
```
```

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

```
```function g02ae_example
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);

if (ifail == 0)
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))));
end
```
```

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

```