naginterfaces.library.correg.corrmat_​shrinking

naginterfaces.library.correg.corrmat_shrinking(g, k, errtol=0.0, eigtol=0.0)

corrmat_shrinking computes a correlation matrix, subject to preserving a leading principal submatrix and applying the smallest relative perturbation to the remainder of the approximate input matrix.

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

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

Parameters

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

$G$, the initial matrix.

kint

$k$, the order of the leading principal submatrix $A$.

errtolfloat, optional

The termination tolerance for the iteration.

If $errtol\le 0.0$, $\sqrt{\text{machine precision}}$ is used.

See Accuracy for further details.

eigtolfloat, optional

The tolerance used in determining the definiteness of $A$.

If ${\lambda }_{min}\left(A\right)>n\times {\lambda }_{max}\left(A\right)\times eigtol$, where ${\lambda }_{min}\left(A\right)$ and ${\lambda }_{max}\left(A\right)$ denote the minimum and maximum eigenvalues of $A$ respectively, $A$ is positive definite.

If $eigtol\le 0$, machine precision is used.

Returns

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

Contains the matrix $X$.

alphafloat

$\alpha$.

iteraint

The number of iterations taken.

eigminfloat

The smallest eigenvalue of the leading principal submatrix $A$.

normfloat

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

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n>0$.

(errno $3$)

On entry, $k=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $n\ge k>0$.

(errno $5$)

The $k\times k$ principal leading submatrix of the initial matrix $G$ is not positive definite.

(errno $6$)

Failure to solve intermediate eigenproblem. This should not occur. Please contact NAG.

Notes

corrmat_shrinking finds a correlation matrix, $X$, starting from an approximate correlation matrix, $G$, with positive definite leading principal submatrix of order $k$. The returned correlation matrix, $X$, has the following structure:

$$\begin{array}{c}X=\alpha \left(\begin{array}{cc}A& 0\\ 0& I\end{array}\right)+(1-\alpha )G\end{array}$$

where $A$ is the $k\times k$ leading principal submatrix of the input matrix $G$ and positive definite, and $\alpha \in [0,1]$.

corrmat_shrinking utilizes a shrinking method to find the minimum value of $\alpha$ such that $X$ is positive definite with unit diagonal.

References

Higham, N J, Strabić, N and Šego, V, 2014, Restoring definiteness via shrinking, with an application to correlation matrices with a fixed block, MIMS EPrint 2014.54, Manchester Institute for Mathematical Sciences, The University of Manchester, UK