naginterfaces.library.correg.corrmat_​target

naginterfaces.library.correg.corrmat_target(g, theta, h, errtol=0.0, eigtol=0.0)

corrmat_target computes a correlation matrix, by using a positive definite target matrix derived from weighting the approximate input matrix, with an optional bound on the minimum eigenvalue.

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

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

Parameters

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

$G$, the initial matrix.

thetafloat

The value of $\theta$. If $theta<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$, $\sqrt{\text{machine precision}}$ is used.

See Accuracy for further details.

eigtolfloat, optional

The tolerance used in determining the definiteness of the target matrix $T=H\circ G$.

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

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

Returns

hfloat, ndarray, shape $(n,n)$

A symmetric matrix $\frac{1}{2}(H+H^T)$ with its diagonal elements set to $1.0$.

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

Contains the matrix $X$.

alphafloat

The constant $\alpha$ used in the formation of $X$.

iteraint

The number of iterations taken.

eigminfloat

The smallest eigenvalue of the target matrix $T$.

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, $theta=⟨value⟩$.

Constraint: $theta<1.0$.

(errno $6$)

The target matrix is not positive definite.

(errno $7$)

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

Notes

Starting from an approximate correlation matrix, $G$, corrmat_target finds a correlation matrix, $X$, which has the form

$$X=\alpha T+(1-\alpha )G\text{,}$$

where $\alpha \in [0,1]$ and $T=H\circ G$ is a target matrix. $C=A\circ B$ denotes the matrix $C$ with elements $C_{ij}=A_{ij}\times B_{ij}$. $H$ is a matrix of weights that defines the target matrix. The target matrix must be positive definite and thus have off-diagonal elements less than $1$ in magnitude. A value of $1$ in $H$ essentially fixes an element in $G$ so it is unchanged in $X$.

corrmat_target utilizes a shrinking method to find the minimum value of $\alpha$ such that $X$ is positive definite with unit diagonal and with a smallest eigenvalue of at least $\theta \in [0,1)$ times the smallest eigenvalue of the target matrix.

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