UQ[PY]LAB USER MANUAL
THE INPUT MODULE
C. Lataniotis, E. Torre, S. Marelli, B. Sudret
CHAIR OF RISK, SAFETY AND UNCERTAINTY QUANTIFICATION
STEFANO-FRANSCINI-PLATZ 5
CH-8093 Z
¨
URICH
Risk, Safety &
Uncertainty Quantification
How to cite UQ[PY]LAB
C. Lataniotis, S. Marelli, B. Sudret, Uncertainty Quantification in the cloud with UQCloud, Proceedings of the 4th
International Conference on Uncertainty Quantification in Computational Sciences and Engineering (UNCECOMP
2021), Athens, Greece, June 27–30, 2021.
How to cite this manual
C. Lataniotis, E. Torre, S. Marelli, B. Sudret, UQ[py]Lab user manual – The Input module, Report UQ[py]Lab
-V1.0-102, Chair of Risk, Safety and Uncertainty Quantification, ETH Zurich, Switzerland, 2024
BIBT
E
X entry
@TechReport{UQdoc_10_102,
author = {Lataniotis, C. and Torre, E. and Marelli, S. and Sudret, B.},
title = {{UQLab user manual -- The Input module }},
institution = {Chair of Risk, Safety and Uncertainty Quantification, ETH Zurich,
Switzerland},
year = {2024},
note = {Report UQ[py]Lab - V1.0-102}
}
List of contributors:
Name Contribution
A. Hlobilov
´
a Translation from the UQLab manual
Document Data Sheet
Document Ref. UQ[PY]LAB-V1.0-102
Title: UQ[PY]LAB user manual – The Input module
Authors: C. Lataniotis, E. Torre, S. Marelli, B. Sudret
Chair of Risk, Safety and Uncertainty Quantification, ETH Zurich,
Switzerland
Date: 27/05/2024
Doc. Version Date Comments
V0.8 19/09/2022 Initial release
V1.0 27/05/2024 Minor update for UQ[PY]LAB release 1.0
Abstract
The UQ[PY]LAB INPUT module is used to define the probabilistic input model in uncertainty
quantification problems. It offers extensive possibilities to perform operations like drawing
samples of random vectors, or transforming samples of random vectors to samples of dif-
ferent random vectors (isoprobabilistic transforms). The dependence structure between the
components of random vectors is specified with the copula formalism.
This user manual includes a review of the methods that are used to define, draw and trans-
form samples of random vectors. It also contains information about each of the available
probability distributions that can be used in the current version of UQ[PY]LAB. After in-
troducing the theoretical aspects, an in-depth example-driven user guide is provided to help
new users to properly set up and use the INPUT module objects. Finally, a comprehensive
reference list of the methods and functions available in the UQ[PY]LAB INPUT module is
given at the end of the manual.
Keywords: Probabilistic Input Model, Marginals, Copula, Isoprobabilistic Transforms, Sam-
pling
Contents
1 Theory 1
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Representation of univariate distributions . . . . . . . . . . . . . . . . . . . . 1
1.2.1 Parametric distributions . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2.2 Kernel density estimates . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2.3 Truncated distributions . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2.4 Marginals inferred from data . . . . . . . . . . . . . . . . . . . . . . . 2
1.3 Representation of dependencies through copulas . . . . . . . . . . . . . . . . 3
1.3.1 Sklar’s transformations for densities and conditional distributions . . . 3
1.3.2 Some properties of copulas . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4 Copulas currently available in UQ[PY]LAB . . . . . . . . . . . . . . . . . . . . 4
1.4.1 Independent copula . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4.2 Gaussian Copula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4.3 Pair copulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4.4 Vine copulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.4.5 Copulas inferred from data . . . . . . . . . . . . . . . . . . . . . . . . 10
1.5 Sampling random vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.5.1 Independence copula: probability integral transform . . . . . . . . . . 10
1.5.2 Gaussian copula: Nataf transform . . . . . . . . . . . . . . . . . . . . . 11
1.5.3 Other copulas: Rosenblatt transform . . . . . . . . . . . . . . . . . . . 12
2 Usage 13
2.1 Defining an INPUT object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.1.1 Defining the input marginals . . . . . . . . . . . . . . . . . . . . . . . 13
2.1.2 Defining the input copula . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.1.3 Independent subgroups of random variables . . . . . . . . . . . . . . . 20
2.1.4 Defining standard inputs . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.1.5 Input summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.2 Drawing samples from a distribution . . . . . . . . . . . . . . . . . . . . . . . 23
2.2.1 Selecting an INPUT object and specifying the sampling method . . . . . 23
2.3 Switching between input objects . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4 Enrichment of an experimental design with new samples . . . . . . . . . . . . 26
2.5 Performing an isoprobabilistic transform . . . . . . . . . . . . . . . . . . . . . 27
2.6 Adding bounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.7 Defining and using custom marginals . . . . . . . . . . . . . . . . . . . . . . . 28
2.8 Constant variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3 Reference List 31
3.1 Creating an INPUT object: uq.createInput . . . . . . . . . . . . . . . . . . . . 33
3.2 Getting samples from an INPUT object: uq.getSample . . . . . . . . . . . . . . 37
3.3 Printing/Visualizing an INPUT object . . . . . . . . . . . . . . . . . . . . . . . 38
3.3.1 Printing information: uq.print . . . . . . . . . . . . . . . . . . . . . . 38
3.3.2 Graphical visualization: uq.display . . . . . . . . . . . . . . . . . . . 38
3.4 Enriching an existing sample set . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.4.1 Enriching a Latin Hypercube: uq.enrichLHS . . . . . . . . . . . . . . . 39
3.4.2 Enriching a Sobol sequence: uq.enrichSobol . . . . . . . . . . . . . . 39
3.4.3 Enriching a Halton sequence: uq.enrichHalton . . . . . . . . . . . . . 40
3.4.4 Pseudo-LHS enrichment: uq.LHSify . . . . . . . . . . . . . . . . . . . 41
3.5 Sub-sampling an existing sample set: uq.subsample . . . . . . . . . . . . . . 42
3.6 Transforming samples between spaces . . . . . . . . . . . . . . . . . . . . . . 43
3.6.1 uq.GeneralIsopTransform . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.6.2 uq.IsopTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.6.3 uq.NatafTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
3.6.4 uq.invNatafTransform . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
3.6.5 uq.RosenblattTransform . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.6.6 uq.invRosenblattTransform . . . . . . . . . . . . . . . . . . . . . . . . 45
3.7 Convenience functions to define marginals and copulas . . . . . . . . . . . . . 46
3.7.1 uq.Marginals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.7.2 uq.StdNormalMarginals . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.7.3 uq.StdUniformMarginals . . . . . . . . . . . . . . . . . . . . . . . . . . 47
3.7.4 uq.KernelMarginals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
3.7.5 uq.GaussianCopula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.7.6 uq.PairCopula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.7.7 uq.VineCopula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.8 Additional functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.8.1 uq.sampleU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.8.2 uq.MarginalFields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.8.3 uq.estimateMoments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
3.8.4 uq.setDefaultSampling . . . . . . . . . . . . . . . . . . . . . . . . . . 52
3.8.5 uq.CopulaSummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4 Appendices 54
A List of univariate distributions supported in UQ[PY]LAB . . . . . . . . . . . . 54
A.1 Uniform distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
A.2 Gaussian (Normal) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
A.3 Lognormal distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
A.4 Gumbel distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
A.5 Gumbel-min distribution . . . . . . . . . . . . . . . . . . . . . . . . . . 58
A.6 Weibull distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
A.7 Gamma distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
A.8 Exponential distribution . . . . . . . . . . . . . . . . . . . . . . . . . . 61
A.9 Beta distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
A.10 Triangular distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
A.11 Logistic distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
A.12 Laplace distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
A.13 Rayleigh distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Chapter 1
Theory
1.1 Introduction
Identification and modelling of the sources of uncertainty are crucial steps for the solution
of any uncertainty quantification problem. In a probabilistic setting, each uncertain model
parameter can be represented by a random variable and a corresponding probability density
function (PDF) in the form X ∼ f
X
(x). Several input parameters, including their dependence
structure, can be grouped together in a random vector with joint PDF X ∼ f
X
(x). The INPUT
module in UQ[PY]LAB offers a suite of tools to handle the representation, transformation
and sampling of a wide variety of univariate and joint PDFs.
Within the UQ[PY]LAB, joint CDFs are represented by means of the copula formalism
(Nelsen, 2006). Copulas are a powerful tool to provide a simple representation of multivari-
ate distributions by separating the univariate distributions of each component of a random
vector (marginals) from their dependence structure (copula). The marginals and the copula
can thus be defined and specified separately, as detailed in the next sections.
1.2 Representation of univariate distributions
A random variable X can be represented by its univariate cumulative distribution function
(CDF) F
X
(x) = P(X ≤ x). One then write X ∼ F
X
. The derivative f
X
of a continuous CDF
F
X
, if existing, is called the probability density function (PDF) of X.
1.2.1 Parametric distributions
UQ[PY]LAB supports a number of continuous, differentiable distributions employed in many
fields of applied sciences, namely:
• Uniform
• Normal or Gaussian
• Lognormal
• Gumbel (maxima)
• Gumbel (minima)
• Beta
1
UQ[PY]LAB user manual
• Gamma
• Exponential
• Weibull
• Triangular
• Logistic
• Laplace
In Appendix A, a more extensive overview of each distribution and its properties (e.g., PDF,
cumulative distribution function, support, moments, parameters) are given for reference.
1.2.2 Kernel density estimates
Kernel density estimation (KDE), also called kernel smoothing, is a non-parametric method
to infer a univariate distribution directly from data. Given a set X = {x
(1)
, . . . , x
(n)
} of n
independent identically distributed (i.i.d) observations from an unknown PDF f
X
, the KDE
estimate of f
X
is defined as
ˆ
f
X
(x) =
1
nw
n
X
h=1
k
|x − x
(h)
|
w
!
. (1.1)
where k(·) is a non-negative function (kernel), which decays with the distance between the
point x where the distribution is evaluated and the point x
(h)
∈ X where the kernel is
centered. The parameter w, called the bandwidth, dictates how fast
ˆ
f
X
decays with |x − x
(h)
|.
A common choice for the kernel is the standard Gaussian distribution.
1.2.3 Truncated distributions
A truncated distribution results from restricting the support of a probability distribution.
Assume that a random variable X follows some distribution with CDF F
X
. Then, the CDF
and inverse CDF (“quantile function”) of the distribution truncated in [a, b] are defined as
F
X|[a,b]
(x) = F
X
(x|a ≤ X ≤ b) and F
−1
X|[a,b]
(x) = F
−1
X|[a,b]
(x|a ≤ X ≤ b), respectively, and are
given by
F
X|[a,b]
(X) =
0 , X ≤ a
F
X
(X)−F
X
(a)
F
X
(b)−F
X
(a)
, a < X < b
1 , X ≥ b
(1.2)
and
F
−1
X|[a,b]
(u) =
a , u = 0
F
−1
X
(F
X
(a) + u (F
X
(b) − F
X
(a))) , 0 < u < 1
b , u = 1
. (1.3)
A practical example of how truncated distributions are defined in UQ[PY]LAB is given in
Section 2.6.
1.2.4 Marginals inferred from data
UQ[PY]LAB provides the possibility to infer marginals from data based on different goodness-
of-fit criteria. More details about the theory underlying this topic and its usage in UQ[PY]LAB
UQ[PY]LAB-V1.0-102 - 2 -
The Input module
are provided in the UQ[PY]LAB User Manual – Statistical inference.
1.3 Representation of dependencies through copulas
An M-dimensional copula (or M -copula for brevity) is formally defined as a multivariate
distribution over [0, 1]
M
with uniform marginals in the unit interval. At the basis of the copula
formalism lies Sklar’s theorem, which states that, for any M-variate distribution F
X
of an M-
dimensional input random vector X = {X
1
, . . . , X
M
} with marginals F
X
1
, . . . , F
X
M
, there
exists a copula C such that
F
X
(x) = C(F
X
1
(x
1
), F
X
2
(x
2
), ..., F
X
M
(x
M
)). (1.4)
Thus, the copula C is the function that links the marginals F
X
i
of a random vector to its
joint CDF F
X
. C itself does not depend on the F
X
i
, and purely describes the statistical
interactions among the components X
i
of X, that is, their dependence structure. Besides, C
is unique if all F
X
i
are continuous. The converse also holds: for any M-copula C and any
set of marginals F
X
1
, . . . , F
X
M
, the function F
X
given by (1.4) is a joint CDF with marginals
F
X
1
, . . . , F
X
M
. This property is exploited in UQ[PY]LAB to define any joint distribution
by specifying separately its marginals and copula. This framework is ideal for uncertainty
quantification. Indeed, it is often the case that marginal distributions as well as some form
of correlation measure between variables are known or inferred from available data, but no
compound information about the joint distribution is readily available.
A detailed description of the copula formalism and of the plethora of available copulas and
copula families is outside the scope of this manual. The reader is referred to Nelsen (2006)
and Joe (2015) for more details and relevant literature.
1.3.1 Sklar’s transformations for densities and conditional distributions
Relations analogous to (1.4) hold for probability densities and conditional distributions.
From (1.4) the joint PDF of X is obtained by differentiation:
f
X
(x) = c (F
X
1
(x
1
), . . . , F
X
M
(x
M
))
M
Y
i=1
f
X
i
(x
i
), (1.5)
where c(·) is the copula density function obtained as
c(u
1
, . . . , u
M
) =
∂
M
C(u
1
, . . . , u
M
)
∂u
1
. . . ∂u
M
. (1.6)
For conditional densities
f
X
1
|X
2
,...,X
M
(x
1
|x
2
, . . . , x
M
) =
f
X
(x)
Q
M
i=2
f
X
i
(x
i
)
= c (F
X
1
(x
1
), . . . , F
X
M
(x
M
)) f
X
1
(x
1
).
(1.7)
UQ[PY]LAB-V1.0-102 - 3 -
UQ[PY]LAB user manual
1.3.2 Some properties of copulas
As mentioned in Section 1.3, a copula describes the dependence between the random vari-
ables it couples, independent of their marginals. The following properties of copulas hold:
• Given two random vectors X and X
′
such that X
′
i
= α
i
(X
i
), where α
i
(·) is a monotone
increasing transformation for each i = 1, . . . , M, then it is easy to prove that C
X
= C
X
′
;
• In particular, the random vector U such that U
i
= F
X
i
(X
i
) has copula C
U
≡ C
X
;
• Since U has standard uniform marginals, C
X
is also its joint CDF;
• Thus, C
X
can be interpreted as the joint distribution of transformations of the original
random variables into random variables with standard uniform distribution.
Besides, a useful property is the following: the copula C
X
of the random vector X = (X
1
, X
2
)
such that X
1
and X
2
are mutually independent is given by
C
X
≡ C
X
1
· C
X
2
. (1.8)
(An analogous expression holds for the copula density c
X
of X). By recursion, the formula
trivially generalizes to any number of independent subgroups. This makes it possible to
easily express the joint copula density/distribution between independent groups of random
variables as the product of the individual copula densities/distributions.
1.4 Copulas currently available in UQ[PY]LAB
UQ[PY]LAB currently supports a variety of copula families to represent dependence between
two or more random variables. The currently supported families are briefly characterized
below.
1.4.1 Independent copula
C(u
1
, . . . , u
M
) =
M
Y
i=1
u
i
(1.9)
By substituting Eq. (1.9) in (1.4), it is clear that it corresponds to the case in which the
components of the input random vector are independent. Indeed:
F
X
(x) = C(F
X
1
(x
1
), . . . , F
X
M
(x
M
)) =
M
Y
i=1
F
X
i
(x
i
). (1.10)
Consequently, the independent copula density is simply c(u
1
, . . . , u
M
) = 1. A graphical
representation of the independence copula PDF in dimension M = 2 is given for reference in
Figure 1, left panel.
UQ[PY]LAB-V1.0-102 - 4 -
The Input module
0 0.5 1
u
0
0.2
0.4
0.6
0.8
1
v
0 0.5 1
u
0
0.2
0.4
0.6
0.8
1
v
0 0.5 1
u
0
0.2
0.4
0.6
0.8
1
v
0 0.5 1
u
0
0.2
0.4
0.6
0.8
1
v
Figure 1: Scatter plot and PDF contour plot of different pair copulas. From left to right:
independence copula, Gaussian copula with parameter ρ = 0.7, t- copula with parameters
ρ = 0.7, ν = 2, and Gumbel copula with parameter τ = 1.5.
1.4.2 Gaussian Copula
C(u
1
, . . . , u
M
; R) = Φ
M
Φ
−1
(u
1
), . . . , Φ
−1
(u
M
); R
(1.11)
where R is the linear correlation matrix of the multivariate Gaussian distribution associated
with the Gaussian copula, Φ
M
(u; R) is the cumulative distribution function of an M-variate
Gaussian distribution with mean 0 and correlation matrix R and Φ
−1
(u
i
) is the inverse cu-
mulative distribution function of the standard normal distribution.
The Gaussian copula is one of the most commonly used copulas to parametrize the depen-
dence structure of random vectors with known marginals. If all the marginals as well as the
copula are Gaussian, the resulting joint PDF is also a multivariate normal distribution with
correlation matrix R. Another important property of the Gaussian copula is that a random
vector with Gaussian copula and diagonal correlation matrix R has independent components.
The Gaussian copula is asymptotically independent in both upper and lower tails. This means
that, no matter how high the parameter correlation coefficient R
ij
is, there will be no tail
dependence (see Nelsen (2006) for details).
A graphical representation of the Gaussian copula in dimension M = 2 is given for reference
in Figure 1, second panel.
1.4.3 Pair copulas
UQ[PY]LAB supports a variety of parametric pair copulas to represent dependencies among
M = 2 random variables. These copula families cover different aspects of bivariate depen-
dence, such as upper or lower tail dependence, asymmetric tails, and others. While some
of these families admit an extension to the multivariate case (M > 2), this extension is
typically non-unique and is not supported in UQ[PY]LAB. Flexible multivariate families in
UQ[PY]LAB are instead implemented in terms of vine copulas (see Section 1.4.4).
A list of pair copulas supported in UQ[PY]LAB is provided in Table 1. The densities of some of
them, as well as samples drawn these densities, are illustrated in Figure 1. For each supported
pair copula density, UQ[PY]LAB provides its rotations by 90
◦
, 180
◦
, and 270
◦
. A pair copula
rotated by 90
◦
or 270
◦
transforms positive dependence into negative and vice versa; a copula
rotated by 180
◦
can be used to switch the upper and lower tails. These rotations are defined
UQ[PY]LAB-V1.0-102 - 5 -
UQ[PY]LAB user manual
0 0.5 1
u
0
0.2
0.4
0.6
0.8
1
v
0 0.5 1
u
0
0.2
0.4
0.6
0.8
1
v
0 0.5 1
u
0
0.2
0.4
0.6
0.8
1
v
0 0.5 1
u
0
0.2
0.4
0.6
0.8
1
v
Figure 2: Rotated Gumbel copula. From left to right: rotation by 0, 90, 180, and 270 degrees.
The copula parameter is ρ = 2.
by the following equations:
C
(90)
(u, v) = v −C(1 − u, v),
C
(180)
(u, v) = u + v − 1 + C(1 − u, 1 − v), (1.12)
C
(270)
(u, v) = u − C(u, 1 −v).
(Note that C
(90)
and C
(270)
are obtained by flipping the copula density c around the vertical
and horizontal axis, respectively; some references provide the formulas for actual rotations:
C
(90)
(u, v) = v − C(v, 1 − u), C
(270)
(u, v) = u − C(1 − v, u)).
An example of rotated Gumbel pair copula is provided in Figure 2. The non-rotated Gumbel
copula assigns positive dependence as well as upper tail dependence to the random variables
it couples. The latter is visible as an accumulation of points in the upper right corner of
the unit square. The rotated versions implement negative dependence (rotations by 90
◦
and
270
◦
) or lower tail dependence (180
◦
).
1.4.4 Vine copulas
Flexible parametric families of multivariate copulas (M > 2) can be obtained by the product
of (possibly conditional) pair copulas. This construction, known as pair copula or vine con-
struction, was first introduced by Bedford and Cooke (2002) and later popularized by Aas
et al. (2009). To get an intuition why this construction is possible, let us first recall the chain
rule of probability which, in its version for probability densities, states that
f
X
(x) =
M
Y
j=1
f
j|j+1,...,M
(x
j
|x
j+1
, . . . , x
M
), (1.13)
where f
j|j+1,...,M
is the conditional PDF of X
j
given X
j+1
, . . . , X
M
. Recalling (1.5),
c (F
X
1
(x
1
), . . . , F
X
M
(x
M
))
M
Y
i=1
f
X
i
(x
i
) =
M
Y
j=1
f
j|j+1,...,M
(x
j
|x
j+1
, . . . , x
M
). (1.14)
Each conditional PDF on the right hand side of (1.14) can in turn be written in terms of a
pair copula density, that is a pair copula differentiated with respect to one of its arguments.
UQ[PY]LAB-V1.0-102 - 6 -
The Input module
Table 1: Pair copula families supported in UQ[PY]LAB. From left to right: copula name,
CDF, and parameter range. (a) Φ is the univariate standard normal distribution, and Φ
2;θ
is
the bivariate normal distribution with zero means, unit variances and correlation parameter
θ. (b) t
ν
is the univariate t distribution with ν degrees of freedom, and t
ν,θ
is the bivariate t
distribution with ν degrees of freedom and correlation parameter θ.
Name C(u, v; θ) Parameter range
Independence uv
Clayton (u
−θ
+ v
−θ
− 1)
−1/θ
θ > 0
Frank −
1
θ
log
1 −e
−θ
− (1 − e
−θu
)(1 −e
−θv
)
1 −e
−θ
θ ∈ R\{0}
Gaussian Φ
2;θ
Φ
−1
(u), Φ
−1
(v)
(a)
θ ∈ (−1, 1)
Gumbel exp
−((−log u)
θ
+ (−log v)
θ
)
1/θ
θ ∈ [1, + inf)
t- t
2;ν,θ
t
−1
ν
(u), t
−1
ν
(v)
(b)
ν > 1, θ ∈ (−1, 1)
Table 2: Some properties of pair copulas supported in UQ[PY]LAB. Kendall’s tau, tail
dependence coefficients, subfamilies of pair copulas that obtain for specific parameter values.
See also Torre et al. (2019).
Name τ
K
λ
l
λ
u
Special cases
Clayton
θ
θ + 2
2
−1/θ
0 —
Frank 1 +
4
θ
(
1
θ
Z
θ
0
t(e
t
− 1)
−1
dt − 1) 0 0 —
Gaussian
2
π
arcsin(θ) 0 0 —
Gumbel
θ − 1
θ
0 2 −2
1/θ
—
t
2
π
arcsin(θ) λ
l
= λ
u
=
(d)
—
= 2t
ν+1
−
p
(ν + 1)(1 − θ)/(1 + θ)
To understand why, for a general subset of indices A ⊂ {1, . . . , M}, let F
i|A
, f
i|A
, , C
i|A
and
c
i|A
indicate the CDF, PDF, copula distribution and copula density of the random variable X
i
UQ[PY]LAB-V1.0-102 - 7 -
UQ[PY]LAB user manual
conditioned on X
A
, respectively. Joe (1996) showed that, for any (j, i) ∈ A × A,
F
j|A
(x
j
|x
A
) =
∂C
ji|A\{i}
(u
j
, u
i
)
∂u
i
(F
j|A\{i}
(x
j
|x
A\{i}
), F
i|A\{i}
(x
i
|x
A\{i}
))
. (1.15)
Differentiating both sides with respect to u
j
yields
f
j|A
(x
j
|x
A
) = c
ji|A\{i}
(F
j|A\{i}
(x
j
|x
A\{i}
), F
i|A\{i}
(x
i
|x
A\{i}
)) · f
j|A\{i}
(x
j
|x
A\{i}
). (1.16)
In other words, a conditional PDF can be written as the product between a pair copula and
a conditional PDF of lower order. The latter can be in turn be written as the product of
another pair copula and a conditional PDF of yet lower order, and so on. Eventually, one can
rewrite the right hand side of (1.14) as a product of (conditional) pair copulas multiplied by
Q
i
F
X
i
(x
i
). The latter factor appears in the left hand side of (1.14) too, and can be simplified.
In conclusion, the joint copula density is expressed as a product of pair copulas:
• M − 1 unconditional pair copulas,
• M − 2 pair copulas conditioned on 1 variable,
• . . .
• 1 pair copula conditioned on M − 2 variables,
for a total of M(M −1)/2 pair copulas. Copulas expressed in this way are called vine copulas.
Note that the order of the variables used for the factorization in (1.14), as well as the index
i selected in (1.16), are arbitrary. Each choice corresponds to a different factorization of the
joint copula density into pair copula densities. To help organizing these different construc-
tions, Bedford and Cooke (2002) introduced two (non-exhaustive, but very broad) classes of
vine, representing two different choices for the vine factorization. These two classes, called
canonical (C-) and drawable (D-) vines, are supported in UQ[PY]LAB and are defined as
follows.
• C-vine
c(u) =
M−1
Y
j=1
M−j
Y
i=1
c
j,j+i|{1,...,j−1}
(u
j|{1,...,j−1}
, u
j+i|{1,...,j−1}
), (1.17)
A C-vine thus expresses an M-copula as a tensor product of
– M − 1 pair copulas between variable X
1
and X
j
, j = 2, . . . , M ,
– M − 2 pair copulas between X
2
and X
j
conditioned on X
1
, j = 3, . . . , M ,
– . . .
– the pair copula between X
M−1
and X
M
, conditioned on X
1
, . . . , X
M−2
.
A graphical representation is provided in Figure 3, left panel.
UQ[PY]LAB-V1.0-102 - 8 -
The Input module
c
1,2
c
1,3
c
1,4
c
1,5
1
2
34
5
T
1
c
2,3
|1
c
2,4
|1
c
2,5 |1
1
2
34
5
T
2
c
3,4 |1,2
c
3,5
|1,2
1
2
34
5
T
3
c
4,5
|1,2,3
1
2
34
5
T
4
c
1,2
c
2,3
c
3,4
c
4,5
1 2 3 4 5
c
1,3 |2
c
2,4 |3
c
3,5 |4
1 2 3 4 5
c
1,4 |2,3
c
2,5 |3,4
1 2 3 4 5
c
1,5 |2,3,4
1 2 3 4 5
Figure 3: Graphical representation of C- and D-vines. The pair copulas in each tree of a
5-dimensional C-vine (left; conditioning variables are shown in grey) and of a 5-dimensional
D-vine (right; conditioning variables are those between the connected nodes).
• D-Vine
c(u) =
M−1
Y
j=1
M−j
Y
i=1
c
i,i+j|{i+1,...,i+j−1}
(u
i|{i+1,...,i+j−1}
, u
i+j|{i+1,...,i+j−1}
). (1.18)
A D-vine thus expresses an M-copula as a tensor product of
– M −1 unconditional pair copulas between variable X
i
and X
i+1
, i = 1, . . . , M −1,
– M − 2 pair copulas between X
i
and X
i+2
conditioned on X
i+1
, i = 1, . . . , M − 2,
– . . .
– the pair copula between X
1
and X
M
, conditioned on X
2
, . . . , X
M−1
.
A graphical representation of this structure is provided in the right panel of Figure 3.
C- and D-vine constructions require in general to specify different sets of pair copulas (except
when M = 3, in which case each D-vine is a C-vine and vice versa). Thus, one may prefer one
construction or the other depending on the type of information available. Besides, the pair
copulas involved in each of the two classes are fully determined by the order of the variables
X
1
, . . . , X
M
. An M-copula thus admits a factorization into M!/2 different C-vines and M!/2
different D-vines (the two classes being equivalent if M = 3).
Truncated vines. The pair copulas that a vine comprises can be grouped into different trees.
The first tree consists of all independent M − 1 unconditional pair copulas, the second tree
of all M − 2 pair copulas between random variables conditioned on another single variable,
and so on until the M − 1-th and last tree, consisting of a single pair copula between two
random variables conditioned on all other variables. In equations (1.17) and (1.18), the tree
index is represented by the variable j.
UQ[PY]LAB-V1.0-102 - 9 -
UQ[PY]LAB user manual
A vine is said to be truncated at level t
∗
∈ {1, . . . , M − 1}, if all pair copulas belonging to
any tree t ≥ t
∗
are the independence pair copula. The rationale for working with truncated
vines is that, often, only conditional probabilities of low order can be reasonably asserted or
reliably inferred from data, whereas imposing complex models for conditional probabilities
of higher order may correspond to over-interpreting or over-fitting data. Furthermore, con-
ditional probabilities of higher order typically have a weaker effect on the joint PDF of the
input random variables than those of lower order, especially if the strongest correlations are
captured in earlier trees, and can thus be neglected.
1.4.5 Copulas inferred from data
In addition to user-defined parametric copulas, UQ[PY]LAB supports the possibility to in-
fer copulas from data. The theory underlying this topic and its usage in UQ[PY]LAB are
extensively covered in the companion UQ[PY]LAB User Manual – Statistical inference.
1.5 Sampling random vectors
Various uncertainty quantification tasks require to generate data according to a specified
joint distribution. For instance, resampling from a known distribution of the inputs to a
system enables statistical estimation of the output by Monte-Carlo or by more sophisticated
strategies.
A number of random sampling strategies (e.g. Monte Carlo sampling, latin hypercube sam-
pling (LHS), pseudorandom sequences, etc.) are available to produce samples in the stan-
dard uniform space, that is, for Z ∼ U([0, 1]
M
). A possible strategy to sample from a different
distribution F
X
is thus to transform a sample z of Z into a sample x of X, if such a trans-
formation exists. Maps of the form (Lebrun and Dutfoy, 2009)
X = T (U ) s.t. X ∼ F
X
, U ∼ F
U
, (1.19)
which transform a random vector U ∼ F
U
(or a sample u thereof) into a random vector
X ∼ F
X
(or a sample x therefore) are called isoprobabilistic transforms. Amongst the many
strategies available to generate samples distributed according to a more general distribution
F
X
, UQ[PY]LAB makes use of isoprobabilistic transforms. Of particular interest for gener-
ating samples of X ∼ F
X
are isoprobabilistic transforms from U ∼ U([0, 1]
M
) to X . In the
following, isoprobabilistic transforms to different target distributions F
X
will be derived. We
will see that different transforms exist depending on the copula of C
X
of F
X
.
1.5.1 Independence copula: probability integral transform
A well known result of probability theory states that, for any random variable X with contin-
uous CDF F
X
, the random variable
U = F
X
(X) (1.20)
UQ[PY]LAB-V1.0-102 - 10 -
The Input module
is uniformly distributed in the unit interval: U ∼ U([0, 1]). The map (1.20) is also known as
probability integral transform (PIT) of X. Its inverse
X = F
−1
X
(U) (1.21)
thus maps U ∼ U([0, 1]) into X ∼ F
X
. The inverse PIT provides a simple way to transform an
M-variate sample U =
u
(1)
, . . . , u
(N)
∼ U([0, 1]
M
) into a sample X =
x
(1)
, . . . , x
(N)
∼ F
X
,
for any multivariate distribution F
X
with independent marginals F
X
i
– that is, with indepen-
dent copula (1.9). For all i = 1, . . . , N and all j = 1, . . . , M,
x
(i)
j
= F
−1
X
j
(u
(i)
j
). (1.22)
We call (1.22) the inverse PIT for random vectors.
1.5.2 Gaussian copula: Nataf transform
In the case of dependent variables, several extra steps are needed to transform a sample set
distributed according to U([0, 1]
M
) into a sample set with the desired joint PDF. When the
target joint PDF has Gaussian copula, a powerful tool to achieve this goal is the inverse Nataf
transform.
We first recall a fundamental result of probability theory: Gaussian random variables are
mutually independent if and only if they are uncorrelated. Based on this property, a Gaussian
random vector V with correlation matrix R can be transformed into a Gaussian random
vector W with uncorrelated (and therefore independent) components by
W = Γ
−1
V , (1.23)
where Γ
−1
is the inverse Choleski factor of R, satisfying the matrix equation ΓΓ
T
= R.
The Nataf transform maps a random vector X with Gaussian copula C
X
given by (1.11) and
arbitrary continuous marginals F
X
i
into W ∼ N(0, I
M
), where I
M
is the identity matrix in
R
M
, in three steps:
• X 7→ U ∼ C
X
: U
i
= F
X
i
(X
i
) ∼ U([0, 1]) (PIT of X)
• U 7→ V ∼ N(0, R) : V
i
= Φ
−1
(U
i
) ∼ N([0, 1]), where Φ is the standard normal CDF
• V 7→ W ∼ N(0, I
M
) through (1.23).
The first two steps involve monotonically increasing transformations of the marginals, thus
do not change the Gaussian copula of X (see Section 1.3.2). Therefore, V has standard
Gaussian marginals and Gaussian copula, that is, Gaussian joint PDF. Consequently, the ran-
dom vector W obtained by the last step is indeed multivariate standard normal. The inverse
map, called inverse Nataf transformation, maps the standard normal space to the space with
probability measure F
X
.
To further map W onto the uniform standard space, only the marginals of W need to be
transformed, by
UQ[PY]LAB-V1.0-102 - 11 -
UQ[PY]LAB user manual
• W 7→ Z : Z
i
= Φ(W
i
).
The inverse transformation is used to map the standard uniform space into the probability
space identified by F
X
, and thus to sample from F
X
. It reads:
1. Z 7→ W ∼ N(0, I
M
) : W
i
= Φ
−1
(Z
i
)
2. W 7→ V = Γ U ∼ N(0
M
, R)
3. V 7→ U ∼ C
X
: U
i
= Φ(V
i
)
4. U 7→ X ∼ F
X
: X
i
= F
−1
X
i
(U
i
)
1.5.3 Other copulas: Rosenblatt transform
The most general case of generating samples with an arbitrary M-dimensional copula can be
addressed by making use of the inverse Rosenblatt transform. First introduced by Rosenblatt
(1952), The Rosenblatt transform maps a random vector X with continuous marginals into
a random vector Z with independent, U([0, 1]) components. It reads
Z
1
= F
X
1
(X
1
)
Z
2
= F
X
2
|X
1
(X
2
|X
1
)
.
.
.
Z
M
= F
X
M
|X
1
,...,X
M−1
(X
M
|X
1
, . . . , X
M−1
)
. (1.24)
Within the copula formalism, one can perform the transform in two steps:
• X 7→ U ∼ C
X
, by the PIT (1.20)
• U 7→ Z : Z
i
= C
X
i
|X
1
,...,X
i−1
(u
i
|u
1
, . . . , u
i−1
).
The transformation is invertible (all conditional distributions are monotonically increasing).
Its inverse can be used to generate samples of X from samples of Z.
The applicability of the inverse Rosenblatt transform requires knowledge of the conditional
quantile functions C
−1
X
i
|X
1
,...,X
i−1
(u
i
|u
1
, . . . , u
i−1
), i = 1, . . . , M. While these are not available
for all classes of parametric copulas, they are for some (at least numerically), including vine
copulas (for details, see Aas et al. (2009)). UQ[PY]LAB provides algorithms to sample
from C- and D-vines, and uses an original implementation that capitalizes on the efficient
vectorization of the numerical inversion process.
Note: while the inverse Rosenblatt transform is a valid alternative to the inverse Nataf
transform for Gaussian copulas, it is computationally less efficient. The latter is
therefore used by UQ[PY]LAB in the presence of a Gaussian copula.
UQ[PY]LAB-V1.0-102 - 12 -
Chapter 2
Usage
2.1 Defining an INPUT object
As discussed in the theory chapter, a random vector in UQ[PY]LAB is defined by its marginal
distributions and the copula that defines their dependence structure. Marginals and copula
can be defined independently from each other, and together fully determine the joint PDF of
the input via the relation (1.4).
2.1.1 Defining the input marginals
2.1.1.1 The general case
An M-dimensional input requires the specification of M marginal distributions.
The following code defines a bivariate Gaussian random vector X = [X
1
, X
2
]
T
with inde-
pendent components (independence copula). The mean value and standard deviation of X
1
(resp. X
2
) are µ
1
= 1, σ
1
= 1 (resp. µ
2
= 2, σ
2
= 0.5):
from uqpylab import sessions
# Start the session
mySession = sessions.cloud()
# (Optional) Get a convenient handle to the command line interface
uq = mySession.cli
# Reset the session
mySession.reset()
# Specify the options for a bivariate normal random vector
Input = {
'Marginals': [
{
'Type': 'Gaussian',
'Parameters': [1, 1]
},
{
'Type': 'Gaussian',
'Moments': [2, 0.5]
}
]
}
# Create the bivariate normal random vector
13
UQ[PY]LAB user manual
myInput1 = uq.createInput(Input)
# Terminate the remote UQCloud session
mySession.quit()
Note that the copula has not been explicitly assigned: when not defined, UQ[PY]LAB by
default assumed it to be the independence copula (1.9). The corresponding code is (to be
typed before using uq.createInput ):
Input['Copula'] = {'Type': 'Independent'}
Also note that the first and second marginals have been specified through their parameters
and moments, respectively. For every marginal, either information is accepted, but not both.
When the INPUT object myInput1 is created, all parameters and moments for all variables
are computed and possible inconsistencies are checked.
2.1.1.2 Special cases of univariate distributions
Most of the available (built-in) distributions can be defined similarly to the way a Gaussian
distribution was defined in Section 2.1.1.1, i.e., either by defining the two parameters of the
distribution or its moments (mean and standand deviation). The meaning of the parameters
is as described in Appendix A. Some special cases are the following:
• For the exponential distribution only one parameter (λ) exists. When such a distribution
is defined by its parameters only one element is needed (λ). Additionally when it is
defined by its moments only one element is needed again which corresponds to the
mean and standard deviation (that are equal).
• For the beta distribution there is the possibility of using four parameters when a custom
support [a, b] needs to be defined. For example, in order to define an element of an
input vector that follows a beta distribution with parameters [r, s] = [1, 2] and support
[a, b] = [0.5, 1.5] we do the following:
'Marginals':
{
'Type': 'Beta',
'Parameters': [1, 2, 0.5, 1.5]
}
Similarly, we can define a beta distribution with moments [µ, σ] = [0.8, 0.2] and support
[a, b] = [0.5, 1.5] as follows:
'Marginals':
{
'Type': 'Beta',
'Moments': [0.8, 0.2, 0.5, 1.5]
}
In this case the two parameters r, s are computed according to the equations in Sec-
tion A.9.
UQ[PY]LAB-V1.0-102 - 14 -
The Input module
• A marginal obtained through kernel smoothing on a data set X can be represented by
'Marginals':
{
'Type': 'ks',
'Parameters': X,
}
which by default uses a Gaussian kernel with bandwidth optimized on the data. The
additional key 'Options' can be used to optionally specify the kernel type, bandwidth,
and the distribution bounds. For instance, the additional lines of code
'Marginals':
{
'Type': 'ks',
'Parameters': X,
'Options': {
'Bandwidth': 0.1,
'Support': [0, 5]
}
}
specify that a kernel bandwidth w = 0.1 must be used, and that the KDE distribution is
defined within the interval [0, 5].
2.1.1.3 Marginals inferred from data
The code needed to instruct UQ[PY]LAB to infer the marginals from data is explained in
detail in the companion UQ[PY]LAB User Manual – Statistical inference.
2.1.1.4 Convenience functions for specific marginals
A number of convenience functions are available to quickly generate data structures that
define marginals of specific types:
• uq.Marginals can be used to conveniently generate any given number of marginals
of the same parametric family and parameters (or moments);
• uq.StdUniformMarginals specifically generates standard uniform marginals;
• uq.StdNormalMarginals specifically generates standard normal marginals;
• uq.KernelMarginals specifically generates marginals by kernel smoothing.
For more details on these functions, see Section 3.7.
2.1.2 Defining the input copula
Let us now create another INPUT object where dependency between the marginals is intro-
duced by imposing a copula. Below, various parametric copulas supported by UQ[PY]LAB
are covered. For copulas inferred from data, see the companion UQ[PY]LAB User Manual –
Statistical inference.
UQ[PY]LAB-V1.0-102 - 15 -
UQ[PY]LAB user manual
2.1.2.1 Gaussian copula
As discussed in Section 1.4.2, the Gaussian copula takes as parameter the linear correla-
tion matrix R of the copula, which is here taken to be R =
1 0.8
0.8 1
(linear correlation
coefficient ρ
12
= 0.8).
Input['Name'] = 'Input 2: Dependent marginals'
Input['Copula'] = {
'Type': 'Gaussian',
'RankCorr': [[1, 0.8],[0.8, 1]]
}
myInput2 = uq.createInput(Input)
X = uq.getSample(myInput2, 300)
0 2 4
1
1.5
2
2.5
3
3.5
4
X
1
X
2
Figure 4: Samples drawn from a 2-D Gaussian distribution with a Gaussian copula (correla-
tion coefficient ρ
12
= 0.8). The sampling method is plain Monte Carlo.
The resulting samples are plotted in Figure 4. By default the sampling method that is
used is Monte Carlo. Also notice that we can assign custom names to an INPUT object, e.g.
'Input 2: Dependent marginals' in the present case.
Note: The code above assumes that the values for 'Marginals' keys have been pre-
viously assigned, as in Section 2.1.1.1. In other words, after creating the IN-
PUT myInput1 , we replace the independence copula by the Gaussian one in the
'Copula' value, and create a second INPUT myInput2 .
UQ[PY]LAB-V1.0-102 - 16 -
The Input module
2.1.2.2 Pair copula
A pair copula is defined in UQ[PY]LAB by
Input['Copula'] = {'Type': 'Pair'}
Additionally, the copula’s Family and Parameters must be provided. As an optional
argument, pair copula densities of standard parametric families can be rotated by 90, 180 or
270 degrees through the additional key Rotation .
The code below defines a Clayton pair copula (see Table 1), whose density is rotated by 90
◦
.
This allows us to introduced a negative correlation between the coupled random variables
X
1
and X
2
. Beside, the non-rotated Clayton pair copula has lower tail dependence coeffi-
cient. Therefore, its rotated version assigns lower tail dependence between −X
1
and X
2
, as
apparent from the cloud of points extending into the lower right corner of Figure 5.
Input['Name'] = 'Input 3: Negative correlation'
Input['Copula'] = {
'Type': 'Pair',
'Family': 'Clayton',
'Rotation': 90,
'Parameters': 1.5
}
myInput3 = uq.createInput(Input)
X = uq.getSample(myInput3, 300)
2.1.2.3 Vine copula: C-Vine and D-Vine
Specifying a higher-dimensional copula by vine construction (see Section 1.4.4) requires to
define all comprising pair copulas. The vine structure specifies which of the M!/2 possible
orders of the variables is chosen for the construction, and thus which set of pair copulas are
explicitly provided in the vine construction. UQ[PY]LAB currently supports two classes of
vines: canonical (C-) vines and drawable (D-) vines.
The example below constructs a 3-dimensional C-vine obtained as a tensor product of pair
copula densities c
21
, c
23
and c
13|2
, that is, vine structure 2 − 1 − 3. The three copulas are,
respectively: a 't'- copula, with parameters [.4, 2], a 'Frank'- copula with parameter 0.5,
and the 'Independence'- copula. The third variable is assigned an exponential marginal.
A sample set from this distribution is shown in Figure 6.
Input = {
'Marginals': [
{
'Type': 'Gaussian',
'Parameters': [1, 1]
},
{
'Type': 'Gaussian',
'Moments': [2, 0.5]
},
{
'Type': 'Exponential',
UQ[PY]LAB-V1.0-102 - 17 -
UQ[PY]LAB user manual
−2 0 2 4
0.5
1
1.5
2
2.5
3
3.5
X
1
X
2
Figure 5: Monte Carlo samples drawn from a 2-D distribution with Gaussian marginals and
Clayton copula (ρ = 1.5) rotated by 90
◦
.
'Parameters': [1.5]
}
]
}
Input['Name'] = 'Input 4: 3D C-Vine'
Input['Copula'] = {
'Type': 'CVine',
'Structure': [2, 1, 3],
'Families': ['t', 'Frank', 'Independence'],
'Rotations': [0, 0, 0],
'Parameters': [[.4, 2], .5, []]
}
myInput4 = uq.createInput(Input)
X = uq.getSample(myInput4, 300)
For a complete list of options to specify for a vine copula, see Table 6 and Table 8.
The set of pair copulas that a vine comprises are often not easy to keep track of, especially
with higher dimension M. This information can be print on screen using the code below (for
a 4-dimensional 'CVine' with structure [4, 1, 2, 3]):
print(uq.CopulaSummary('CVine', [4, 1, 3, 2]))
which prints the text:
Type: CVine
UQ[PY]LAB-V1.0-102 - 18 -
The Input module
−2 0 2 4
0
50
100
150
0 1 2 3 4
−2
0
2
4
0 2 4
−2
0
2
4
−2 0 2 4
0
1
2
3
4
0 1 2 3 4
0
50
100
150
200
0 2 4
0
1
2
3
4
−2 0 2 4
0
2
4
0 1 2 3 4
0
2
4
0 1 2 3 4
0
100
200
300
X
1
X
2
X
3
X
1
X
2
X
3
Figure 6: Monte Carlo samples drawn from a 3-D distribution with C-vine copula.
Dimension: 4
Structure: [4;1;3;2]
Pair copulas:
Index | Pair Copula
==================================
1 | C_4,1
2 | C_4,3
3 | C_4,2
4 | C_1,3|4
5 | C_1,2|4
6 | C_3,2|4,1
For a detailed use of the function uq.CopulaSummary , see Section 3.8.5.
Additionally, a graph of the vine’s constituting pair copulas and edges among them, such as
those shown in Figure 3, can be visualized using the function uq.display with show_vine=True
input parameter.
2.1.2.4 Truncated vines
As discussed in Section 1.4.4, the higher-order dependencies needed for the construction of
a vine copula may be difficult to assert, or to reliably infer from data. Also, when setting the
UQ[PY]LAB-V1.0-102 - 19 -
UQ[PY]LAB user manual
Table 3: Number of non-truncated pair copulas for a vine of dimension M truncated at tree
t. The last row, where t = M , corresponds to the no-truncation case and indicates the total
number of pair copulas in the vine.
∗
: no truncation, because t ≥ M : all pair copulas need
to be specified.
t
M
3 4 5 6 7 8 9 10
2 2 3 4 5 6 7 8 9
3 3
∗
5 7 9 11 13 15 17
4 3
∗
6
∗
9 12 15 18 21 24
5 3
∗
6
∗
10
∗
14 18 22 26 30
.
.
.
M 3 6 10 15 21 28 36 45
vine structure such that pair copulas among more strongly correlated random variables are
captured in earlier trees, higher-order dependencies play a less significant role in shaping the
joint PDF and can often be neglected. This is also the approach taken by UQ[PY]LAB and
by most software when inferring vine copulas from data (see the UQ[PY]LAB User Manual –
Statistical inference, Section 1.3.3).
Representing a vine truncated at tree t is possible by using the additional code
Input['Copula']['Truncation'] = t
for any t = 1, . . . , M , where t = 1 sets all pair copulas to the independence pair copula, and
thus the vine to the independence M-copula, and t = M corresponds to no truncation. Values
of t lower than 1 or larger than M are also interpreted by UQ[PY]LAB as no truncation.
Note: For a vine truncated at level t, only the pair copulas in the first t − 1 trees need
to be specified. The others are by definition the independence copula.
Since the j-th tree contains M −j copulas, a total of (M −1) + (M −2) + . . . + (M −t −1) =
(t − 1)M − t(t + 1)/2 are to be defined (see Table 3 for the number of non-truncated pair
copulas in a vine for different values of M and t). UQ[PY]LAB additionally handles several
special cases as follows:
• an error is thrown if not enough or too many pair copulas are specified (for instance, if
M = 10, t = 3 and less than 17 or more than 45 pair copulas are provided);
• a warning is given if more pair copulas than the non-truncated ones are specified (for
instance, if M = 10, t = 3 and more than 17 pair copulas are provided).
2.1.3 Independent subgroups of random variables
As mentioned in Section 1.3.2, the copula of a random vector consisting of independent
subgroups of random variables is given by the product of the copulas of all subgroups (see
(1.8) for the case d = 2). Subgroup independence can be specified in UQ[PY]LAB by simply
UQ[PY]LAB-V1.0-102 - 20 -
The Input module
defining any number of input copulas, and the variables associated to each one. The full
copula is automatically understood to be the tensor product of the individual copulas. For
instance, the code below defines an input consisting of 5 standard normal random variables,
three of which (X
1
, X
4
and X
5
) are coupled by a Gaussian copula, the remaining coupled by
a Gumbel pair copula:
iOpts = { 'Marginals' : uq.StdNormalMarginals(5)}
iOpts['Copula'] = [
{
'Type': 'Gaussian',
'RankCorr': [[1, .5, -.3], [.5, 1, .2],[-.3, .2, 1]],
'Variables': [1, 4, 5],
},
{
'Type': 'Pair',
'Family': 'Gumbel',
'Parameters': 1.5,
'Variables': [2, 3]
}
]
myInput = uq.createInput(iOpts)
uq.print(myInput)
==============================================================
Input object name: Input 7
Dimension(M): 5
Marginals:
Index | Name | Type | Parameters | Moments
--------------------------------------------------------------------------
1 | X1 | Gaussian | 0.000e+00, 1.000e+00 | 0.000e+00, 1.000e+00
2 | X2 | Gaussian | 0.000e+00, 1.000e+00 | 0.000e+00, 1.000e+00
3 | X3 | Gaussian | 0.000e+00, 1.000e+00 | 0.000e+00, 1.000e+00
4 | X4 | Gaussian | 0.000e+00, 1.000e+00 | 0.000e+00, 1.000e+00
5 | X5 | Gaussian | 0.000e+00, 1.000e+00 | 0.000e+00, 1.000e+00
Copula:
Tensor product of 2 copulas between the random vectors
X_[1;4;5], X_[2;3]
Copula 1, of X_[1;4;5]:
Type: Gaussian
Dimension: 3
Variables coupled: [1;4;5]
Parameters:
[+1.0000 +0.5176 -0.3129 ;
+0.5176 +1.0000 +0.2091 ;
-0.3129 +0.2091 +1.0000 ]
Copula 2, of X_[2;3]:
Type: Pair
Variables coupled: [2;3]
Family: Gumbel
Rotation: 0
Parameters: 1.5
UQ[PY]LAB-V1.0-102 - 21 -
UQ[PY]LAB user manual
==============================================================
All copula types can be freely combined, and there is no restriction on their individual pa-
rameters.
2.1.4 Defining standard inputs
Some multivariate distributions are often used in various types of statistical analysis. This
is the case of the M -variate standard uniform (resp. standard normal) distributions, that is,
distributions with U([0, 1]) (resp. N(0, 1)) marginals. To create an input object with standard
uniform (resp. standard normal) marginals and copula myCopula the convenience function
uq.StdUniformMarginals (resp. uq.StdNormalMarginals ) can be used:
Input = {'Marginals': uq.StdUniformMarginals(10)}
Input['Copula'] = myCopula
myInput1 = uq.createInput(Input)
(For details on how to specify the copula, see Section 2.1.2).
For a comprehensive list of all the available convenience functions in the INPUT module,
please refer to Section 3.7.
2.1.5 Input summary
Once an INPUT object has been created, a summary of its marginals and copulas can be
printed on screen via the uq.print command.
Input = {'Marginals': uq.Marginals(1, 'Gaussian', [1, 1]) +
uq.Marginals(1, 'Gaussian', [2, 0.5])}
Input['Copula'] = uq.GaussianCopula([[1, .8],[.8, 1]])
myInput1 = uq.createInput(Input)
uq.print(myInput1)
==============================================================
Input object name: Input 1
Dimension(M): 2
Marginals:
Index | Name | Type | Parameters | Moments
--------------------------------------------------------------------------
1 | X1 | Gaussian | 1.000e+00, 1.000e+00 | 1.000e+00, 1.000e+00
2 | X2 | Gaussian | 2.000e+00, 5.000e-01 | 2.000e+00, 5.000e-01
Copula:
Type: Gaussian
Dimension: 2
Variables coupled: [1 2]
Parameters:
[+1.0000 +0.8000 ;
+0.8000 +1.0000 ]
==============================================================
UQ[PY]LAB-V1.0-102 - 22 -
The Input module
For visual inspection of an INPUT object, the function uq.displaycan be used as follows:
uq.display(myInput1)
The result is shown in Figure 7.
−2 0 2 4
0.5
1
1.5
2
2.5
3
3.5
X
1
X
2
Figure 7: The output of the function uq.display on the INPUT object myInput1 . By
default, the samples are drawn using Monte Carlo sampling.
2.2 Drawing samples from a distribution
It is possible to draw samples from the INPUT object myInput1 as follows:
X = uq.getSample(N=300)
Notice that we do not need to define the INPUT object in uq.getSample , because after
an INPUT object is created, if not specified otherwise, it is the one that is going to be used
when calling uq.getSample . Methods to handle different INPUT objects in the workspace
are described in Section 2.3. The MATLAB standard random number generator is used by
default.
2.2.1 Selecting an INPUT object and specifying the sampling method
When handling several INPUT objects in parallel, the last one that has been defined is used
by default for sampling. There are two ways to use an INPUT object different from the last
defined one:
• Using the function uq.selectInput . For example, drawing 300 samples from the
INPUT object myInput1 can be achieved as follows:
UQ[PY]LAB-V1.0-102 - 23 -
UQ[PY]LAB user manual
uq.selectInput(myInput1)
X = uq.getSample(N=300)
• Specifying the INPUT object directly in uq.getSample . For example, drawing 300
samples from the INPUT object myInput1 can be achieved as follows:
X = uq.getSample(myInput1, 300)
When using uq.getSample in order to obtain samples from a random vector, various sam-
pling methods can be used. For instance Latin Hypercube Sampling (McKay et al., 1979) can
be used to sample from the INPUT object myInput2 as follows:
X = uq.getSample(myInput2, 300, 'LHS')
The result is shown in Figure 8. For a list of all the available sampling methods refer to
Table 11 in Section 3.2.
−2 0 2 4
0.5
1
1.5
2
2.5
3
3.5
X
1
X
2
Figure 8: Samples drawn from INPUT myInput1 using the Latin Hypercube sampling
method.
Advanced options
Instead of using the 'LHS' argument in uq.getSample one could also change the default
sampling method of the INPUT object myInput2 as follows:
uq.selectInput(myInput2)
uq.setDefaultSampling(Method='LHS')
UQ[PY]LAB-V1.0-102 - 24 -
The Input module
Note that this does not affect other INPUT objects, i.e.the sampling method for myInput1 is
still plain Monte Carlo.
2.3 Switching between input objects
Suppose we want to draw two sample sets:
• 200 Monte Carlo samples from the input vector myInput1 defined above, and having
components coupled by a Gaussian copula;
• 300 LHS samples from the input vector myInput2 defined right below, whose marginal
X
1
is bounded and independent from X
2
.
Input2 = {'Marginals': uq.Marginals(1, 'Gaussian', [1, 1]) +
uq.Marginals(1, 'Gaussian', [2, 0.5])}
Input2['Marginals'][0]['Bounds'] = [-3, 2]
myInput2 = uq.createInput(Input2)
This is carried out as follows:
uq.selectInput(myInput1)
X2 = uq.getSample(N=200, Method='MC')
uq.selectInput(myInput2)
X3 = uq.getSample(N=300, Method='LHS')
The two samples are plotted in Figure 9.
−2 0 2 4
−4
−2
0
2
4
6
8
myInput1
myInput2
X
1
X
2
Figure 9: Samples drawn from two different cases of a 2-D Gaussian distribution. The INPUT
object myInput1 has dependent marginals and the INPUT object myInput2 has independent
marginals and bounds on X
1
∈ [−3, 2]. The sampling method is Latin Hypercube sampling.
UQ[PY]LAB-V1.0-102 - 25 -
UQ[PY]LAB user manual
2.4 Enrichment of an experimental design with new samples
Enrichment is a functionality that can be used when there is an already existing sample set
(called experimental design in the context of metamodelling) to which more points need to
be added. Starting from where the previous section (Figure 8) left off, assume that we want
to add 700 additional points to the Latin Hypercube (the already existing 300 samples are
stored in X ):
Xnew = uq.enrichLHS(X, 700)
−2 0 2 4
0.5
1
1.5
2
2.5
3
3.5
X
Xnew
X
1
X
2
Figure 10: Enrichment of the LHS samples drawn from a 2-D Gaussian distribution with a
Gaussian copula using uq.enrichLHS . The initial sample set is shown in Figure 8.
Note: uq.enrichLHS only returns the new sample points! The full set can be retrieved
by Xfull = np.concatenate((X, Xnew)).
However, uq.enrichLHS should only be used when the initial sample set is generated by
Latin Hypercube sampling. If the initial sample set X was generated, e.g. using plain Monte
Carlo or if its origin is unknown (e.g. because it has been produced by another software)
then the function uq.LHSify must be used. This function enriches the existing sample set
in such a way that it forms a pseudo-Latin Hypercube sampling as a whole. This can be done
as follows:
Xnew = uq.LHSify(X, 700)
Xfull = np.concatenate((X, Xnew))
For enriching an experimental design that was generated by Sobol or Halton sampling the
functions uq.enrichSobol and uq.enrichHalton can be used with a similar syntax. For
UQ[PY]LAB-V1.0-102 - 26 -
The Input module
more information about the available sample enrichment functions see Section 3.4.
2.5 Performing an isoprobabilistic transform
Isoprobabilistic transforms are implemented in a general fashion in UQ[PY]LAB. Assume
that we want to map some existing sample X to the standard normal space (e.g. for solving
a reliability problem, see Section 1 of UQ[PY]LAB User Manual – Structural Reliability).
This can be carried out by defining the marginals (here, standard normal) and copula (here,
independent) of the target vector U.
InputU = {
'Marginals': uq.StdNormalMarginals(2),
'Copula' : {'Type': 'Independent'}
}
myInputU = uq.createInput(InputU)
Then the transformed samples are obtained by:
U = uq.GeneralIsopTransform(X, myInput2['Marginals'], myInput2['Copula'],
myInputU['Marginals'], myInputU['Copula'])
The original and transformed samples are shown in Figure 11.
−4 −2 0 2 4
−4
−2
0
2
4
−4 −2 0 2 4
−4
−2
0
2
4
X
1
U
1
X
2
U
2
Figure 11: Isoprobabilistic transform from the physical space (2D Gaussian, left) to the stan-
dard normal space (right).
2.6 Adding bounds
A marginal distribution truncated (oa.k.a bounded) in an interval [a, b] which is contained in
the distribution’s domain can be specified by
Input['Marginals'][0]['Bounds'] = [a, b]
For instance, the code below defines an uncorrelated 2D Gaussian distribution with X
1
(resp.
X
2
) having mean value µ
1
= 1 (resp. µ
2
= 2) and standard deviation σ
1
= 2 (resp. σ
2
= 2).
Additionally, X
1
is bounded in [−3, 2]:
UQ[PY]LAB-V1.0-102 - 27 -
UQ[PY]LAB user manual
Input = {'Marginals': uq.Marginals(1, 'Gaussian', [1, 2]) +
uq.Marginals(1, 'Gaussian', [2, 2])}
Input['Marginals'][0]['Bounds'] = [-3, 2]
myInput3 = uq.createInput(Input)
Now we can draw 300 samples using Latin Hypercube Sampling as follows:
X = uq.getSample(myInput3, 300, 'LHS')
The result is shown in Figure 12.
−3 −2 −1 0 1 2
−4
−2
0
2
4
6
8
X
1
X
2
Figure 12: Samples drawn from a 2-D Gaussian distribution with independent marginals and
bounds on X
1
∈ [−3, 2]. The sampling method is Latin Hypercube sampling.
2.7 Defining and using custom marginals
UQ[PY]LAB does not support custom distributions.
2.8 Constant variables
Constants are degenerate random variables that always take the same scalar value. A con-
stant variable can be specified as follows:
Input = {
'Marginals':
{
'Type': 'Constant',
'Parameters': [1]
}
}
UQ[PY]LAB-V1.0-102 - 28 -
The Input module
A random variable with zero variance is automatically interpreted as a constant. For example,
the INPUT object created by the code
Input = {
'Marginals': [
{
'Type': 'Gaussian',
'Parameters': [0, 1]
},
{
'Type': 'Gaussian',
'Parameters': [1, 0]
}
]
}
myInput = uq.createInput(Input)
has the second marginal set to the constant 1.
Similarly, a bounded random variable with identical upper and lower bound is reverted to a
constant. For example, the INPUT object created by the code
Input = {
'Marginals': [
{
'Type': 'Gaussian',
'Parameters': [0, 1]
},
{
'Type': 'Gaussian',
'Parameters': [0, 1],
'Bounds': [0, 0]
}
]
}
myInput = uq.createInput(Input)
has the second marginal set to the constant 0.
UQ[PY]LAB-V1.0-102 - 29 -
Chapter 3
Reference List
How to read the reference list
Python dictionaries play an important role throughout the UQ[PY]LAB syntax. They offer
a natural way to semantically group configuration options and output quantities. Due to
the complexity of the algorithms implemented, it is not uncommon to employ nested dictio-
naries to fine-tune the inputs and outputs. Throughout this reference guide, a table-based
description of the configuration dictionaries is adopted.
The simplest case is given when a value of a dictionary key is a simple value or a list:
Table X: Input
Name String A description of the field is put here
which corresponds to the following syntax:
Input = {
'Name' : 'My Input'
}
The columns, from left to right, correspond to the name, the data type and a brief description
of each key-value pair. At the beginning of each row a symbol is given to inform as to whether
the corresponding key is mandatory, optional, mutually exclusive, etc. The comprehensive
list of symbols is given in the following table:
Mandatory
□ Optional
⊕ Mandatory, mutually exclusive (only one of
the keys can be set)
⊞ Optional, mutually exclusive (one of them
can be set, if at least one of the group is set,
otherwise none is necessary)
31
UQ[PY]LAB user manual
When the value of one of the keys of a dictionary is a dictionary itself, a link to a table that
describes the structure of that nested dictionary is provided, as in the case of the Options
key in the following example:
Table X: Input
Name String Description
□ Options Table Y Description of the Options
dictionary
Table Y: Input['Options']
Key1 String Description of Key1
□ Key2 Double Description of Key2
In some cases, an option value gives the possibility to define further options related to that
value. The general syntax would be:
Input = {
'Option1' : 'VALUE1',
'VALUE1' : {
'Val1Opt1' : ... ,
'Val1Opt2' : ...
}
}
This is illustrated as follows:
Table X: Input
Option1 String Short description
'VALUE1' Description of 'VALUE1'
'VALUE2' Description of 'VALUE2'
⊞ VALUE1 Table Y Options for 'VALUE1'
⊞ VALUE2 Table Z Options for 'VALUE2'
Table Y: Input['VALUE1']
□ Val1Opt1 String Description
□ Val1Opt2 Float Description
Table Z: Input['VALUE2']
□ Val2Opt1 String Description
□ Val2Opt2 Float Description
UQ[PY]LAB-V1.0-102 - 32 -
The Input module
3.1 Creating an INPUT object: uq.createInput
Syntax
myInput = uq.createInput(Input)
Input
The dictionary variable Input contains the description of the marginal distributions of the
input parameters as well as their dependence through the copula function.
The content of the Input dictionary is listed in Table 4. 1
Table 4: Input
Marginals Table 5 The options regarding the marginals
of the random vector
□ Copula Table 6 The options regarding the copula (or
copulas) of the random vector
□ Name String The name of the object. If not set by
the user, a unique string is
automatically assigned to it, e.g.
'Input 1'.
The options that can be defined under Input['Marginals'] are given in Table 5. 2
Table 5: Input['Marginals']
Type String Type of marginal distribution
'Constant' A constant value
'Gaussian' Gaussian distribution (Section A.2)
'Lognormal' Lognormal distribution (Section A.3)
'Uniform' Uniform distribution (Section A.1)
'Exponential' Exponential distribution
(Section A.8)
'Beta' Beta distribution (Section A.9)
'Weibull' Weibull distribution (Section A.6)
'Gumbel' Gumbel maximum extreme value
distribution (Section A.4)
'GumbelMin' Gumbel minimum extreme value
distribution (Section A.5)
'Gamma' Gamma distribution (Section A.7)
'Triangular' Triangular distribution
(Section A.10)
UQ[PY]LAB-V1.0-102 - 33 -
UQ[PY]LAB user manual
'Logistic' Logistic distribution (Section A.11)
'Laplace' Laplace distribution (Section A.12)
'Rayleigh' Rayleigh distribution (Section A.13)
⊕ Moments variable length Float • Mean and standard
deviation([µ, σ]) of the marginal
distribution
• In case of constants just the
constant value is needed.
• For Beta distribution [µ, σ, a, b] can
be used for defining a custom
support, otherwise it is assumed that
[a, b] = [0, 1]
• For exponential distribution a
single element in 'Moments' is
needed (both mean and standard
deviation)
⊕ Parameters variable length Float • The parameters of the marginal
distribution as defined in Section 1.2
• In case of constants just the
constant value is needed.
• For Beta distribution either the
parameters [r, s] can be set (then the
support is assumed to be
[a, b] = [0, 1]) or all [r, s, a, b] can be
set for defining a custom support
[a, b].
□ Bounds 1 × 2 List with Float
entries
default:
[-float('inf'),
float('inf')]
[X
min
, X
max
] admissible value
Note: Only one of the two keys Input['Marginals']['Parameters'] or
Input['Marginals']['Moments'] can be set by the user for each element of
Input['Marginals']. If both keys are specified, an error is returned.
The options that can be defined under Input['Copula'] are listed in Table 6. 3
Table 6: Input['Copula']
Type String
default:
'Independent'
Copula type
'Independent' Independent copula
'Gaussian' Gaussian copula
'Pair' Pair copula
'CVine' C-vine copula
UQ[PY]LAB-V1.0-102 - 34 -
The Input module
'DVine' D-vine copula
⊞ Parameters • For 'Independent'
copula: ignored;
• For 'Gaussian'
copula: M × M List of
lists with Float entries ;
• For 'Pair' copula:
variable length Float ;
• For 'C'/'DVine': List
of M(M − 1)/2 (nested
lists of) Floats;
• The 'Independent' copula has
no parameters
• Linear correlation matrix of the
'Gaussian' copula
• Array of 'Pair' copula
parameter(s)
• Parameters of each pair copula in
the 'CVine'/'DVine'
⊞ RankCorr M × M List of lists with
Float entries
Spearman correlation matrix
('Gaussian' copula only)
Additional mandatory and optional options accepted when Copula['Type']='Pair' (resp.
Copula['Type']='CVine' or 'DVine') are listed in Table 7 (resp. Table 8).
Table 7: Input['Copula']: additional fields when Input['Copula']['Type']='Pair'
Family String Pair copula family
'Independent' or
'Independence'
Independence pair copula
'Gaussian' Gaussian pair copula
'Clayton' Clayton pair copula
'Gumbel' Gumbel pair copula
'Frank' Frank pair copula
't' t- pair copula
□ Rotation Float
default: 0
Either 0, 90, 180 or 270
Rotation of copula density; see
(1.13)
Table 8: Input['Copula']: additional keys when Input['Copula']['Type']='CVine'/'DVine'
Structure List with M integers Vine structure. Can be any
permutation of [1, 2, . . . , M]
Families List of Strings Families of pair copulas composing
the vine. Possible values are listed in
Table 7 (see 'Family')
□ Rotations List with Float entries
default: [0, 0, . . . , 0]
Entries must takes values
0, 90, 180 or 270
Rotation of each pair copula density;
see (1.13)
UQ[PY]LAB-V1.0-102 - 35 -
UQ[PY]LAB user manual
□ Truncation Integer
default: M
Vine truncation level
NOTE: Instead of manually specifying the structures Input['Marginals'] and Input['Copula'],
it is possible to obtain them through convenience functions described in Section 3.7. Beside,
the following functions may be useful to properly specify suitable copulas:
• uq.PairCopulaParameterRange(family): provided a pair copula family as a char
(e.g., 'Gumbel'), this function returns the range of admissible values for each parame-
ter of the copula;
• uq.CopulaSummary: for a copula of vine type, prints the pairs of variables coupled by
each pair copula in a specified vine, and the corresponding conditioning variables. For
more details, see Section 3.8.5.
Output
After uq.createInput completes its operation, a new INPUT object is created that contains
the following key-value pairs: 4
Table 9: myInput = uq.createInput(...)
Name String The name of the INPUT object
Sampling Dictionary Information regarding the default and lastly
used sampling method. See Sampling for
contents
Marginals List of M
Dictionaries
Information regarding the marginals, see
Table 5 for contents
Copula Dictionary Information regarding the copula, see Table 6
for contents
Internal Dictionary Internal key-value pairs that are only of
interest for scientific developers
The dictionary 'Sampling' contains the following fields : 5
Table 10: myInput['Sampling']
DefaultMethod String
Table 11
The default sampling method
Method String
Table 11
The current sampling method
UQ[PY]LAB-V1.0-102 - 36 -
The Input module
3.2 Getting samples from an INPUT object: uq.getSample
Syntax
X = uq.getSample([Input=None, ]N=None[, Method='MC'[, Name=None, Value=None]]
[, nargout=1])
X, U = uq.getSample(..., nargout=2)
Description
X = uq.getSample(N=N) returns N samples of a random vector defined in the currently
selected INPUT module using the default sampling method. If not set otherwise by the
user, the default sampling method is 'MC' (Monte Carlo). The user can call the function
uq.setDefaultSampling to change the default sampling method.
X = uq.getSample(myInput, N) returns N samples of the random vector defined in the
INPUT object myInput using the default sampling method.
X = uq.getSample(myInput, N, Method) returns N samples of a random vector defined
in the currently selected INPUT object using the sampling method defined in Method. This is
a string that can take one of the following values: 6
Table 11: Method option of uq.getSample
'MC' Monte Carlo
'LHS' Latin Hypercube
'Sobol' Sobol series
'Halton' Halton series
X = uq.getSample(myInput, N, Method, Name, Value) allows for specification of ad-
ditional Name - Value pairs of options. The supported options are listed in Table 12.
Table 12: Available options of uq.getSample
Name Value Description
method = 'LHS'
LHSiterations Integer
default: 5
Maximum number of
iterations to perform in
an attempt to improve the
design. For more
information refer to the
MATLAB function
lhsdesign.
Output
X = uq.getSample(...) returns an N-by-M NumPy ndarray of the samples of the selected
random vector in the physical space (where M is the dimension of the random vector).
UQ[PY]LAB-V1.0-102 - 37 -
UQ[PY]LAB user manual
X, U = uq.getSample(..., nargout=2) additionally returns an N-by-M NumPy ndar-
ray (U) of the samples in the uniform space.
3.3 Printing/Visualizing an INPUT object
UQ[PY]LAB offers two commands to conveniently print reports containing contextually rele-
vant information for a given object.
3.3.1 Printing information: uq.print
Syntax
uq.print(myInput);
Description
uq.print(myInput) prints a report about the INPUT object myInput (type, name, param-
eters and moments of each marginal and brief information about the copula).
3.3.2 Graphical visualization: uq.display
Syntax
uq.display(myInput[, idx][, marginals=False]);
Description
uq.display(myInput) produces a sample set from the INPUT object myInput. Then it
produces M × M plots in a single figure. Each plot, indexed by i, j = 1, . . . , M corre-
sponds to the scatter plot between the i-th and j-th element of the random vector. The
diagonal elements (i.e.when i = j) contain the histogram of the corresponding element
of the random vector. If M = 1, it produces plots of the PDF and CDF of the random
variable instead. If M = 2, it plots one scatter plot with marginal histograms on the
edges of the plot. The maximum value of M to display graphics is 10.
uq.display(myInput, idx) only takes into account the input indices that are contained
in the vector idx. In particular, if idx is a single integer, this command produces plots
of the PDF and CDF of that particular component.
uq.display(myInput, idx, marginals=True) only takes into account the input indices
that are contained in the vector idx and regardless of its size, it produces plots of the
PDF and CDF of each component. By default, idx contains indices of all random vector
elements.
UQ[PY]LAB-V1.0-102 - 38 -
The Input module
Examples
uq.display(myInput, [1 3]) will display the plots only for the first and third element of
the random vector that is described by myInput.
3.4 Enriching an existing sample set
3.4.1 Enriching a Latin Hypercube: uq.enrichLHS
Syntax
X1 = enrichLHS(X0=None, N=None[, Input=None][, nargout=1])
X1, U1 = enrichLHS(..., nargout=2)
Input
X1 = uq.enrichLHS(X0, N) enriches the experimental design X0 defined in the currently
selected INPUT object with N new samples so that the enriched sample set forms a (pseudo-)
Latin Hypercube sampling.
Note: The initial sample set is expected to form a Latin Hypercube, i.e. it should be
generated using Latin Hypercube sampling! If that is not the case, the function
uq.LHSify should be used instead (see Section 3.4.4).
X1 = uq.enrichLHS(X0, N, myInput) enriches the experimental design X0 defined in the
INPUT object myInput with N new samples so that the enriched sample set forms a Latin
Hypercube.
Output
X1 = uq.enrichLHS(...) returns an N-by-M NumPy ndarray of the new samples of the
selected random vector in the physical space.
Note: X1 only contains the new samples in the physical space. The enriched sample set
is obtained by X = np.concatenate((X0, X1)).
[X1, U1] = uq_enrichLHS(..., nargout=2) additionally returns an N -by-M NumPy
ndarray (U1) of the new samples in the uniform space.
3.4.2 Enriching a Sobol sequence: uq.enrichSobol
Syntax
X1 = uq.enrichSobol(X0=None, N=None[, Input=None][, nargout=1])
X1, U1 = uq.enrichSobol(..., nargout=2)
UQ[PY]LAB-V1.0-102 - 39 -
UQ[PY]LAB user manual
Input
X1 = uq.enrichSobol(X0, N) enriches the experimental design X0 defined in the cur-
rently selected INPUT object with N new samples that correspond to the next elements of
the Sobol sequence.
Note: The initial sample set is expected to be generated using Sobol sampling.
X1 = uq.enrichSobol(X0, N, myInput) enriches the experimental design X0 defined in
the INPUT object myInput with N new samples that correspond to the next elements of the
Sobol sequence.
Output
X1 = uq.enrichSobol(...) returns an N-by-M NumPy ndarray of the new samples of the
selected random vector in the physical space.
Note: X1 only contains the new samples in the physical space. The enriched sample set
is obtained by X = np.concatenate((X0, X1)).
X1, U1 = uq.enrichSobol(..., nargout=2) additionally returns an N -by-M NumPy
ndarray (U1) of the new samples in the uniform space.
3.4.3 Enriching a Halton sequence: uq.enrichHalton
Syntax
X1 = uq.enrichHalton(X0=None, N=None[, Input=None][, nargout=1])
X1, U1 = uq.enrichHalton(..., nargout=2)
Input
X1 = uq.enrichHalton(X0, N) enriches the experimental design X0 defined in the cur-
rently selected INPUT object with N new samples that correspond to the next elements of the
Halton sequence.
Note: The initial sample set is expected to be generated using Halton sampling.
X1 = uq.enrichHalton(X0, N, myInput) enriches the experimental design X0 defined in
the INPUT object myInput with N new samples that correspond to the next elements of the
Halton sequence.
Output
X1 = uq.enrichHalton(...) returns an N -by-M NumPy ndarray of the new samples of
the selected random vector in the physical space.
UQ[PY]LAB-V1.0-102 - 40 -
The Input module
Note: X1 only contains the new samples in the physical space. The enriched sample set
is obtained by X = np.concatenate((X0, X1)).
X1, U1 = uq_enrichHalton(..., nargout=2) additionally returns an N-by-M NumPy
ndarray (U1) of the new samples in the uniform space.
3.4.4 Pseudo-LHS enrichment: uq.LHSify
Syntax
X1 = uq.LHSify(X0=None, N=None[, Input=None][, nargout=1])
X1, U1 = uq.LHSify(..., nargout=2)
Input
X1 = uq.LHSify(X0, N) enriches the experimental design X0 defined in the currently se-
lected INPUT object with N new samples so that the enriched sample set forms a pseudo-Latin
Hypercube.
X1 = uq.LHSify(X0, N, myInput) enriches the experimental design X0 defined in the IN-
PUT object myInput with N new samples so that the enriched sample set forms a pseudo-Latin
Hypercube.
Output
X1 = uq.LHSify(...) returns an N -by-M NumPy ndarray of the new samples of the se-
lected random vector in the physical space.
Note: X1 only contains the new samples in the physical space. The enriched sample set
is obtained by X = np.concatenate((X0, X1)).
X1, U1 = uq.LHSify(..., nargout=2) additionally returns an N-by-M NumPy ndarray
(U1) of the new samples in the uniform space.
UQ[PY]LAB-V1.0-102 - 41 -
UQ[PY]LAB user manual
3.5 Sub-sampling an existing sample set: uq.subsample
Syntax
X1 = uq.subsample(X0=None, N1=None, Method=None[, Name=None, Value=None][,
nargout=1])
X1, idx = uq.subsample(..., nargout=2)
Input
X1 = uq.subsample(X0, N1, Method) reduces the sample size of the experimental de-
sign X0 (N0-by-M NumPy ndarray ) from N0 to N1 samples using the approach specified in
Method. The following values are possible for Method:
• 'random': The subset of N1 samples out of N0 is selected randomly
• 'k-means': The subset of N1 samples out of N0 is selected by first performing k-means
clustering with k = N1. Subsequently, the N1 samples closest to the cluster centroids
are selected.
X1 = uq.subsample(X0, N1, Method, Name, Value) allows for fine-tuning various pa-
rameters of the subsampling algorithm by specifying Name and Value pairs of options. The
available options are summarised in Table 13.
Table 13: Available options of uq.subsample(..., Name=Name, Value=Value)
Name Value Description
The following options are taken into account when method = 'kmeans'
'Distance_kmeans' String
default:
'sqeuclidean'
The distance measure
that is used in k-means
clustering. The available
options can be found in
the documentation of the
built-in MATLAB function
kmeans (option
'Distance').
'Distance_nn' String
default: 'euclidean'
The distance measure
that is used in nearest
neighbour search for
determining the samples
closest to the k-means
centroids. The available
options can be found in
the documentation of the
built-in MATLAB function
knnsearch (option
'Distance').
Output
X1 = uq.subsample(...) returns an N1-by-M NumPy ndarray that contains a subset of
the samples in X0.
UQ[PY]LAB-V1.0-102 - 42 -
The Input module
X1, idx = uq.subsample(..., nargout=2) additionally returns the indices of the se-
lected samples.
3.6 Transforming samples between spaces
3.6.1 uq.GeneralIsopTransform
Syntax
Y = uq.GeneralIsopTransform(X, XMarginals, XCopula, YMarginals, YCopula)
Input
The uq.GeneralIsopTransform function allows one to transform a sample set X (of size
N × M) drawn from a random vector defined by XMarginals and XCopula into samples of
a random vector Y defined by YMarginals and YCopula.
The guidelines for specifying the structures XMarginals, XCopula, YMarginals and YCopula
can be found in Section 3.1 (the syntax of dictionaries Input.Marginals from Table 5 and
Input.Copula from Table 6 are used respectively).
Output
Y = uq.GeneralIsopTransform(...) returns an N-by-M NumPy ndarray Y that contains
the transformed sample set.
3.6.2 uq.IsopTransform
Syntax
Y = uq.IsopTransform(X, XMarginals, YMarginals)
Input
The uq.IsopTransform function allows one to transform a sample set X (of size N × M)
drawn from a random vector with marginals XMarginals into samples of a random vector Y
with marginals YMarginals assuming that the components are independent. The guidelines
for specifying the structures XMarginals and YMarginals can be found in Table 5 (Sec-
tion 3.1).
Note: The 'Type' and 'Parameters' key-value pairs of X_marginals, Y_marginals
are necessary. In case the moments are given for some marginals the function
uq.MarginalFields can be executed first in order to obtain the corresponding
parameter values.
UQ[PY]LAB-V1.0-102 - 43 -
UQ[PY]LAB user manual
Output
Y = uq.IsopTransform(...) returns an N -by-M NumPy ndarray Y that contains the
transformed sample set.
3.6.3 uq.NatafTransform
Syntax
U = uq.NatafTransform(X, XMarginals, XCopula)
Input
The uq.NatafTransform function allows one to transform a sample set X (of size N × M)
into the standard normal space (space of zero mean, unit variance independent normal vari-
ables). The space is defined by the dictionaries XMarginals and XCopula. The guidelines
for specifying XMarginals (resp. XCopula) can be found in Table 5 (resp. Table 6) in Sec-
tion 3.1.
Output
U = uq.NatafTransform(...) returns an N-by-M NumPy ndarray U that contains N sam-
ples from M independent standard normal variables resulting from the Nataf transform of X.
3.6.4 uq.invNatafTransform
Syntax
X = uq.invNatafTransform(U, XMarginals, XCopula)
Input
The uq.invNatafTransform function allows one to transform a sample set U (of size N ×M)
drawn from a standard normal random vector into samples of a random vector X defined by
XMarginals and XCopula. The guidelines for specifying XMarginals (resp. XCopula) can
be found in Table 5 (resp. Table 6) in Section 3.1.
Output
X = uq.invNatafTransform(...) returns an N-by-M NumPy ndarray X that contains N
samples of size M, each row being a realization of the random vector defined by XMarginals
and XCopula.
UQ[PY]LAB-V1.0-102 - 44 -
The Input module
3.6.5 uq.RosenblattTransform
Syntax
U = uq.RosenblattTransform(X, XMarginals, XCopula)
Input
The uq.RosenblattTransform function allows one to transform a sample set X (of size
N × M) into the standard uniform space (space independent variables with uniform distri-
bution in [0, 1]). The original space is defined by the dictionaries XMarginals and XCopula.
The guidelines for specifying XMarginals (resp. XCopula) can be found in Table 5 (resp.
Table 6) in Section 3.1.
Output
U = uq.RosenblattTransform(...) returns an N-by-M NumPy ndarray U that contains
N samples from M independent standard normal variables resulting from the Nataf trans-
form of X.
3.6.6 uq.invRosenblattTransform
Syntax
X = uq.invRosenblattTransform(U, XMarginals, XCopula)
Input
The uq.invRosenblattTransform function allows one to transform a sample set U (of size
N × M) drawn from a standard uniform random vector into samples of a random vector
X defined by XMarginals and XCopula. The guidelines for specifying XMarginals (resp.
XCopula) can be found in Table 5 (resp. Table 6) in Section 3.1.
Output
X = uq.invRosenblattTransform(...) returns an N-by-M NumPy ndarray X that con-
tains N samples of size M, each row being a realization of the random vector defined by
XMarginals and XCopula.
UQ[PY]LAB-V1.0-102 - 45 -
UQ[PY]LAB user manual
3.7 Convenience functions to define marginals and copulas
3.7.1 uq.Marginals
The uq.Marginals function generates a structure describing M marginal distributions all of
the specified type and parameters (or moments). uq.Marginals allows one to quickly define
a multivariate INPUT with identical marginals, as in the following examples:
# Generate an Input object with 3 Gumbel marginals of parameters
# 1 and 2, and independence copula
iOpts = {"Marginals": uq.Marginals(3, "Gumbel", [1, 2])}
myInput = uq.createInput(iOpts);
# Generate a trivariate input with Gumbel marginals of moments
# 2 and 2, and independence copula
iOpts = {"Marginals": uq.Marginals(3, "Gumbel", Moments=[2, 2])}
myInput = uq.createInput(iOpts);
Syntax
myMarginals = uq.Marginals(Dimension, Type, {Parameters=None |
Moments=None})
Input
Dimension: integer describing the number of standard normal marginal.
Type : string, name of distribution family (common to each marginal)
Parameters / Moments: list, distribution parameters / moments. Only one can be specified,
not both.
Output
A list of dictionaries myMarginals with elements myMarginals[i], i= 0, . . . , M − 1, each
having the following keys
myMarginals[i]['Type'] = 'Gumbel'
myMarginals[i]['Parameters'] = [1, 2]
# alternatively: myMarginals[i]['Moments'] = [2, 2]
3.7.2 uq.StdNormalMarginals
The uq.StdNormalMarginals function generates a list of dictionaries describing M standard
normal marginal distributions. It is a special case of uq.Marginals with Type='Gaussian'
and Parameters=[0, 1]. uq.StdNormalMarginals allows one to quickly define a multi-
variate standard normal INPUT by the following code:
iOpts = {"Marginals": uq.StdNormalMarginals(M)}
myInput = uq.createInput(iOpts)
UQ[PY]LAB-V1.0-102 - 46 -
The Input module
Syntax
myMarginals = uq.StdNormalMarginals(M)
Input
M: integer describing the number of standard normal marginals.
Output
Structure myMarginals with elements myMarginals[i], i= 0, . . . , M − 1, each having the
following fields
myMarginals[i]['Type'] = 'Gaussian'
myMarginals[i]['Parameters'] = [0, 1]
3.7.3 uq.StdUniformMarginals
The uq.StdUniformMarginals function generates a list of dictionaries describing M stan-
dard uniform distributions, that is, uniform distributions in the interval [0, 1]. The syntax is
the same as for uq.StdNormalMarginals (see above). The generated marginals, however,
are of the type 'Uniform'.
3.7.4 uq.KernelMarginals
Syntax
myInput = uq.KernelMarginals(X[, bounds][, bandwidth])
Creates a list of dictionaries that describes the marginal distributions of the data points in X
as kernel density estimates.
Input
X : NumPy ndarray of input data.
Each column X_i=X[:,ii] represents data from input variable X
i
, i = 0, . . . , M − 1.
bounds: positive int, float or M × 2 List with Float entries , optional.
If specified, the marginals are bounded. Can be:
• a positive int or float: defined dX
j
= max(X
j
) − min(X
j
), each j-th marginal is
bounded in [min(X
j
) − bounds ∗ dX
j
, max(Xj) + bounds ∗ dX
j
]
• an M × 2 List with Float entries : marginal jj is bounded in bounds[jj,:]
bandwidth: int, float, or list, optional.
The Gaussian kernel bandwidth. Can be:
• a positive int or float: the kernel bandwidth for each dimension
• a list of M positive floats: the bandwidths of each dimension
UQ[PY]LAB-V1.0-102 - 47 -
UQ[PY]LAB user manual
Output
Marginals: list of M dictionaries
A list that contains a dictionary for each of M marginals obtained by kernel smoothing.
3.7.5 uq.GaussianCopula
Usage
Copula = uq.GaussianCopula(C[, corrType])
Convenience function to create a data structure describing a Gaussian copula with spec-
ified correlation matrix.
Input
C: M × M List with Float entries
correlation matrix of the M-variate Gaussian copula
corrType : string, optional
the type of correlation provided in C. Either 'Linear' (equivalently 'Pearson'),
'Spearman', or 'Kendall'.
Default: 'Linear'
Output
mcodeCopula: dictionary
Dictionary that contains the specified Gaussian copula, with the keys 'Type',
'Dimension', 'Parameters', 'RankCorr', 'RhoS', 'TauK', 'CholR'
3.7.6 uq.PairCopula
Usage
Copula = uq.PairCopula(family, theta[, rotation])
Convenience function to create a data structure describing the specified pair copula. The
dictionary is used in copula-related operations in UQ[PY]LAB, for instance as part of an
INPUTobject.
Input
family: string
the pair copula family
theta : List with Float entries
the copula parameters
rotation: Float , optional
UQ[PY]LAB-V1.0-102 - 48 -
The Input module
the rotation of the copula density. Can be: 0, 90, 180, 270.
Default: 0 (no rotation).
Note: rotations 90 and 270 are obtained by flipping the copula density around the lines
u
1
= 0.5 and u
2
= 0.5, respectively.
Output
Copula: dictionary
Dictionary that contains the specified pair copula, with the keys 'Type', 'Family',
'Dimension', 'Parameters', 'Rotation'
3.7.7 uq.VineCopula
Usage
Copula = uq.VineCopula(type, structure, families, thetas[, rotations][,
truncation])
Convenience function to create a data structure describing the specified vine copula.
Input
type: string
either 'CVine' or 'DVine'
structure : list of M integers
list with all and only integers 1 to M, in any order.
families: list of M(M − 1)/2 strings
the families of pair copulas comprising the vine
thetas: list of M(M − 1)/2 lists
each j-th element in the list is the (list of) parameter(s) of the j-th pair copula
rotations: 1 × M(M − 1)/2 List with Float entries , optional
the rotation of each pair copula density (0, 90, 180, or 270)
Default: 0 (no rotation)
truncation: Integer, optional
the vine truncation. Pair copulas in the vine with higher conditioning order that the vine
truncation are set to be the independence pair copula.
Default: M − 1 (no truncation)
Note: Vine copulas truncated at tree t < M − 1 need the specification of only
P =
P
t
j=1
(M − j) pair copulas. Consequently, the input parameters families,
thetas and rotations need to contain only P elements for truncated vines.
Additional ones are ignored.
Output
Copula: dictionary
Dictionary that describes the specified vine copula
UQ[PY]LAB-V1.0-102 - 49 -
UQ[PY]LAB user manual
3.8 Additional functions
3.8.1 uq.sampleU
Syntax
U = uq.sampleU(N, M[, options])
Input
U = uq.sampleU(N, M) returns N samples of a random vector having M independent, uni-
form marginals over [0, 1] (i.e. uniform sample over the unit hypercube of dimension M).
U = uq.sampleU(N, M, options) returns N samples of a random vector having M in-
dependent uniform marginals over [0, 1], with sampling options defined in the dictionary
options (Table 14).
Table 14: options of uq_sampleU
□ Method String
default: 'MC'
Sampling method
'MC' Monte Carlo
'LHS' Latin Hypercube
'Sobol' Sobol series
'Halton' Halton series
□ LHSiterations Integer
default: 5
This option is taken into account
when .Method = 'LHS'. It refers
to the maximum number of
iterations to perform in an attempt to
improve the space-filling properties
of the sample set. For more
information refer to the MATLAB
function lhsdesign.
Output
U = uq.sampleU(...) returns an N-by-M NumPy ndarray of samples of the unit hyper-
cube.
3.8.2 uq.MarginalFields
Syntax
updated_marginals = uq.MarginalFields(marginals)
UQ[PY]LAB-V1.0-102 - 50 -
The Input module
Input
The uq.MarginalFields function computes moments of marginals from parameters and
vice versa. More precisely uq.MarginalFields computes for each marginal contained in
marginals:
• the moments marginals['Moments'] if the parameters marginals['Parameters']
are available
• the parameters marginals['Parameters'] if the moments marginals['Moments']
are available.
The input variable marginals is a dictionary as described in Table 5 (Section 3.1).
Output
updated_marginals = uq.MarginalFields(...) returns an updated dictionary having
both the Parameters and Moments key-value pairs filled.
3.8.3 uq.estimateMoments
Syntax
moments = uq.estimateMoments(marginal[,
*
args][, nargout=1])
moments, exit_flag = uq.estimateMoments(..., nargout=2)
moments, exit_flag, convergence = uq.estimateMoments(..., nargout=3)
Input
The uq.estimateMoments function computes the moments (mean and standard deviation)
of a distribution numerically. By default, the moments are estimated by numerical integra-
tion. In case poor convergence of the integrator is observed, the moments are re-estimated
using a sampling-based scheme. The sample-based method measures convergence by means
of the COV of the moments estimators (Saporta, 2006).
moments = u.estimateMoments(marginal) calculates the moments of the distribution that
is described by the marginal dictionary as described in Table 5 (Section 3.1).
moments = uq.estimateMoments(marginal, Name, Value) allows for fine-tuning vari-
ous parameters of the moments estimation algorithm by specifying Name, and Value pairs of
options. The available options are summarized in Table 15.
Table 15: Available options of uq.estimateMoments
Name Value (default) Description
UQ[PY]LAB-V1.0-102 - 51 -
UQ[PY]LAB user manual
'method' String ('Integral') Method for estimating the
moments. Currently
supported values are
'MC' for sample-based
and 'Integral' for
integral-based estimation.
The following options are taken into account when 'method'= 'MC'
'N0' Double (10
6
) Initial sample size
'Nstep' Double (10
5
) Number of additional
samples per iteration
'targetCOV' Double (0.01) The target Coefficient of
Variation of the moments
estimates
'maxiter' Double (30) Maximum number of
iterations
'sampling' String ('Sobol') Method for generating
samples. See Table 14 for
available options.
'verbose' Logical (false) If set to true
convergence information
are printed after each
iteration otherwise
nothing is printed
Output
moments = uq.estimateMoments(...) returns a 2 × 1 list that contains the mean and
standard deviation of the distribution.
moments, exit_flag = uq.estimateMoments(..., nargout=2) additionally returns a
Boolean variable exit_flag that is true if the algorithm converged to the specified target
coefficient of variation or false otherwise. This extra output will only be available in case
the sampling-based method (method = 'MC') was used.
moments, exit_flag, convergence = uq.estimateMoments(..., nargout=3) addition-
ally returns a N
i
×3 list, where N
i
is the number of iterations. Each row contains the iteration
number and the corresponding estimate of the mean and standard deviation at that iteration.
This extra output will only be available in case the sampling-based method (method = 'MC')
was used.
3.8.4 uq.setDefaultSampling
Syntax
uq.setDefaultSampling([Input=None, ]Method=None)
success = uq.setDefaultSampling(...)
UQ[PY]LAB-V1.0-102 - 52 -
The Input module
Description
uq.setDefaultSampling(Method=method) sets the default sampling method of the cur-
rently selected INPUT object to method. The accepted values of method can be found in
Table 11.
uq.setDefaultSampling(myInput, method) sets the default sampling method of the IN-
PUT object myInput to method.
3.8.5 uq.CopulaSummary
Syntax
This function has two different uses, with syntax either
msg = uq.CopulaSummary(Copula),
OR
msg = uq.CopulaSummary(VineType, Structure).
It prints a summary of the specified copula structure (first syntax) or of the pair copulas in a
vine with the specified type and structure.
Input
Copula: dictionary
A structure describing a copula
OR
VineType: string
vine type (either 'CVine' or 'DVine')
Structure: List with Int entries
vine structure (order of the variables in the vine construction)
Output
msg = uq.CopulaSummary(...) returns a string containing the copula summary.
print(uq.CopulaSummary(...)) prints a message on screen.
UQ[PY]LAB-V1.0-102 - 53 -
Chapter 4
Appendices
A List of univariate distributions supported in UQ[PY]LAB
In this section, a brief overview of each distribution and its properties (e.g., PDF, cumulative
distribution function, support, moments,parameters) is given for reference.
A.1 Uniform distribution
Uniform distributions are commonly used to represent variables with unknown moments and
known support. The uniform distribution is the maximum entropy distribution on any closed
support.
Notation : X ∼ U (a, b)
Parameters : a, b ∈ R ; a < b
Support : D
X
= [a, b]
PDF : f
X
(x) =
[a,b]
(x)
b − a
=
1
b−a
if x ∈ [a, b]
0 if x /∈ [a, b]
CDF : F
X
(x) =
x − a
b − a
[a,b]
(x) =
0 if x ≤ a
x−a
b−a
if x ∈ [a, b]
1 if x ≥ b
Moments : µ
X
=
a + b
2
σ
X
=
b − a
2
√
3
A particularly important uniform distribution in the field of numerical statistics is X = U(0, 1).
In fact, every class of random number generators produces samples from this PDF (or its
multidimensional version), which are then manipulated to produce samples distributed ac-
cording any other distribution as needed. For details, see Section 1.5.
A.2 Gaussian (Normal)
Gaussian distributions are another basic family of PDF that are pervasive throughout any
fields of applied science. They are commonly employed to represent measurement error,
54
The Input module
-2 -1 0 1 2
0
0.2
0.4
0.6
0.8
1
1.2
-2 -1 0 1 2
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 13: PDF and CDF of uniform distributions for various parameter values.
noise terms, etc.
Notation : X ∼ N (µ, σ)
Parameters : µ ∈ R , σ > 0
Support : D
X
= R
PDF : f
X
(x) =
1
σ
√
2π
e
−
(x−µ)
2
2σ
2
CDF : F
X
(x) =
1
2
1 + erf
x − µ
σ
√
2
= Φ
x − µ
σ
Moments : µ
X
= µ
σ
X
= σ
where µ is the mean, σ
2
the variance and erf(·) is the error function, defined by:
erf(x) =
2
√
π
Z
x
0
e
−t
2
dt (1)
An important distribution belonging to the normal family is the so-called standard normal
distribution N(0, 1), characterized by µ = 0, σ = 1. The notation Φ(x) is used to identify the
standard normal CDF:
Φ(x) =
x
Z
−∞
e
−t
2
/2
√
2π
dt (2)
All normal distributions can be represented as linear transforms of standard normal distribu-
UQ[PY]LAB-V1.0-102 - 55 -
UQ[PY]LAB user manual
-1 0 1 2 3 4
0
0.2
0.4
0.6
0.8
1
1.2
1.4
1.6
1.8
2
-1 0 1 2 3 4
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 14: PDF and CDF of Gaussian distributions for various parameter values.
tions as follows:
N(µ, σ) = µ + σN(0, 1) (3)
A.3 Lognormal distribution
A lognormal variable is a random variable X ∼ LN (λ, ζ) such that its logarithm is a Gaussian
variable:
X ∼ LN (λ, ζ) ⇔ ln(X) ∼ N (λ, ζ) (4)
Notation : X ∼ LN (λ, ζ)
Parameters : λ ∈ R , ζ > 0
Support : D
X
= (0, +∞)
PDF : f
X
(x) =
1
√
2πζx
exp
−
(ln x − λ)
2
2ζ
2
!
CDF : F
X
(x) =
1
2
+
1
2
erf
ln x − λ
√
2ζ
= Φ
ln x − λ
ζ
Moments : µ
X
= e
λ+ζ
2
/2
σ
X
= e
λ+ζ
2
/2
p
e
ζ
2
− 1
where λ and ζ are the mean and standard deviation of the natural logarithm of the variable
and the error function is defined in Eq. (1).
Lognormal distributions are commonly used in engineering to describe parameters which are
positive in nature, such as material or physical properties. An important property of lognor-
UQ[PY]LAB-V1.0-102 - 56 -
The Input module
0 1 2 3 4
0
0.5
1
1.5
2
2.5
3
3.5
4
4.5
5
0 1 2 3 4
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 15: PDF and CDF of lognormal distributions for various parameter values.
mally distributed variables is that their products and ratios are also lognormally distributed.
A.4 Gumbel distribution
The Gumbel distribution is also referred to as Extreme Value distribution of type I (EV I). Note
that in the literature the name ’Gumbel distribution’ is used to refer to either the maximum
or the minimum extreme value distribution. In UQ[PY]LAB “Gumbel” refers to the maximum
Gumbel distribution .
Notation : X ∼ G (µ, β)
Support : D
X
= R
Parameters : µ ∈ R , β > 0
PDF : f
X
(x) =
1
β
e
−
x−µ
β
−e
−
x−µ
β
CDF : F
X
(x) = e
−e
−
x−µ
β
Moments : µ
X
= µ + βγ
e
where γ
e
= 0.577216 . . . is the Euler constant
σ
X
=
πβ
√
6
Note that parameter µ coincides with the mode of the distribution.
The Gumbel distribution is used for modelling random variables obtained as the maximum of
identically distributed variables. It is used for instance in hydrology to model flood intensity.
UQ[PY]LAB-V1.0-102 - 57 -
UQ[PY]LAB user manual
-1 0 1 2 3 4 5
0
0.5
1
1.5
2
-1 0 1 2 3 4 5
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 16: PDF and CDF of Gumbel maximum extreme value distributions for various pa-
rameter values.
A.5 Gumbel-min distribution
The Gumbel-min is also referred to as the Smallest Extreme Value (SEV) distribution or the
Smallest Extreme Value (Type I) distribution.
Notation : X ∼ G (µ, β)
Parameters : µ ∈ R , β > 0
Support : D
X
= R
PDF : f
X
(x) =
1
β
e
x−µ
β
+e
−
x−µ
β
CDF : F
X
(x) = 1 − e
−e
−
x−µ
β
Moments : µ
X
= µ − βγ
e
where γ
e
= 0.577216 . . . is the Euler constant
σ
X
=
πβ
√
6
Note that parameter µ coincides with the mode of the distribution.
The Gumbel-min distribution’s PDF is skewed to the left, unlike the Gumbel-max which is
skewed to the right (see Figures 16 and 17).
UQ[PY]LAB-V1.0-102 - 58 -
The Input module
-1 0 1 2 3 4 5
0
0.5
1
1.5
2
-1 0 1 2 3 4 5
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 17: PDF and CDF of Gumbel-min extreme value distributions for various parameter
values.
A.6 Weibull distribution
The Weibull distribution is the last type of extreme-value distributions. It is commonly em-
ployed to parametrize time-to-failure-type variables.
Notation : X ∼ W (α, β)
Parameters : α > 0 , β > 0
Support : D
X
= [0, +∞)
PDF : : f
X
(x) =
(
β
α
x
α
β−1
e
−(x/α)
β
if x ≥ 0
0 , x < 0
CDF : : F
X
(x) =
(
1 − e
−(x/α)
β
if x ≥ 0
0 if x < 0
Moments : µ
X
= α Γ (1 + 1/β)
σ
X
= α
q
Γ (1 + 2/β) − Γ (1 + 1/β)
2
Other uses of the Weibull distribution include the parametrization of strength or strength-
related lifetime parameters, material strength and lifetime parameters for brittle materials
(for which the weakest-link-theory is applicable).
UQ[PY]LAB-V1.0-102 - 59 -
UQ[PY]LAB user manual
0 1 2 3 4
0
0.5
1
1.5
2
2.5
0 1 2 3 4
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 18: PDF and CDF of Weibull distributions for various parameter values.
A.7 Gamma distribution
The Gamma distribution may be used to model variables which are positive in nature, such as
those connected to Poisson processes. Assuming events occur randomly in time in a Poisson
process at a constant rate λ, the time to first occurrence follows an exponential distribution
Γ(λ, 1). The time to k-th occurrence follows a Gamma distribution Γ(λ, k).
Notation : X ∼ Γ (λ, k)
Parameters : λ > 0 , k > 0
Support : D
X
= [0, +∞)
PDF : f
X
(x) =
λ
k
Γ(k)
x
k−1
e
−λx
CDF : F
X
(x) =
γ (k, λx)
Γ(k)
Moments : µ
X
=
k
λ
σ
X
=
√
k
λ
where Γ(x) is the Gamma function defined by
Γ(x) =
Z
∞
0
t
x−1
e
−t
dt (5)
UQ[PY]LAB-V1.0-102 - 60 -
The Input module
and γ(x, y) is the incomplete Gamma function defined by
γ(k, x) =
Z
x
0
t
k−1
e
−t
dt (6)
0 2 4 6 8
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
0 2 4 6 8
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 19: PDF and CDF of Gamma distributions for various parameter values.
A special case of Gamma distribution is X ∼ Γ(λ, 1), which corresponds to the exponential
distribution (see Section A.8).
A.8 Exponential distribution
A special case of the Gamma distribution, the exponential distribution is commonly used to
represent the time to first-occurrence of Poissonian-type processes, e.g. radioactive decays.
Notation : X ∼ E (λ)
Parameters : λ > 0
Support : D
X
= [0, +∞)
P DF : f
X
(x) = λe
−λx
CDF : F
X
(x) = 1 − e
−λx
Moments : µ
X
= 1/λ
σ
X
= 1/λ
where λ > 0 is the scale parameter.
The Exponential distribution is also used to model the waiting times in queuing problems
(e.g., for load balancing applications in large computational facilities).
UQ[PY]LAB-V1.0-102 - 61 -
UQ[PY]LAB user manual
0 2 4 6 8
0
0.05
0.1
0.15
0.2
0.25
0.3
0.35
0.4
0.45
0 2 4 6 8
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 20: PDF and CDF of exponential distributions for various parameter values.
A.9 Beta distribution
The Beta distribution commonly used to model bounded variables.
Notation : X ∼ B(r, s, a, b)
Parameters : r > 0 , s > 0
Support : D
X
= [a, b]
PDF : : f
X
(x) =
(
(x−a)
r−1
(b−x)
s−1
(b−a)
r+s−1
B (r, s)
if x ∈ [a, b]
0 if x /∈ [a, b]
CDF : : F
X
(x) =
0 if x ≤ a
1
(b−a)
r+s−1
B(r, s)
R
x
a
(t − a)
r−1
(b − t)
s−1
dt if x ∈ [a, b]
1 if x ≥ b
Moments : µ
X
= a + (b − a)r/(r + s)
σ
X
=
b − a
r + s
r
r s
r + s + 1
where B (r, s) is the Beta function:
B(r, s) =
Z
1
0
t
r−1
(1 − t)
s−1
dt =
Γ(r)Γ(s)
Γ(r + s)
(7)
The support of the distribution is given by the parameters [a, b]. The shape of the distribution
is related to parameters [r, s] and their ratio:
• When r = s the PDF is symmetrical;
• If r, s > 1 the PDF is unimodal;
UQ[PY]LAB-V1.0-102 - 62 -
The Input module
0 0.2 0.4 0.6 0.8 1
0
0.5
1
1.5
2
2.5
3
3.5
4
0 0.2 0.4 0.6 0.8 1
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 21: PDF and CDF of Beta distributions for various parameter values (D
X
= [0, 1]).
• if r, s < 1 the PDF is maximum at the boundaries.
A.10 Triangular distribution
Notation : X ∼ Tr(a, b, c)
Parameters : a ∈ R , a < b , a < c < b
Support : D
X
= [a, b]
PDF : f
X
(x) =
0 if x ≤ a
2(x−a)
(b−a)(c−a)
if x ∈ (a, c)
2
b−a
if x = c
2(b−x)
(b−a)(c−a)
if x ∈ (c, b)
0 if x ≥ b
CDF : F
X
(x) =
0 if x ≤ a
(x−a)
2
(b−a)(c−a)
if x ∈ (a, c]
1 −
(b−x)
2
(b−a)(b−c)
if x ∈ (c, b)
1 if x ≥ b
Moments : µ
X
=
a + b + c
3
σ
X
=
√
a
2
+ b
2
+ c
2
− ab − ac − bc
3
√
2
The triangular distribution is typically used as a subjective description of a population for
which there is only limited sample data. It is based on knowledge of the minimum a and
maximum b and an “inspired guess” c of the modal value.
UQ[PY]LAB-V1.0-102 - 63 -
UQ[PY]LAB user manual
0 2 4 6
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
0 2 4 6
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 22: PDF and CDF of triangular distributions for various parameter values.
A.11 Logistic distribution
The logistic distribution resembles the normal distribution in shape but has heavier tails
(higher kurtosis).
Notation : X ∼ P (µ, s)
Parameters : µ ∈ R , s > 0
Support : D
X
= R
PDF : f
X
(x) =
e
−
x−µ
s
s(1 + e
−
x−µ
s
)
2
CDF : F
X
(x) =
1
1 + e
−
x−µ
s
Moments : µ
X
= µ
σ
X
=
sπ
√
3
UQ[PY]LAB-V1.0-102 - 64 -
The Input module
-10 0 10 20
0
0.05
0.1
0.15
0.2
0.25
0.3
-10 0 10 20
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 23: PDF and CDF of logistic distributions for various parameter values.
A.12 Laplace distribution
Laplace distribution is also known as double exponential distribution, because it can be
thought of as two exponential distributions (with an additional location parameter) spliced
together back-to-back.
Notation : X ∼ L(µ, b)
Parameters : µ ∈ R , b > 0
Support : D
X
= R
PDF : f
X
(x) =
1
2b
exp
−
|x − µ|
b
CDF : F
X
(x) =
1
2
exp
x−µ
b
if x < µ
1 −
1
2
exp
−
x−µ
b
if x ≥ µ
Moments : µ
X
= µ
σ
X
= b
√
2
UQ[PY]LAB-V1.0-102 - 65 -
UQ[PY]LAB user manual
-20 -10 0 10 20
0
0.05
0.1
0.15
0.2
0.25
0.3
0.35
0.4
0.45
0.5
-20 -10 0 10 20
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 24: PDF and CDF of Laplace distributions for various parameter values.
A.13 Rayleigh distribution
A spacial case of the Weibull distribution, the Rayleigh distribution is commonly used to
describe the envelope of the channel response of a radio signal (a.k.a. Rayleigh fading).
Besides, it is also widely used in engineering to model the wind speed.
Notation : X ∼ R(σ)
Parameters : σ > 0
Support : D
X
= [0, +∞)
PDF : f
X
(x) =
x
σ
2
e
−x
2
/
(
2σ
2
)
CDF : F
X
(x) = 1 − e
−x
2
/
(
2σ
2
)
Moments : µ
X
=
r
π
2
σ
σ
X
=
r
4 − π
2
σ
where σ > 0 is the scale parameter.
UQ[PY]LAB-V1.0-102 - 66 -
The Input module
Figure 25: PDF and CDF of Rayleigh distributions for various parameter values.
UQ[PY]LAB-V1.0-102 - 67 -
References
Aas, K., C. Czado, A. Frigessi, and H. Bakkend (2009). Pair-copula constructions of multiple
dependence. Insurance: Mathematics and Economics 44(2), 182–198. 6, 12
Bedford, T. and R. M. Cooke (2002). Vines – a new graphical model for dependent random
variables. The Annals of Statistics 30(4), 1031–1068. 6, 8
Joe, H. (1996). Families of m-variate distributions with given margins and m(m − 1)/2
bivariate dependence parameters. In L. R
¨
uschendorf, B. Schweizer, and M. D. Taylor (Eds.),
Distributions with fixed marginals and related topics, Volume 28 of Lecture Notes–Monograph
Series, pp. 120–141. Institute of Mathematical Statistics. 8
Joe, H. (2015). Dependence modeling with copulas. CRC Press. 3
Lebrun, R. and A. Dutfoy (2009). A generalization of the Nataf transformation to distribu-
tions with elliptical copula. Probabilistic Engineering Mechanics 24(2), 172–178. 10
McKay, M. D., R. J. Beckman, and W. J. Conover (1979). A comparison of three methods
for selecting values of input variables in the analysis of output from a computer code.
Technometrics 2, 239–245. 24
Nelsen, R. B. (2006). An Introduction to Copulas. Secaucus, NJ, USA: Springer-Verlag New
York, Inc. 1, 3, 5
Rosenblatt, M. (1952). Remarks on a multivariate transformation. The Annals of Mathemati-
cal Statistics 23, 470–472. 12
Saporta, G. (2006). Probabilit
´
es, analyse des donn
´
ees et statistique. Editions Technip. 51
Torre, E., S. Marelli, P. Embrechts, and B. Sudret (2019). A general framework for data-
driven uncertainty quantification under complex input dependencies using vine copulas.
Probabilistic Engineering Mechanics 55, 1–16. 7
68
