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


    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example


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.


[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)


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=XXT+diagI-XXT, 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 minG-XXT+diagXXT-IF such that xiT21, for i=1,2,,n, where xi is the ith row of the factor loading matrix, X, which gives us the solution.


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


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 number of factors and columns of X.
Constraint: 0<kn.

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 errtol0.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 maxit0, 40000 is used.

Output Parameters

1:     gldgn – double array
A symmetric matrix 12G+GT with the diagonal elements set to unity.
2:     xldxk – 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-XXT+diagXXT-IF.
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:
Constraint: 0<kn.
Constraint: ldgn.
Constraint: ldxn.
Constraint: n>0.
Spectral gradient method fails to converge in _ iterations.
An unexpected error has been triggered by this routine. Please contact NAG.
Your licence key may have expired or may not have been installed correctly.
Dynamic memory allocation failed.


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×n+4×n×k+nb+3×n+n+50 double elements and 6×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.


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);

fprintf('\n Factor Loading Matrix x:\n');
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

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