naginterfaces.library.correg.corrmat_​h_​weight

naginterfaces.library.correg.corrmat_h_weight(g, alpha, h, errtol=0.0, maxit=0)

corrmat_h_weight computes the nearest correlation matrix, using element-wise weighting in the Frobenius norm and optionally with bounds on the eigenvalues, to a given square, input matrix.

For full information please refer to the NAG Library document for g02aj

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g02/g02ajf.html

Parameters

gfloat, array-like, shape $(n,n)$

$G$, the initial matrix.

alphafloat

The value of $\alpha$.

If $alpha<0.0$, $0.0$ is used.

hfloat, array-like, shape $(n,n)$

The matrix of weights $H$.

errtolfloat, optional

The termination tolerance for the iteration. If $errtol\le 0.0$, $n\times \sqrt{\text{machine precision}}$ is used. See Accuracy for further details.

maxitint, optional

Specifies the maximum number of iterations to be used.

If $maxit\le 0$, $200$ is used.

Returns

xfloat, ndarray, shape $(n,n)$

Contains the nearest correlation matrix.

iteraint

The number of iterations taken.

normfloat

The value of ${\parallel H\circ (G-X)\parallel }_F$ after the final iteration.

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n>0$.

(errno $5$)

On entry, $alpha=⟨value⟩$.

Constraint: $alpha<1.0$.

(errno $6$)

On entry, one or more of the off-diagonal elements of $H$ were negative.

(errno $7$)

Function failed to converge in $⟨value⟩$ iterations.

Increase $maxit$ or check the call to the function.

Warns

NagAlgorithmicWarning

(errno $8$)

Failure to solve intermediate eigenproblem. This should not occur. Please contact NAG with details of your call.

Notes

corrmat_h_weight finds the nearest correlation matrix, $X$, to an approximate correlation matrix, $G$, using element-wise weighting, this minimizes ${\parallel H\circ (G-X)\parallel }_F$, where $C=A\circ B$ denotes the matrix $C$ with elements $C_{ij}=A_{ij}\times B_{ij}$.

You can optionally specify a lower bound on the eigenvalues, $\alpha$, of the computed correlation matrix, forcing the matrix to be strictly positive definite, if $0<\alpha <1$.

Zero elements in $H$ should be used when you wish to put no emphasis on the corresponding element of $G$. The algorithm scales $H$ so that the maximum element is $1$. It is this scaled matrix that is used in computing the norm above and for the stopping criteria described in Accuracy.

Note that if the elements in $H$ vary by several orders of magnitude from one another the algorithm may fail to converge.

References

Borsdorf, R and Higham, N J, 2010, A preconditioned (Newton) algorithm for the nearest correlation matrix, IMA Journal of Numerical Analysis (30(1)), 94–107

Jiang, K, Sun, D and Toh, K-C, 2012, An inexact accelerated proximal gradient method for large scale linearly constrained convex SDP, SIAM J. Optim. (22(3)), 1042–1064

Qi, H and Sun, D, 2006, A quadratically convergent Newton method for computing the nearest correlation matrix, SIAM J. Matrix AnalAppl (29(2)), 360–385