naginterfaces.library.correg.corrmat_​nearest_​bounded

naginterfaces.library.correg.corrmat_nearest_bounded(g, opt, alpha=None, w=None, errtol=0.0, maxits=0, maxit=0)

corrmat_nearest_bounded computes the nearest correlation matrix, in the Frobenius norm or weighted 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 g02ab

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

Parameters

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

$G$, the initial matrix.

optstr, length 1

Indicates the problem to be solved.

$opt=\text{'A'}$

The lower bound problem is solved.

$opt=\text{'W'}$

The weighted norm problem is solved.

$opt=\text{'B'}$

Both problems are solved.

alphaNone or float, optional

The value of $\alpha$.

If $opt=\text{'W'}$, $alpha$ need not be set.

wNone or float, array-like, shape $(:)$, optional

Note: the required length for this argument is determined as follows: if $opt\ne \text{'A'}$: $n$; otherwise: $0$.

The square roots of the diagonal elements of $W$, that is the diagonal of $W^{\frac{1}{2}}$.

If $opt=\text{'A'}$, $w$ is not referenced and may be None.

errtolfloat, optional

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

maxitsint, optional

Specifies the maximum number of iterations to be used by the iterative scheme to solve the linear algebraic equations at each Newton step.

If $maxits\le 0$, $2\times n$ 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 $1$)

On entry, the value of $opt$ is invalid.

Constraint: $opt=\text{'A'}$, $\text{'W'}$ or $\text{'B'}$.

(errno $1$)

On entry, $alpha=⟨value⟩$.

Constraint: $0.0<alpha<1.0$.

(errno $1$)

On entry, all elements of $w$ were not positive.

Constraint: $w[\text{i}-1]>0.0$, for all $i$.

(errno $2$)

Newton iteration fails to converge in $⟨value⟩$ iterations. Increase $maxit$ or check the call to the function.

Warns

NagAlgorithmicWarning

(errno $3$)

The machine precision is limiting convergence. In this instance the returned value of $x$ may be useful.

(errno $4$)

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

Notes

Finds the nearest correlation matrix $X$ by minimizing $\frac{1}{2}{\parallel G-X\parallel }^2$ where $G$ is an approximate correlation matrix.

The norm can either be the Frobenius norm or the weighted Frobenius norm $\frac{1}{2}{\Vert W^{\frac{1}{2}}(G-X)W^{\frac{1}{2}}\Vert }_F^2$.

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

Note that if the weights 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

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