uncertainty.draws¶

Correlated draws of the variables of an uncertainty analysis.

The points of the unit cube are quasi-random (scrambled Sobol points, the default, Owen 1998; Joe & Kuo 2008), a Latin hypercube or random. Their normal scores z = Φ⁻¹(u) are correlated with the Cholesky factor of the correlation of the normal scores, z L^T, mapped back to the unit interval, Φ(z), and through the inverse distribution function of every marginal (a Gaussian copula, Nelsen 2006). For normal marginals this is the multivariate normal of the covariance, for log-normal marginals the multivariate normal of their logarithms; for other marginals the correlation is the one of the normal scores, about the same rank correlation.

The correlation of the normal scores comes from the covariances of the analysis (normal_score_correlation):

• a correlation: the coefficients between the normal scores (for log-normal marginals between the logarithms)
• a covariance of normal marginals: Σ_ij / (sd_i sd_j)
• a covariance on the log scale of log-normal marginals: Σ_ij / (σ_i σ_j) with the standard deviations σ of the logarithms
• a covariance on the linear scale of log-normal marginals: the exact conversion ln(1 + Σ_ij / (μ_i μ_j)) / (σ_i σ_j) with the means μ

The variances of a covariance must be the variances of the marginals (a relative tolerance of 1e-6), which the marginals define.

Owen AB (1998). Scrambling Sobol' and Niederreiter-Xing points. J Complexity 14:466-489. Joe S, Kuo FY (2008). Constructing Sobol sequences with better two-dimensional projections. SIAM J Sci Comput 30:2635-2654. Nelsen RB (2006). An Introduction to Copulas, 2^nd ed. Springer.

normal_score_correlation(variables, covariance)

unit_points(d, n, *, design='sobol', seed, start=0)

draw(
    variables,
    covariance,
    n,
    *,
    design="sobol",
    seed,
    start=0,
    model=None,
    simulation=None,
    scenario=None,
)