NAG CL Interface
g02aec (corrmat_nearest_kfactor)
1
Purpose
g02aec computes the factor loading matrix associated with the nearest correlation matrix with -factor structure, in the Frobenius norm, to a given square, input matrix.
2
Specification
void |
g02aec (Nag_OrderType order,
double g[],
Integer pdg,
Integer n,
Integer k,
double errtol,
Integer maxit,
double x[],
Integer pdx,
Integer *iter,
Integer *feval,
double *nrmpgd,
NagError *fail) |
|
The function may be called by the names: g02aec, nag_correg_corrmat_nearest_kfactor or nag_nearest_correlation_k_factor.
3
Description
A correlation matrix with -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 , where is the identity matrix and has rows and columns. is often referred to as the factor loading matrix.
g02aec applies a spectral projected gradient method to the modified problem such that , for , where is the th row of the factor loading matrix, , which gives us the solution.
4
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
5
Arguments
-
1:
– Nag_OrderType
Input
-
On entry: the
order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by
. See
Section 3.1.3 in the Introduction to the NAG Library CL Interface for a more detailed explanation of the use of this argument.
Constraint:
or .
-
2:
– double
Input/Output
-
Note: the dimension,
dim, of the array
g
must be at least
.
On entry: , the initial matrix.
On exit: a symmetric matrix with the diagonal elements set to unity.
-
3:
– Integer
Input
On entry: the stride separating row or column elements (depending on the value of
order) of the matrix
in the array
g.
Constraint:
.
-
4:
– Integer
Input
-
On entry: , the order of the matrix .
Constraint:
.
-
5:
– Integer
Input
-
On entry: , the number of factors and columns of .
Constraint:
.
-
6:
– double
Input
-
On entry: the termination tolerance for the projected gradient norm. See references for further details. If , is used. This is often a suitable default value.
-
7:
– Integer
Input
-
On entry: specifies the maximum number of iterations in the spectral projected gradient method.
If , is used.
-
8:
– double
Output
-
Note: the dimension,
dim, of the array
x
must be at least
- when
;
- when
.
The
th element of the matrix
is stored in
- when ;
- when .
On exit: contains the matrix .
-
9:
– Integer
Input
-
On entry: the stride separating row or column elements (depending on the value of
order) in the array
x.
Constraints:
- if ,
;
- if , .
-
10:
– Integer *
Output
-
On exit: the number of steps taken in the spectral projected gradient method.
-
11:
– Integer *
Output
-
On exit: the number of evaluations of .
-
12:
– double *
Output
-
On exit: the norm of the projected gradient at the final iteration.
-
13:
– NagError *
Input/Output
-
The NAG error argument (see
Section 7 in the Introduction to the NAG Library CL Interface).
6
Error Indicators and Warnings
- NE_ALLOC_FAIL
-
Dynamic memory allocation failed.
See
Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
- NE_BAD_PARAM
-
On entry, argument had an illegal value.
- NE_CONVERGENCE
-
Spectral gradient method fails to converge in iterations.
- NE_INT
-
On entry, .
Constraint: .
- NE_INT_2
-
On entry, and .
Constraint: .
On entry, and .
Constraint: .
On entry, and .
Constraint: .
On entry, and .
Constraint: .
- NE_INTERNAL_ERROR
-
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact
NAG for assistance.
See
Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
- NE_NO_LICENCE
-
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library CL Interface for further information.
7
Accuracy
The returned accuracy is controlled by
errtol and limited by
machine precision.
8
Parallelism and Performance
g02aec is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g02aec makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the
Users' Note for your implementation for any additional implementation-specific information.
Arrays are internally allocated by
g02aec. The total size of these arrays is
double elements and
Integer elements.
There is an additional
double elements if
.
Here
is the block size required for optimal performance by
f08fec and
f08fgc which are called internally. All allocated memory is freed before return of
g02aec.
See
g03cac for constructing the factor loading matrix from a known correlation matrix.
10
Example
This example finds the nearest correlation matrix with
factor structure to:
10.1
Program Text
10.2
Program Data
10.3
Program Results