Utility functions

This page includes useful functions that are not categorised.

Correlation

Map arbitrary correlation matrix to Gaussian.

This module implements methods from two papers to map arbitrary correlation matrix into correlation matrix for Gaussian copulas.

econsa.correlation.gc_correlation(marginals, corr, order=15, force_calc=False)[source]

Correlation for Gaussian copula.

This function implements the algorithm outlined in Section 4.2 of [K2012] to map arbitrary correlation matrix to an correlation matrix for Gaussian copula. For special combination of distributions, use the values from Table 4. of [L1986].

Since chaospy’s copula functions only accept positive definite correlation matrix, this function also checks the output, and transforms to nearest positive definite matrix if it is not already.

Numerical integration is calculated with Gauss-Hermite quadrature ([D1984]).

Parameters

  • marginals (chaospy.distributions) – Marginal distributions of the correlated variables. All marginals must be chaospy distributions, otherwise returns error.

  • corr (array_like) – The correlation matrix to be transformed.

  • order (int, optional) – The order of grids used to generate for integration. The total number of used points is calculated as \((\text{order}+1)^2\). Values larger than 20 are not recommended. (default value is 15)

  • force_calc (bool, optional) – When True, calculate the covariances ignoring all special combinations of marginals (default value is False).

Returns

gc_corr – The transformed correlation matrix that is ready to be fed into a Gaussian copula.

Return type

numpy.ndarray

References

K2012

Kucherenko, S., Tarantola, S., & Annoni, P. (2012). Estimation of global sensitivity indices for models with dependent variables. Computer Physics Communications, 183(4), 937–946.

L1986

Liu, P., & Der Kiureghian, A. (1986). Multivariate distribution models with prescribed marginals and covariances. Probabilistic Engineering Mechanics, 1(2), 105–112.

D1984

Davis, P. J., & Rabinowitz, P. (1984). Methods of numerical integration (2nd ed.). Academic Press.

Examples

>>> corr = [[1.0, 0.6, 0.3], [0.6, 1.0, 0.0], [0.3, 0.0, 1.0]]
>>> marginals = [cp.Normal(1.00), cp.Uniform(lower=-4.00), cp.Normal(4.20)]
>>> corr_transformed = gc_correlation(marginals, corr)
>>> copula = cp.Nataf(cp.J(*marginals), corr_transformed)
>>> corr_copula = np.corrcoef(copula.sample(1000000))
>>> np.testing.assert_almost_equal(corr, corr_copula, decimal=6)