pystra.dependence.correlation.CorrelationMatrix

Use it: User guide · Worked example · Theory

class CorrelationMatrix(matrix)

Bases: object

Validated correlation matrix of the physical variables.

The \((i, j)\) entry is \(\text{corr}(X_i, X_j)\). The matrix is checked when it is created: square, finite, symmetric, with a unit diagonal and positive definite. It is held as a read-only array, so build a new matrix rather than editing one. Elements can be read with [], and numpy.asarray returns the matrix.

Parameters:

matrix (ArrayLike) – Symmetric positive-definite matrix with a unit diagonal.

Raises:

ModelError – If the matrix is not a valid correlation matrix.

Methods

cholesky	Return the lower-triangular factor \(L\) with \(R = L L^T\).
get_matrix	Return the correlation matrix as a read-only NumPy array.
nataf	Return the Nataf correlation for this matrix and the model's marginals.
nearest_positive_definite	Return the nearest valid correlation matrix to matrix.

property matrix: ndarray

The matrix, as a read-only array.

get_matrix()

Return the correlation matrix as a read-only NumPy array.

Return type:

ndarray

cholesky()

Return the lower-triangular factor \(L\) with \(R = L L^T\).

Return type:

ndarray

nataf(model)

Return the Nataf correlation for this matrix and the model’s marginals.

The correlation of the standard-normal variables that the Nataf transformation uses to reproduce this correlation between physical variables with the marginal distributions of model. For normal marginals it equals this matrix.

Parameters:

model (StochasticModel) – Supplies the marginal distributions, in matrix order.

Return type:

CorrelationMatrix

classmethod nearest_positive_definite(matrix, *, min_eigenvalue=1e-10, max_iterations=100)

Return the nearest valid correlation matrix to matrix.

Uses Higham’s (2002) alternating projections between the positive semidefinite matrices and the matrices with a unit diagonal, then raises the eigenvalues to at least min_eigenvalue so that the result is positive definite, and restores the unit diagonal. Use it to repair an estimate, for example one assembled from pairwise data, that is not positive definite.

Parameters:

• matrix (ArrayLike) – Square matrix, symmetrized before projection.

• min_eigenvalue (float) – Smallest eigenvalue of the result before the diagonal is restored.

• max_iterations (int) – Limit on the alternating projections.

Return type:

CorrelationMatrix

References

Higham, N. J. (2002). Computing the nearest correlation matrix: a problem from finance. IMA Journal of Numerical Analysis, 22(3), 329-343.