naginterfaces.library.correg.corrmat_​nearest

naginterfaces.library.correg.corrmat_nearest(g, errtol=0.0, maxits=0, maxit=0)

corrmat_nearest computes the nearest correlation matrix, in the Frobenius norm, to a given square, input matrix.

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

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

Parameters

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

$G$, the initial matrix.

errtolfloat, optional

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

maxitsint, optional

$maxits$ specifies the maximum number of iterations used for the iterative scheme used to solve the linear algebraic equations at each Newton step.

If $maxits\le 0$, $100$ is used.

maxitint, optional

Specifies the maximum number of Newton iterations.

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

Returns

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

Contains the nearest correlation matrix.

iteraint

The number of Newton steps taken.

fevalint

The number of function evaluations of the dual problem.

nrmgrdfloat

The norm of the gradient of the last Newton step.

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n>0$.

(errno $2$)

Newton iteration fails to converge in $⟨value⟩$ iterations.

(errno $4$)

An intermediate eigenproblem could not be solved. This should not occur. Please contact NAG with details of your call.

Warns

NagAlgorithmicWarning

(errno $3$)

Machine precision is limiting convergence.

The array returned in $x$ may still be of interest.

Notes

A correlation matrix may be characterised as a real square matrix that is symmetric, has a unit diagonal and is positive semidefinite.

corrmat_nearest applies an inexact Newton method to a dual formulation of the problem, as described by Qi and Sun (2006). It applies the improvements suggested by Borsdorf and Higham (2010).

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

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

See also

naginterfaces.library.examples.correg.corrmat_nearest_ex.main()