UQLab User Manual – The Input Module

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 60

UQLAB USER MANUAL
THE INPUT MODULE
C. Lataniotis, 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 UQLAB
S. Marelli, and B. Sudret, UQLab: A framework for uncertainty quantification in Matlab, Proc. 2nd Int. Conf. on
Vulnerability, Risk Analysis and Management (ICVRAM2014), Liverpool, United Kingdom, 2014, 2554-2563.
How to cite this manual
C. Lataniotis, S. Marelli and B. Sudret, UQLab user manual – The Input module, Report UQLab-V1.1-102, Chair of
Risk, Safety & Uncertainty Quantification, ETH Zurich, 2018.
BIBT
E
X entry
@TechReport{UQdoc 11 102,
author = {Lataniotis, C. and Marelli, S. and Sudret, B.},
title = {{UQLab user manual -- INPUT module}},
institution = {Chair of Risk, Safety & Uncertainty Quantification, ETH Zurich},
year = {2018},
note = {Report # UQLab-V1.1-102},
}
Document Data Sheet
Document Ref. UQLAB-V1.1-102
Title: UQLAB User Manual – The Input module
Authors: C. Lataniotis, S. Marelli, B. Sudret
Chair of Risk. Safety and Uncertainty Quantification, ETH Zurich,
Switzerland
Date: 01/07/2018
Doc. Version Date Comments
V1.1 01/07/2018 UQLAB V1.1 release
• New section in the reference list about uq subsample
V1.0 01/05/2017 UQLAB V1.0 release
• New distributions: triangular, logistic, Laplace
• Updated custom distributions section
• Updated description of several functions
V0.9 01/07/2015 Initial release
Abstract
The UQLAB 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 UQLAB. After introducing
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 UQLAB INPUT module is given at the end of the
manual.
Keywords: Probabilistic Input Model, Marginals, Copula, Sampling
Contents
1 Theory 1
1.1 Introduction ..................................... 1
1.2 Representation of common univariate distributions ............... 1
1.2.1 Uniform distribution ............................ 3
1.2.2 Gaussian (Normal) ............................. 4
1.2.3 Lognormal distribution ........................... 5
1.2.4 Gumbel distribution ............................ 5
1.2.5 Gumbel-min distribution .......................... 6
1.2.6 Weibull distribution ............................ 8
1.2.7 Gamma distribution ............................ 9
1.2.8 Exponential distribution .......................... 10
1.2.9 Beta distribution .............................. 11
1.2.10 Triangular distribution ........................... 12
1.2.11 Logistic distribution ............................ 13
1.2.12 Laplace distribution ............................ 14
1.3 Truncated distributions ............................... 15
1.4 Representation of random vectors and joint PDFs ................ 15
1.4.1 Marginals and copula ........................... 15
1.4.2 Copulas currently available in UQLAB .................. 16
1.5 Sampling random vectors ............................. 18
1.5.1 Isoprobabilistic transform of independent marginals .......... 18
1.5.2 Generalized Nataf transform ........................ 18
1.5.3 Sampling multivariate distributions with the inverse generalized Nataf
transform .................................. 19
2 Usage 21
2.1 Drawing samples from a distribution ....................... 21
2.1.1 Introductory example ........................... 21
2.1.2 Special cases of distributions ....................... 22
2.1.3 Using a copula ............................... 23
2.1.4 Selecting an INPUT object and specifying the sampling method ..... 24
2.2 Enrichment of an experimental design with new samples ............ 26
2.3 Performing an isoprobabilistic transform ..................... 27
2.4 Adding bounds ................................... 27
2.5 Switching between input objects ......................... 28
2.6 Defining and using custom marginals ....................... 29
2.6.1 Advanced options .............................. 30
2.7 Constant variables ................................. 30
3 Reference List 33
3.1 Creating an INPUT object: uq_createInput ................... 35
3.2 Getting samples from an INPUT object: uq_getSample ............. 38
3.3 Printing/Visualizing an INPUT object ....................... 39
3.3.1 Printing information: uq_print ...................... 39
3.3.2 Graphical visualization: uq_display ................... 39
3.4 Enriching an existing sample set .......................... 41
3.4.1 Enriching a Latin Hypercube: uq_enrichLHS .............. 41
3.4.2 Enriching a Sobol sequence: uq_enrichSobol ............. 41
3.4.3 Enriching a Halton sequence: uq_enrichHalton ............ 42
3.4.4 Pseudo-LHS enrichment: uq_LHSify ................... 43
3.5 Sub-sampling an existing sample set: uq_subsample .............. 44
3.6 Transforming samples between spaces ...................... 45
3.6.1 uq_GeneralIsopTransform ....................... 45
3.6.2 uq_IsopTransform ............................ 45
3.6.3 uq_NatafTransform ............................ 46
3.6.4 uq_invNatafTransform ......................... 46
3.7 Additional functions ................................ 48
3.7.1 uq_sampleU ................................ 48
3.7.2 uq_MarginalFields ............................ 49
3.7.3 uq_estimateMoments ........................... 49
3.7.4 uq_setDefaultSampling ......................... 50
References ......................................... 52
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∼fX(x). Several input parameters, including their dependence
structure, can be grouped together in a random vector with joint PDF X∼fX(x). The INPUT
module in UQLAB offers a suite of tools to handle the representation, transformation and
sampling of a wide variety of PDFs and joint PDFs.
1.2 Representation of common univariate distributions
A random variable can be represented by its univariate PDF X∼fX(x). UQLAB supports a
number of distributions employed in many fields of applied sciences, namely:
• Uniform
• Normal or Gaussian
• Lognormal
• Gumbel (maxima)
• Gumbel (minima)
• Beta
• Gamma
• Exponential
• Weibull
• Triangular
1
UQLAB User Manual
• Logistic
• Laplace
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.
UQLAB-V1.1-102 - 2 -
The Input module
1.2.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 :DX= [a, b]
PDF :fX(x) = [a,b](x)
b−a=1
b−aif x∈[a, b]
0if x /∈[a, b]
CDF :FX(x) = x−a
b−a[a,b](x) =
0if x≤a
x−a
b−aif x∈[a, b]
1if x≥b
Moments :µX=a+b
2
σX=b−a
2√3
-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 1: PDF and CDF of uniform distributions for various parameter values.
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.3.
UQLAB-V1.1-102 - 3 -
UQLAB User Manual
1.2.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,
noise terms etc..
Notation :X∼ N (µ, σ)
Parameters :µ∈R, σ > 0
Support :DX=R
PDF :fX(x) = 1
σ√2πe−(x−µ)2
2σ2
CDF :FX(x) = 1
21 + erf x−µ
σ√2
= Φ x−µ
σ
Moments :µX=µ
σX=σ
where µis the mean, σ2the variance and erf(·)is the error function, defined by:
erf(x) = 2
√πZx
0
e−t2dt (1.1)
-101234
0
0.2
0.4
0.6
0.8
1
1.2
1.4
1.6
1.8
2
-101234
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 2: PDF and CDF of Gaussian distributions for various parameter values.
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:
UQLAB-V1.1-102 - 4 -
The Input module
Φ(x) =
x
Z
−∞
e−t2/2
√2πdt (1.2)
All normal distributions can be represented as linear transforms of standard normal distribu-
tions as follows:
N(µ, σ) = µ+σN(0,1) (1.3)
1.2.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 (λ, ζ)(1.4)
Notation :X∼ LN (λ, ζ)
Parameters :λ∈R, ζ > 0
Support :DX= (0,+∞)
PDF :fX(x) = 1
√2πζx exp −(ln x−λ)2
2ζ2!
CDF :FX(x) = 1
2+1
2erf ln x−λ
√2ζ
= Φ ln x−λ
ζ
Moments :µX=eλ+ζ2/2
σX=eλ+ζ2/2peζ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.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-
mally distributed variables is that their products and ratios are also lognormally distributed.
1.2.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 UQLAB “Gumbel” refers to the maximum
UQLAB-V1.1-102 - 5 -
UQLAB User Manual
01234
0
0.5
1
1.5
2
2.5
3
3.5
4
4.5
5
01234
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 3: PDF and CDF of lognormal distributions for various parameter values.
Gumbel distribution .
Notation :X∼ G (µ, β)
Support :DX=R
Parameters :µ∈R, β > 0
PDF :fX(x) = 1
βe−x−µ
β−e
−
x−µ
β
CDF :FX(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.
1.2.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.
UQLAB-V1.1-102 - 6 -
The Input module
-1012345
0
0.5
1
1.5
2
-1012345
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 4: PDF and CDF of Gumbel maximum extreme value distributions for various param-
eter values.
Notation :X∼ G (µ, β)
Parameters :µ∈R, β > 0
Support :DX=R
PDF :fX(x) = 1
βex−µ
β+e
−
x−µ
β
CDF :FX(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 4and 5).
UQLAB-V1.1-102 - 7 -
UQLAB User Manual
-1012345
0
0.5
1
1.5
2
-1012345
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 5: PDF and CDF of Gumbel-min extreme value distributions for various parameter
values.
1.2.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 :DX= [0,+∞)
PDF : :fX(x) = (β
αx
αβ−1e−(x/α)βif x≥0
0, x < 0
CDF : :FX(x) = (1−e−(x/α)βif x≥0
0if 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).
UQLAB-V1.1-102 - 8 -
The Input module
01234
0
0.5
1
1.5
2
2.5
01234
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 6: PDF and CDF of Weibull distributions for various parameter values.
1.2.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 :DX= [0,+∞)
PDF :fX(x) = λk
Γ(k)xk−1e−λx
CDF :FX(x) = γ(k, λx)
Γ(k)
Moments :µX=k
λ
σX=√k
λ
where Γ(x)is the Gamma function defined by
Γ(x) = Z∞
0
tx−1e−tdt (1.5)
UQLAB-V1.1-102 - 9 -
UQLAB User Manual
and γ(x, y)is the incomplete Gamma function defined by
γ(k, x) = Zx
0
tk−1e−tdt (1.6)
02468
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
02468
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 7: 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 1.2.8).
1.2.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 :DX= [0,+∞)
P DF :fX(x) = λe−λx
CDF :FX(x) = 1 −e−λx
Moments :µX= 1/λ
σX= 1/λ
where λ > 0is 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).
UQLAB-V1.1-102 - 10 -
The Input module
02468
0
0.05
0.1
0.15
0.2
0.25
0.3
0.35
0.4
0.45
02468
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 8: PDF and CDF of exponential distributions for various parameter values.
1.2.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 :DX= [a, b]
PDF : :fX(x) = ((x−a)r−1(b−x)s−1
(b−a)r+s−1B(r, s)if x∈[a, b]
0if x /∈[a, b]
CDF : :FX(x) =
0if x≤a
1
(b−a)r+s−1B(r, s)Rx
a(t−a)r−1(b−t)s−1dt if x∈[a, b]
1if x≥b
Moments :µX=a+ (b−a)r/(r+s)
σX=b−a
r+srr s
r+s+ 1
where B(r, s)is the Beta function:
B(r, s) = Z1
0
tr−1(1 −t)s−1dt =Γ(r)Γ(s)
Γ(r+s)(1.7)
The range of the variable is given by the parameters [a, b]. The shape of the distribution is
related to parameters [r, s]and their ratio:
• When r=sthe PDF is symmetrical;
• If r, s > 1the PDF is unimodal;
• if r, s < 1the PDF is maximum at the boundaries.
UQLAB-V1.1-102 - 11 -
UQLAB User Manual
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 9: PDF and CDF of Beta distributions for various parameter values (DX= [0,1]).
1.2.10 Triangular distribution
Notation :X∼Tr(a, b, c)
Parameters :a∈R, a < b , a < c < b
Support :DX= [a, b]
PDF :fX(x) =
0if x≤a
2(x−a)
(b−a)(c−a)if x∈(a, c)
2
b−aif x=c
2(b−x)
(b−a)(c−a)if x∈(c, b)
0if x≥b
CDF :FX(x) =
0if 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)
1if x≥b
Moments :µX=a+b+c
3
σX=√a2+b2+c2−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 and
maximum and an “inspired guess” of the modal value.
UQLAB-V1.1-102 - 12 -
The Input module
0246
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
0246
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
Figure 10: PDF and CDF of triangular distributions for various parameter values.
1.2.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 :DX=R
PDF :fX(x) = e−x−µ
s
s(1 + e−x−µ
s)2
CDF :FX(x) = 1
1 + e−x−µ
s
Moments :µX=µ
σX=sπ
√3
UQLAB-V1.1-102 - 13 -
UQLAB User Manual
-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 11: PDF and CDF of logistic distributions for various parameter values.
1.2.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 :DX=R
PDF :fX(x) = 1
2bexp −|x−µ|
b
CDF :FX(x) =
1
2exp x−µ
bif x<µ
1−1
2exp −x−µ
bif x≥µ
Moments :µX=µ
σX=b√2
UQLAB-V1.1-102 - 14 -
The Input module
-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 12: PDF and CDF of Laplace distributions for various parameter values.
1.3 Truncated distributions
A truncated distribution results from restricting the domain of some probability distribution.
Assume that a random variable Xfollows some distribution with CDF FX(X). Of interest in
this section is the derivation of the CDF, F0
Xand inverse CDF, F0−1
Xof the random variable X
after limiting the support to X∈[a, b].
The derivation of these quantities is given below:
F0
X(X) =
0, X ≤a
FX(X)−FX(a)
FX(b)−FX(a), a < X < b
1, X ≥b
(1.8)
F0−1
X(u) =
a , u = 0
F−1
X(FX(a) + u(FX(b)−FX(a))) ,0<u<1
b , u = 1
(1.9)
A practical example for specifying truncated distributions is given in Section 2.4.
1.4 Representation of random vectors and joint PDFs
1.4.1 Marginals and copula
A natural extension of the univariate random variables case to the multivariate random vec-
tors case is the introduction of multivariate joint-PDFs. Within the UQLAB framework, joint
CDFs are represented by means of the copula formalism (Nelsen,2006). Copulas are a pow-
erful tool to provide a simple representation of multivariate distributions by separating the
univariate distributions of each component of a random vector (marginals) from their depen-
UQLAB-V1.1-102 - 15 -
UQLAB User Manual
dence structure (copula). At the basis of the copula formalism lies Sklar’s theorem:
FX(x) = C(FX1(x1), FX2(x2), ..., FXM(xM)) (1.10)
where X={X1, . . . , XM}is the M-dimensional input random vector with joint CDF FX(x),
FXi(xi)is the i-th input marginal and C(·)is a function that describes the dependence struc-
ture between the Minput variables. From (1.10) the joint PDF is obtained by differentiation:
fX(x)=
M
Y
i=1
fXi(xi)·c(FX1(x1), . . . , FXM(xM)) (1.11)
where c(·)is the copula density function obtained as
c(u1, . . . , uM) = ∂MC(u1, . . . , uM)
∂u1, . . . , ∂uM
.(1.12)
Sklar’s theorem states that any joint PDF FXcan be expressed in terms of its marginal distri-
butions FXi(xi)and some additional function, the copula, that represents their dependence.
This framework is ideal for uncertainty quantification in scientific applications. Indeed it is
often the case that marginal distributions as well as some form of correlation measure be-
tween variables are known or inferred from available data, but no clear information about
the correlation structure 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)
for more details and relevant literature.
1.4.2 Copulas currently available in UQLAB
The UQLAB framework currently supports two different copulas to represent dependence
between variables, namely the independent, and Gaussian copulas. They are characterized
as follows:
1. Independent copula:
C(u1, . . . , uM) =
M
Y
i=1
ui(1.13)
By substituting Eq. (1.13) in (1.10), it is clear that it corresponds to the case in which
the components of the input random vector are independent. Indeed:
FX(x) = C(FX1(x1), . . . , FXM(xM)) =
M
Y
i=1
FXi(xi),(1.14)
consequently the independent copula density is simply c(u1, . . . , uM) = 1. A graphical
representation of the uniform copula density is given for reference in Figure 13.
UQLAB-V1.1-102 - 16 -
The Input module
Figure 13: Independent copula: scatterplot (a), contour plot (b) and 3D-view (c) of the
copula density c(u1, u2).
2. Gaussian copula:
C(u1, . . . , uM;R)=ΦMΦ−1(u1), . . . , Φ−1(uM); R(1.15)
where Ris the linear correlation matrix of the multivariate Gaussian distribution asso-
ciated with the Gaussian copula,ΦM(u;R)is the cumulative distribution function of an
M-variate Gaussian distribution with mean 0and correlation matrix Rand Φ−1(ui)is
the inverse cumulative distribution function of the standard normal distribution.
The Gaussian copula is one of the most commonly used copulas to parametrize the
dependence 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 Rij is, there will
be no tail dependence (see Nelsen (2006) for details).
A graphical representation of the Gaussian copula is given for reference in Figure 14.
Figure 14: Gaussian copula: scatter plot (a), contour plot (b) and 3D-view (c) of the copula
density c(u1, u2).
UQLAB-V1.1-102 - 17 -
UQLAB User Manual
1.5 Sampling random vectors
In most uncertainty quantification applications, sampling the input vectors is as important
as properly represent them. However, most of the existing random sampling strategies (e.g.
Monte Carlo sampling, latin hypercube sampling (LHS), pseudorandom sequences, etc.) pro-
duce samples in the unit hypercube distributed according to X∼ U([0,1]M). Amongst the
many strategies available to generate samples distributed according to a specific PDF FX,
UQLAB approaches the problem in terms of isoprobabilistic transforms. An isoprobabilistic
transform is a map of the form (Lebrun and Dutfoy,2009):
X=T(U)s.t. X ∼FX,U∼FU(1.16)
or, in other words, it is a change of variables that transforms a sample of random vector
U∼FUinto a sample of random vector X∼FX. Of particular interest for sampling
purposes is the transform between the unit hypercube U∼ U([0,1]M), and any other random
vector with joint distribution FX.
In the following, isoprobabilistic transforms will be derived for the purposes of sampling
independent random vectors as well as random vectors with Gaussian copula.
1.5.1 Isoprobabilistic transform of independent marginals
Consider a sampling of size Nof the unit hypercube Z=u(1), . . . , u(N)∼ U([0,1]M).
Due to the independence between the components of the random vector X∼FX, a simple
isoprobabilistic transform can be used to transform Zinto X=x(1), . . . , x(N)∼FX:
x(i)
j=F−1
Xj(u(i)
j)(1.17)
where F−1
Xjdenotes the inverse CDF of the j-th marginal of the random vector X.
1.5.2 Generalized Nataf transform
In the case of dependent variables, several extra steps are needed to properly transform
a sample from the unit hypercube to the desired joint PDF. A powerful tool is given by the
generalized Nataf transform (Lebrun and Dutfoy,2009). Given Sklar’s theorem in Eq. (1.10),
it follows that that a sample Zfrom a random vector X∼FX(x)can be obtained from
a sample of the underlying copula C=c(1), . . . , c(N)with a component-by-component
isoprobabilistic transform similar to that in Eq. (1.17):
x(i)
j=F−1
Xj(c(i)
j)(1.18)
where F−1
Xjdenotes the inverse CDF of the j-th marginal of the random vector X. Moreover,
the underlying copula distribution is a multivariate Gaussian. An important property of the
Gaussian copula is that it is elliptical, which means that an isoprobabilistic transform exist
that maps samples from an elliptical copula with correlation matrix Rto the same copula
UQLAB-V1.1-102 - 18 -
The Input module
with identity correlation matrix I(uncorrelated components). Such transform has the form:
U=Γ−1V(1.19)
where Uis a sample from the elliptical copula with identity correlation matrix, Vis a sample
from the same copula but with correlation matrix Rand Γ−1is the inverse Cholesky factor
of R=ΓΓT. Note that this property is well known for multivariate Gaussian distributions.
With these ingredients it is possible to define the so-called generalized Nataf transform:
U=TGN (X),(1.20)
where U∼ N(0,I)(standard normal space) for the Gaussian copula, as follows:
1. X7→ W= [FX1(X1), . . . , FXM(XM)]T
2. W7→ V=E−1(W1), ..., E−1(WM)T
3. V7→ U=Γ−1V
where Wis a sample of the copula with correlation matrix R,Vis a sample of the multivari-
ate elliptical distribution with correlation matrix Rthat generates the copula , E−1= Φ−1for
the Gaussian copula and Γ−1is the inverse Cholesky factor of R. The Nataf transform first
transforms any sample of the input random vector into a sample of the underlying copula. It
then transforms the copula into the desired multivariate standard elliptical distribution with
correlation matrix Rand finally decorrelates it via Eq. (1.19).
1.5.3 Sampling multivariate distributions with the inverse generalized Nataf
transform
An important property of the transform in Section 1.5.2 is that it is invertible. It then be-
comes clear how it can be used for efficient sampling of multivariate distributions in conjunc-
tion with random number generators that generate samples in the uniform unit hypercube
Z=U([0,1]M). Given a sample of the uniform unit hypercube Z=z(1), . . . , z(N), one
can obtain a sample from the desired random vector X∼FX(x)with arbitrary marginals
FX1(x1), . . . , FXM(xM)and elliptic copula C(U)as follows:
1. Z7→ U∼FE(u)[Generate samples from the standard elliptical distribution]
2. U7→ V=Γ−1U[Correlate the samples]
3. V7→ W= [E(V1), ..., E(VM)]T[Transform into a sample of the underlying copula]
4. W7→ X=hF−1
X1(X1), . . . , F −1
XM(XM)iT[Transform into FX(x)]
The implementation of the first step of this algorithm depends on the actual copula chosen.
In case of Gaussian copula it can be easily achieved directly with Eq. (1.17).
UQLAB-V1.1-102 - 19 -
Chapter 2
Usage
2.1 Drawing samples from a distribution
2.1.1 Introductory example
Let us consider a Gaussian vector X= [X1, X2]Twith independent components. The mean
value and standard deviation of X1(resp. X2) are µ1= 1,σ1= 1 (resp. µ2= 2,σ2= 0.5).
In UQLAB an INPUT object is created by defining the list of marginal distributions and the
copula that connects these marginals to form the joint distribution.
uqlab;
Input.Marginals(1).Type = 'Gaussian';
Input.Marginals(1).Parameters = [1 1];
Input.Marginals(2).Type = 'Gaussian';
Input.Marginals(2).Moments = [2 0.5];
myInput1 = uq_createInput(Input);
Note that each marginal distribution can be defined either from its parameters or moments
(but not from both). By default the input variables are assumed independent in UQLAB. In
this case there is no need to define a copula. This can be however done explicitly by typing
(before using uq_createInput):
Input.Copula.Type = 'Independent';
When the INPUT object myInput1 is created, all the parameters and moments for all vari-
ables are computed and all possible inconsistencies are checked. In case the parameters and
moments are specified for a given marginal. an error is returned and the script aborts.
Once the INPUT object myInput1 has been created, a report can be produced as follows:
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
21
UQLAB User Manual
Copula:
Type: Independent
-------------------------------------------
For visual inspecting an INPUT object the function uq_display can be used as follows:
uq_display(myInput1)
The result is shown in Figure 15.
X1
-2 -1 0 1 2 3 4
X2
0.5
1
1.5
2
2.5
3
3.5
Figure 15: The output of the function uq_display on the INPUT object myInput1.
It is possible to draw samples from the INPUT object myInput1 as follows:
X=uq_getSample(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.5.
The MATLAB standard random number generator is used by default. The result is shown in
Figure 16.
2.1.2 Special cases of 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,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 Section 1.2. Some special cases are the following:
• For exponential distribution only one parameter (λ) exists. When such distribution is
defined by its parameters only one element is needed (λ). Additionally when it is
UQLAB-V1.1-102 - 22 -
The Input module
X1
-1 0 1 2 3 4
X2
1
1.5
2
2.5
3
3.5
Figure 16: Samples drawn from a 2-D Gaussian distribution with independent marginals.
The sampling method is plain Monte Carlo.
defined by its moments only one element is needed again which corresponds to the
mean and standard deviation (that are equal).
• For 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:
Input.Marginals.Type = 'Beta';
Input.Marginals.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:
Input.Marginals.Type = 'Beta';
Input.Marginals.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 1.2.9.
2.1.3 Using a copula
Let us now create another INPUT object where dependency between the marginals is intro-
duced by imposing a Gaussian copula. As discussed in Section 1.4.2, the Gaussian copula
takes as parameter the linear correlation matrix Rof the copula, which is assumed to be
UQLAB-V1.1-102 - 23 -
UQLAB User Manual
equal to R=1 0.8
0.8 1 (linear correlation coefficient ρ12 = 0.8).
Input.Name = 'Input 2: Dependent marginals' ;
Input.Copula.Type = 'Gaussian';
Input.Copula.Parameters = [ 1 0.8 ; 0.8 1 ];
myInput2 = uq_createInput(Input);
X=uq_getSample(300);
X1
-1 0 1 2 3 4
X2
0.5
1
1.5
2
2.5
3
3.5
Figure 17: Samples drawn from a 2-D Gaussian distribution with a Gaussian copula (corre-
lation coefficient ρ12 = 0.8).The sampling method is plain Monte Carlo.
The resulting samples are plotted in Figure 17. 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.
2.1.4 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 a different INPUT object than the last for
sampling:
• Using the function uq_selectInput. For example, drawing 300 samples from the IN-
PUT object myInput1 can be achieved as follows:
uq_selectInput(myInput1);
X=uq_getSample(300);
UQLAB-V1.1-102 - 24 -
The Input module
• Specifying the INPUT object directly in uq_getSample. For example, drawing 300 sam-
ples 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(300, 'LHS');
The result is shown in Figure 18. For a list of all the available sampling methods refer to
Table 6 in Section 3.2.
X1
-2 0 2 4
X2
0.5
1
1.5
2
2.5
3
3.5
4
Figure 18: Samples drawn from a 2-D Gaussian distribution with a Gaussian copula. The
Latin Hypercube sampling method is used.
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('LHS');
Note that this does not affect other INPUT objects, i.e.the sampling method for myInput1 is
still plain Monte Carlo.
UQLAB-V1.1-102 - 25 -
UQLAB User Manual
2.2 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 18) 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);
X1
-2 0 2 4
X2
0.5
1
1.5
2
2.5
3
3.5
4X
Xnew
Figure 19: 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 18.
Note: uq_enrichLHS only returns the new sample points! The full set can be retrieved
by Xfull = [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 Xwas 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 = [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
more information about the available sample enrichment functions see Section 3.4.
UQLAB-V1.1-102 - 26 -
The Input module
2.3 Performing an isoprobabilistic transform
Isoprobabilistic transforms are implemented in a general fashion in UQLAB. Assume that
we want to map some existing sample Xto the standard normal space (e.g. for solving a
reliability problem, see UQLAB User Manual : Structural Reliability, Section 1).
This can be carried out by defining the marginals (here standard normal) and copula (here
independent) of the target vector U.
UMarginals(1).Type = 'Gaussian';
UMarginals(1).Parameters = [0,1];
UMarginals(2).Type = 'Gaussian';
UMarginals(2).Parameters = [0,1];
UCopula.Type = 'Independent';
Then the transformed samples are obtained by:
U=uq_GeneralIsopTransform(X,...
myInput2.Marginals, myInput2.Copula, UMarginals, UCopula);
The original and transformed samples are shown in Figure 20.
X1
-4 -2 0 2 4
X2
-4
-2
0
2
4
U1
-4 -2 0 2 4
U2
-4
-2
0
2
4
Figure 20: An isoprobabilistic transform from some physical space (2D Gaussian) to the
standard normal space.
2.4 Adding bounds
Suppose we want to draw samples from an uncorrelated 2D Gaussian distribution with X1
(resp. X2) having mean value µ1= 1 (resp. µ2= 3) and standard deviation σ1= 2 (resp.
σ2= 2). Additionally X1is bounded in [−3,2]:
Input.Marginals(1).Type = 'Gaussian';
Input.Marginals(1).Parameters = [1 2];
Input.Marginals(1).Bounds = [-3 2];
Input.Marginals(2).Type = 'Gaussian';
Input.Marginals(2).Moments = [2 2];
UQLAB-V1.1-102 - 27 -
UQLAB User Manual
myInput3 = uq_createInput(Input);
Now we can draw 300 samples using Latin Hypercube Sampling as follows:
X=uq_getSample(300, 'LHS');
The result is shown in Figure 21.
X1
-4 -2 0 2 4
X2
-2
0
2
4
6
8
Figure 21: Samples drawn from a 2-D Gaussian distribution with independent marginals and
bounds on X1∈[−3,2]. The sampling method is Latin Hypercube sampling.
2.5 Switching between input objects
Suppose we want to draw two sample sets:
• 200 Monte Carlo samples from the input vector myInput2 with correlated components.
• 300 LHS samples from the input vector myInput3 with bounded marginal X1.
This is carried out as follows:
uq_selectInput(myInput2);
X2=uq_getSample(200,'MC');
uq_selectInput(myInput3);
X3=uq_getSample(300,'LHS');
The two samples are plotted in Figure 22.
UQLAB-V1.1-102 - 28 -
The Input module
X1
-3 -2 -1 0 1 2 3 4
X2
-5
0
5
10 myInput2
myInput3
Figure 22: Samples drawn from two different cases of a 2-D Gaussian distribution. The INPUT
object myInput2 has dependent marginals and the INPUT object myInput3 has independent
marginals and bounds on X1∈[−3,2]. The sampling method is Latin Hypercube sampling.
2.6 Defining and using custom marginals
The built-in probability distributions can be found in Table 2 of the Reference List (Section 3)
and a brief description of each in Section 1.2. New distributions can be defined by provid-
ing three files to a folder that is available to the MATLAB path, each corresponding to the
PDF, CDF and inverse CDF respectively. In order to define a new distribution some naming
convention has to be followed. The functions that correspond e.g.to a distribution called
myDistribution should be named as follows:
• PDF function: uq_myDistribution_pdf
• CDF function: uq_myDistribution_cdf
• inverse CDF function: uq_myDistribution_invcdf
The definition of each function should look like:
function f = uq_myDistribution_pdf(X, parameters)
function F = uq_myDistribution_cdf(X, parameters)
function X = uq_myDistribution_invcdf(F, parameters)
In these functions, Xand Fare vectors of length Nand parameters is a vector of doubles
of arbitrary length.
UQLAB-V1.1-102 - 29 -
UQLAB User Manual
In order to use the custom distribution myDistribution we then create an INPUT object as
follows:
Input.Marginals(1).Type = 'myDistribution';
Input.Marginals(1).Parameters = ...
%e t c
myInput = uq_createInput(Input);
2.6.1 Advanced options
In order to fully specify a custom probability distribution a function that calculates the mean
and standard deviation of the distribution given its parameters is required. The following
naming convention should be used in order to specify such function:
function moments = uq_myDistribution_PtoM(parameters)
where parameters is an arbitrary variable that contains the distribution’s parameters and
moments is a vector equal to [µ, σ], that is the mean and standard deviation of the distribu-
tion for the given parameter values.
Note: In case the function uq_myDistribution_PtoM is not provided the moments of
the distribution are estimated numerically. For more information refer to the
uq_estimateMoments function reference (Section 3.7.3). The default values of
the options of uq_estimateMoments are used for estimating the moments.
In addition, the function that calculates the parameters of a user-defined probability distribu-
tion given its moments can be specified in case the ability of specifying the distribution based
on its mean and standard deviation is required. In that case a function of the following form
needs to be created:
function parameters = uq_myDistribution_MtoP(moments)
where moments is a vector equal to [µ, σ], that is the mean and standard deviation of the
distribution and parameters is a vector that contains the distribution’s parameters that
correspond to the given moments.
2.7 Constant variables
Constants form a special variable type that simply corresponds to some constant scalar value.
A constant variable can be specified as follows:
Input.Marginals.Type = 'Constant';
Input.Marginals.Parameters = 1;
In addition, a random variable may be reverted to constant in case its variance is zero. For
example, after creating the following INPUT object:
Input.Marginals(1).Type = 'Gaussian';
UQLAB-V1.1-102 - 30 -
The Input module
Input.Marginals(1).Parameters = [0 1];
Input.Marginals(2).Type = 'Gaussian';
Input.Marginals(2).Parameters = [1 0];
myInput = uq_createInput(Input);
The following warning message is returned:
Warning: Marginal(2).Type changed from Gaussian to constant because
the variance was zero.
Similarly a random variable is reverted to constant in case bounds have been specified with
upper and lower bound being identical. For example, after creating the following INPUT
object:
Input.Marginals(1).Type = 'Gaussian';
Input.Marginals(1).Parameters = [0 1];
Input.Marginals(2).Type = 'Gaussian';
Input.Marginals(2).Parameters = [0 1];
Input.Marginals(2).Bounds = [0 0];
myInput = uq_createInput(Input);
The following warning message is returned:
Warning: Marginal(2).Type changed from Gaussian to constant because
the upper and lower bounds were identical.
UQLAB-V1.1-102 - 31 -
Chapter 3
Reference List
How to read the reference list
Structures play an important role throughout the UQLAB syntax. They offer a natural way
to group configuration options and output quantities semantically. Due to the complexity of
the algorithms implemented, it is not uncommon to employ nested structures to fine-tune
inputs/outputs. Throughout this reference guide, we adopt a table-based description of the
configuration structures.
The simplest case is given when a field of the structure is a simple value/array of values:
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 correspond to name, data type and a brief description of each field. At the
beginning of each row a symbol is given to inform as to whether the corresponding field 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 fields 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)
When one of the fields of a structure is a nested structure, we provide a link to a table that
describes the available options, as in the case of the Options field in the following example:
33
UQLAB User Manual
Table X: Input
.Name String Description
.Options Table Y Description of the Options
structure
Table Y: Input.Options
.Field1 String Description of Field1
.Field2 Double Description of Field2
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' ;
Input.VALUE1.Val1Opt1 = ...;
Input.VALUE1.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 Double Description
Table Z: Input.VALUE2
.Val2Opt1 String Description
.Val2Opt2 Double Description
Note: In the sequel, double/doubles mean a real number represented in double pre-
cision (resp. a set of such real numbers).
UQLAB-V1.1-102 - 34 -
The Input module
3.1 Creating an INPUT object: uq_createInput
Syntax
myInput = uq_createInput(Input)
Input
The struct 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 structure is listed in Table 1.1
Table 1: Input
.Marginals Table 2 The options regarding the marginals
of the random vector
.Copula Table 3 The options regarding the copula 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 2.2
Table 2: Input.Marginals
.Type String Type of marginal distribution
'Constant' A constant value
'Gaussian' Gaussian distribution (Section 1.2.2)
'Lognormal' Lognormal distribution
(Section 1.2.3)
'Uniform' Uniform distribution (Section 1.2.1)
'Exponential' Exponential distribution
(Section 1.2.8)
'Beta' Beta distribution (Section 1.2.9)
'Weibull' Weibull distribution (Section 1.2.6)
'Gumbel' Gumbel maximum extreme value
distribution (Section 1.2.4)
'GumbelMin' Gumbel minimum extreme value
distribution (Section 1.2.5)
'Gamma' Gamma distribution (Section 1.2.7)
'Triangular' Triangular distribution
(Section 1.2.10)
UQLAB-V1.1-102 - 35 -
UQLAB User Manual
'Logistic' Logistic distribution (Section 1.2.11)
'Laplace' Laplace distribution (Section 1.2.12)
other String A user-defined marginal type
(Section 2.6)
⊕.Moments variable length Double •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 Double •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×2Double
default: [-inf, inf]
[Xmin, Xmax ]admissible value
Note: Only one of the two fields Input.Marginals.Parameters or
Input.Marginals.Moments can be set by the user for each element of
Input.Marginals. If both fields are specified, an error is returned.
The options that can be defined under Input.Copula are listed in Table 3.3
Table 3: Input.Copula
.Type String
default:
'Independent'
Copula type.
'Independent' Independent copula.
'Gaussian Gaussian copula
UQLAB-V1.1-102 - 36 -
The Input module
.Parameters M×MDouble •For a Gaussian copula it
corresponds to the linear correlation
matrix
•It is not taken into account when
Input.Copula.Type has value
'Independent'
.RankCorr M×MDouble Spearman correlation matrix
(Gaussian copula only)
Output
After uq_createInput completes its operation a new INPUT object is created that contains
the following fields: 4
Table 4: myInput = uq_createInput(...)
.Name String The name of the INPUT object
.Sampling Struct Information regarding the default and lastly
used sampling method. See Sampling for
contents
.Marginals M×1Struct Information regarding the marginals, see
Table 2 for contents
.Copula Struct Information regarding the copula, see Table 3
for contents
.Internal Struct Internal fields that are only of interest for
scientific developers. For more information
refer to the Scientific Developer’s Guide of the
Input module
The structure Sampling contains the following fields : 5
Table 5: myInput.Sampling
.DefaultMethod String
Table 6
The default sampling method
.Method String
Table 6
The current sampling method
UQLAB-V1.1-102 - 37 -
UQLAB User Manual
3.2 Getting samples from an INPUT object: uq_getSample
Syntax
X=uq_getSample(N)
X=uq_getSample(myInput,N)
X=uq_getSample(N,method)
X=uq_getSample(myInput,N,method)
X=uq_getSample(N,method,Name,Value)
X=uq_getSample(myInput,N,method,Name,Value)
X=uq_getSample(...)
[X, U] = uq_getSample(...)
Description
X=uq_getSample(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 IN-
PUT 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 6: 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 addi-
tional Name -Value pairs of options. The supported options are listed in Table 7.
Table 7: Available options of uq_getSample
Name Value Description
method = 'LHS'
'iterations' 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.
UQLAB-V1.1-102 - 38 -
The Input module
Output
X=uq_getSample(...) returns an N-by-Mmatrix of the samples of the selected random
vector in the physical space (where M is the dimension of the random vector).
[X, U] = uq_getSample(...) additionally returns an N-by-Mmatrix (U) of the samples
in the uniform space.
3.3 Printing/Visualizing an INPUT object
UQLAB offers two commands to conveniently print reports containing contextually relevant
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);
uq_display(myInput, idx);
uq_display(myInput, idx, 'marginals');
Description
uq_display(myInput) produces a sample set from the INPUT object myInput. Then it
produces M×Mplots 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.
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.
UQLAB-V1.1-102 - 39 -
UQLAB User Manual
uq_display(myInput, idx, 'marginals')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.
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.
UQLAB-V1.1-102 - 40 -
The Input module
3.4 Enriching an existing sample set
3.4.1 Enriching a Latin Hypercube: uq_enrichLHS
Syntax
X1=uq_enrichLHS(X0, N)
X1=uq_enrichLHS(X0, N, myInput)
[X1, U1] = uq_enrichLHS(...)
Input
X1=uq_enrichLHS(X0, N) enriches the experimental design X0 defined in the currently
selected INPUT object with Nnew 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 Nnew samples so that the enriched sample set forms a Latin
Hypercube.
Output
X1=uq_enrichLHS(...) returns an N-by-Mmatrix 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 = [X0;X1].
[X1, U1] = uq_enrichLHS(...) additionally returns an N-by-Mmatrix (U1) of the new
samples in the uniform space.
3.4.2 Enriching a Sobol sequence: uq_enrichSobol
Syntax
X1=uq_enrichSobol(X0, N)
X1=uq_enrichSobol(X0, N, myInput)
[X1, U1] = uq_enrichSobol(...)
UQLAB-V1.1-102 - 41 -
UQLAB User Manual
Input
X1=uq_enrichSobol(X0, N) enriches the experimental design X0 defined in the cur-
rently selected INPUT object with Nnew 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 Nnew samples that correspond to the next elements of the
Sobol sequence.
Output
X1=uq_enrichSobol(...) returns an N-by-Mmatrix 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 = [X0;X1].
[X1, U1] = uq_enrichSobol(...) additionally returns an N-by-Mmatrix (U1) of the new
samples in the uniform space.
3.4.3 Enriching a Halton sequence: uq_enrichHalton
Syntax
X1=uq_enrichHalton(X0, N)
X1=uq_enrichHalton(X0, N, myInput)
[X1, U1] = uq_enrichHalton(...)
Input
X1=uq_enrichHalton(X0, N) enriches the experimental design X0 defined in the cur-
rently selected INPUT object with Nnew 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 Nnew samples that correspond to the next elements of the
Halton sequence.
UQLAB-V1.1-102 - 42 -
The Input module
Output
X1=uq_enrichHalton(...) returns an N-by-Mmatrix 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 = [X0;X1].
[X1, U1] = uq_enrichHalton(...) additionally returns an N-by-Mmatrix (U1) of the
new samples in the uniform space.
3.4.4 Pseudo-LHS enrichment: uq_LHSify
Syntax
X1=uq_LHSify(X0, N)
X1=uq_LHSify(X0, N, myInput)
[X1, U1] = uq_LHSify(...)
Input
X1=uq_LHSify(X0, N) enriches the experimental design X0 defined in the currently se-
lected INPUT object with Nnew 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 Nnew samples so that the enriched sample set forms a pseudo-Latin
Hypercube.
Output
X1=uq_LHSify(...) returns an N-by-Mmatrix of the new samples of the selected ran-
dom vector in the physical space.
Note: X1 only contains the new samples in the physical space. The enriched sample set
is obtained by X = [X0;X1].
[X1, U1] = uq_LHSify(...) additionally returns an N-by-Mmatrix (U1) of the new sam-
ples in the uniform space.
UQLAB-V1.1-102 - 43 -
UQLAB User Manual
3.5 Sub-sampling an existing sample set: uq_subsample
Syntax
X1=uq_subsample(X0, N1, method)
X1=uq_subsample(X0, N1, method, Name, Value)
X1=uq_subsample(...)
[X1, idx] = uq_subsample(...)
Input
X1=uq_subsample(X0, N1, method) reduces the sample size of the experimental design
X0 (N0-by-Mmatrix) 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 8.
Table 8: Available options of uq_subsample(..., Name, 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').
UQLAB-V1.1-102 - 44 -
The Input module
Output
X1=uq_subsample(...) returns an N1-by-Mmatrix that contains a subset of the samples
in X0.
[X1, idx] = uq_subsample(...) additionally returns the indices of the selected 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 Ydefined 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 structures Input.Marginals from Ta-
ble 2 and Input.Copula from Table 3 are used respectively).
Output
Y=uq_GeneralIsopTransform(...) returns an N-by-Mmatrix Ythat contains the trans-
formed 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 2 (Sec-
tion 3.1).
UQLAB-V1.1-102 - 45 -
UQLAB User Manual
Note: The .Type and .Parameters fields of X_marginals,Y_marginals are nec-
essary. 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.
Output
Y=uq_IsopTransform(...) returns an N-by-Mmatrix Ythat 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 structures XMarginals and XCopula. The guidelines
for specifying XMarginals (resp. XCopula) can be found in Table 2 (resp. Table 3)inSec-
tion 3.1.
Output
U=uq_NatafTransform(...) returns an N-by-Mmatrix Uthat contains Nsamples from
Mindependent 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 Xdefined by
XMarginals and XCopula. The guidelines for specifying XMarginals (resp. XCopula) can
be found in Table 2 (resp. Table 3)inSection 3.1.
UQLAB-V1.1-102 - 46 -
The Input module
Output
X=uq_invNatafTransform( ... ) returns an N-by-Mmatrix Xthat contains Nsamples
of size M, each row being a realization of the random vector defined by XMarginals and
XCopula.
UQLAB-V1.1-102 - 47 -
UQLAB User Manual
3.7 Additional functions
3.7.1 uq_sampleU
Syntax
U=uq_sampleU(N, M)
U=uq_sampleU(N, M, options)
Input
U=uq_sampleU(N, M) returns Nsamples of a random vector having Mindependent, uni-
form marginals over [0,1] (i.e. uniform sample over the unit hypercube of dimension M).
U=uq_sampleU(N, M, options) returns Nsamples of a random vector having Min-
dependent uniform marginals over [0,1], with sampling options defined in the structure
options (Table 9).
Table 9: options of uq_sample_u
.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 design. For more
information refer to the MATLAB
function lhsdesign.
.SobolGen sobolset object Sobol sequence point set
.HaltonGen haltonset object Halton sequence point set
Note: For customizing Sobol or Halton sampling, one can set the relevant fields of
options.SobolGen or options.HaltonGen objects. For more details refer to
the MATLAB documentation of sobolset and haltonset respectively.
Output
U=uq_sampleU(...) returns an N-by-Mmatrix of samples of the unit hypercube.
UQLAB-V1.1-102 - 48 -
The Input module
3.7.2 uq_MarginalFields
Syntax
uq_MarginalFields(marginals)
updated_marginals = uq_MarginalFields( ... )
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 structure as described in Table 2 (Section 3.1).
Output
updated_marginals = uq_MarginalFields( ... ) returns an updated structure having
both the Parameters and Moments fields filled.
3.7.3 uq_estimateMoments
Syntax
uq_estimateMoments(marginal)
uq_estimateMoments(marginal, Name, Value)
moments = uq_estimateMoments(...)
[moments, exit_flag] = uq_estimateMoments(...)
[moments, exit_flag, convergence] = uq_estimateMoments(...)
Input
The uq_estimateMoments function computes the moments (mean and standard deviation)
of a distribution numerically. By default the moments are estimated by numerical integration.
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 = uq_estimateMoments(marginal) calculates the moments of the distribution
that is described by the marginal structure as described in Table 2 (Section 3.1).
UQLAB-V1.1-102 - 49 -
UQLAB User Manual
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 10.
Table 10: Available options of uq_estimateMoments
Name Value (default) Description
'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 (106) Initial sample size
'Nstep' Double (105) 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 9 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(marginal) returns a 2×1vector that contains the mean
and standard deviation of the distribution.
[moments, exit_flag] = uq_estimateMoments(marginal) 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(marginal) additionally
returns a Ni×3matrix, where Niis 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.7.4 uq_setDefaultSampling
Syntax
UQLAB-V1.1-102 - 50 -
The Input module
uq_setDefaultSampling(method)
uq_setDefaultSampling(myInput, method)
success = uq_setDefaultSampling(...)
Description
uq_setDefaultSampling(method) sets the default sampling method of the currently se-
lected INPUT object to method. The accepted values of method can be found in Table 6.
uq_setDefaultSampling(myInput, method) sets the default sampling method of the IN-
PUT object myInput to method.
UQLAB-V1.1-102 - 51 -
References
Lebrun, R. and A. Dutfoy (2009). A generalization of the Nataf transformation to distribu-
tions with elliptical copula. Prob. Eng. Mech. 24(2), 172–178. 18
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. 25
Nelsen, R. B. (2006). An Introduction to Copulas. Secaucus, NJ, USA: Springer-Verlag New
York, Inc. 15,16,17
Saporta, G. (2006). Probabilit´
es, analyse des donn´
ees et statistique. Editions Technip. 49
52

Navigation menu