NAG Library Function Document

nag_nearest_correlation_k_factor (g02aec)

void	nag_nearest_correlation_k_factor (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)

3 Description

A correlation matrix

C

with

k

-factor structure may be characterized as a real square matrix that is symmetric, has a unit diagonal, is positive semidefinite and can be written as

C = X X^{T} + diag (I - X X^{T})

, 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_nearest_correlation_k_factor (g02aec) applies a spectral projected gradient method to the modified problem

{\min ‖G - X X^{T} + diag (X X^{T} - I)‖}_{F}

such that

{‖x_{i}^{T}‖}_{2} \leq 1

, for

i = 1, 2, \dots, n

, where

x_{i}

is the

i

th row of the factor loading matrix,

X

, 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: order – Nag_OrderTypeInput

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

order = Nag_RowMajor

. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint:

order = Nag_RowMajor

or Nag_ColMajor.

2: g[ $\dim$ ] – doubleInput/Output

Note: the dimension, dim, of the array g must be at least

pdg \times n

The

(i, j)

th element of the matrix

G

is stored in

$g [(j - 1) \times pdg + i - 1]$ when $order = Nag_ColMajor$ ;
$g [(i - 1) \times pdg + j - 1]$ when $order = Nag_RowMajor$ .

On entry:

G

, the initial matrix.

On exit: a symmetric matrix

\frac{1}{2} (G + G^{T})

with the diagonal elements set to unity.

3: pdg – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array g.

Constraint:

pdg \geq n

4: n – IntegerInput

On entry:

n

, the order of the matrix

G

Constraint:

n > 0

5: k – IntegerInput

On entry:

k

, the number of factors and columns of

X

Constraint:

0 < k \leq n

6: errtol – doubleInput

On entry: 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.

7: maxit – IntegerInput

On entry: specifies the maximum number of iterations in the spectral projected gradient method.

maxit \leq 0

40000

is used.

8: x[ $\dim$ ] – doubleOutput

Note: the dimension, dim, of the array x must be at least

$\max (1, pdx \times k)$ when $order = Nag_ColMajor$ ;
$\max (1, n \times pdx)$ when $order = Nag_RowMajor$ .

The

(i, j)

th element of the matrix

X

is stored in

$x [(j - 1) \times pdx + i - 1]$ when $order = Nag_ColMajor$ ;
$x [(i - 1) \times pdx + j - 1]$ when $order = Nag_RowMajor$ .

On exit: contains the matrix

X

9: pdx – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array x.

Constraints:

if $order = Nag_ColMajor$ , $pdx \geq n$ ;
if $order = Nag_RowMajor$ , $pdx \geq k$ .

10: iter – Integer *Output

On exit: the number of steps taken in the spectral projected gradient method.

11: feval – Integer *Output

On exit: the number of evaluations

{\min ‖G - X X^{T} + diag (X X^{T} - I)‖}_{F}

12: nrmpgd – double *Output

On exit: the norm of the projected gradient at the final iteration.

13: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_BAD_PARAM: On entry, argument $〈value〉$ had an illegal value.
NE_CONVERGENCE: Spectral gradient method fails to converge in $〈value〉$ iterations.
NE_INT: On entry, $n = 〈value〉$ .
Constraint: $n > 0$ .
NE_INT_2: On entry, $k = 〈value〉$ and $n = 〈value〉$ .
Constraint: $0 < k \leq n$ .; On entry, $pdg = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pdg \geq n$ .; On entry, $pdx = 〈value〉$ and $k = 〈value〉$ .
Constraint: $pdx \geq k$ .; On entry, $pdx = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pdx \geq n$ .
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.

7 Accuracy

The returned accuracy is controlled by errtol and limited by machine precision.

8 Further Comments

Arrays are internally allocated by nag_nearest_correlation_k_factor (g02aec). 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. There is an additional

n \times k

double elements if

order = Nag_RowMajor

. Here

nb

is the block size required for optimal performance by nag_dsytrd (f08fec) and nag_dormtr (f08fgc) which are called internally. All allocated memory is freed before return of nag_nearest_correlation_k_factor (g02aec).

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

9 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})

NAG Library Function Documentnag_nearest_correlation_k_factor (g02aec)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_nearest_correlation_k_factor (g02aec)