Quick start guide to distributions

Abstract

In this example, we present classes for univariate and multivariate distributions. We demonstrate the probabilistic programming capabilities of the library. For univariate distributions, we show how to compute the probability density, the cumulated probability density and the quantiles. We also show how to create graphics. The JointDistribution class, which creates a distribution based on its marginals and its copula, is presented. We show how to truncate any distribution with the TruncatedDistribution class.

Univariate distribution

The library is a probabilistic programming library: it is possible to create a random variable and perform operations on this variable without generating a sample.

Several univariate distributions are implemented in the library. The most commonly used are:

import openturns.viewer as otv
import openturns as ot
import openturns.viewer as viewer
from matplotlib import pylab as plt

ot.Log.Show(ot.Log.NONE)

The uniform distribution

Let us create a uniform random variable \mathcal{U}(2,5).

uniform = ot.Uniform(2, 5)

The drawPDF() method plots the probability density function.

graph = uniform.drawPDF()
view = viewer.View(graph)
plot quick start guide distributions

The computePDF() method computes the probability distribution at a specific point.

uniform.computePDF(3.5)
0.3333333333333333

The drawCDF() method plots the cumulated distribution function.

graph = uniform.drawCDF()
view = viewer.View(graph)
plot quick start guide distributions

The computeCDF() method computes the value of the cumulated distribution function a given point.

uniform.computeCDF(3.5)
0.5

The getSample() method generates a sample.

sample = uniform.getSample(10)
sample
X0
04.468085
14.220982
24.276883
34.91059
44.557379
54.453005
63.422504
72.536824
84.410839
92.9383


The most common way to “see” a sample is to plot the empirical histogram.

sample = uniform.getSample(1000)
graph = ot.HistogramFactory().build(sample).drawPDF()
view = viewer.View(graph)
X0 PDF

Multivariate distributions with or without independent copula

We can create multivariate distributions by two different methods:

  • we can also create a multivariate distribution by combining a list of univariate marginal distribution and a copula,

  • some distributions are defined as multivariate distributions: Normal, Dirichlet, Student.

Define a multivariate Normal distribution in dimension 4

distribution = ot.Normal(4)
distribution
Normal
  • name=Normal
  • dimension=4
  • weight=1
  • range=]-inf (-7.65063), (7.65063) +inf[ ]-inf (-7.65063), (7.65063) +inf[ ]-inf (-7.65063), (7.65063) +inf[ ]-inf (-7.65063), (7.65063) +inf[
  • description=[X0,X1,X2,X3]
  • isParallel=true
  • isCopula=false


Since the method based on a marginal and a copula is more flexible, we illustrate below this principle. In the following script, we define a bivariate distribution made of two univariate distributions (Gaussian and uniform) and an independent copula. The second input argument of the JointDistribution class is optional: if it is not specified, the copula is independent by default.

normal = ot.Normal()
uniform = ot.Uniform()
distribution = ot.JointDistribution([normal, uniform])
distribution
JointDistribution
  • name=JointDistribution
  • dimension: 2
  • description=[X0,X1]
  • copula: IndependentCopula(dimension = 2)
Index Variable Distribution
0 X0 Normal(mu = 0, sigma = 1)
1 X1 Uniform(a = -1, b = 1)


We can also use the IndependentCopula class.

normal = ot.Normal()
uniform = ot.Uniform()
copula = ot.IndependentCopula(2)
distribution = ot.JointDistribution([normal, uniform], copula)
distribution
JointDistribution
  • name=JointDistribution
  • dimension: 2
  • description=[X0,X1]
  • copula: IndependentCopula(dimension = 2)
Index Variable Distribution
0 X0 Normal(mu = 0, sigma = 1)
1 X1 Uniform(a = -1, b = 1)


We see that this produces the same result: in the end of this section, we will change the copula and see what happens.

The getSample() method produces a sample from this distribution.

distribution.getSample(10)
X0X1
00.42377520.03731124
10.1448278-0.9660635
21.273868-0.5232126
31.3841880.9786282
40.53662510.720757
51.2830380.8316031
60.6371329-0.8106468
7-0.1327306-0.6646291
8-1.113346-0.1037191
9-0.1808409-0.7662679


In order to visualize a bivariate sample, we can use the Cloud class.

sample = distribution.getSample(1000)
showAxes = True
graph = ot.Graph("X0~N, X1~U", "X0", "X1", showAxes)
cloud = ot.Cloud(sample, "blue", "fsquare", "")  # Create the cloud
graph.add(cloud)  # Then, add it to the graph
view = viewer.View(graph)
X0~N, X1~U

We see that the marginals are Gaussian and uniform and that the copula is independent.

Define a plot a copula

The NormalCopula class allows one to create a Gaussian copula. Such a copula is defined by its correlation matrix.

R = ot.CorrelationMatrix(2)
R[0, 1] = 0.6
copula = ot.NormalCopula(R)
copula
NormalCopula
  • name=NormalCopula
  • dimension=2
  • weight=1
  • range=[0, 1] [0, 1]
  • description=[X0,X1]
  • isParallel=true
  • isCopula=true


We can draw the contours of a copula with the drawPDF() method.

graph = copula.drawPDF()
view = viewer.View(graph)
[X0,X1] iso-PDF

Multivariate distribution with arbitrary copula

Now that we know that we can define a copula, we create a bivariate distribution with normal and uniform marginals and an arbitrary copula. We select the Ali-Mikhail-Haq copula as an example of a non trivial dependence.

normal = ot.Normal()
uniform = ot.Uniform()
theta = 0.9
copula = ot.AliMikhailHaqCopula(theta)
distribution = ot.JointDistribution([normal, uniform], copula)
distribution
JointDistribution
  • name=JointDistribution
  • dimension: 2
  • description=[X0,X1]
  • copula: AliMikhailHaqCopula(theta = 0.9)
Index Variable Distribution
0 X0 Normal(mu = 0, sigma = 1)
1 X1 Uniform(a = -1, b = 1)


sample = distribution.getSample(1000)
showAxes = True
graph = ot.Graph("X0~N, X1~U, Ali-Mikhail-Haq copula", "X0", "X1", showAxes)
cloud = ot.Cloud(sample, "blue", "fsquare", "")  # Create the cloud
graph.add(cloud)  # Then, add it to the graph
view = viewer.View(graph)
X0~N, X1~U, Ali-Mikhail-Haq copula

We see that the sample is quite different from the previous sample with independent copula.

Draw several distributions in the same plot

It is sometimes convenient to create a plot presenting the PDF and CDF on the same graphics. This is possible thanks to Matplotlib.

beta = ot.Beta(5, 7, 9, 10)
pdfbeta = beta.drawPDF()
cdfbeta = beta.drawCDF()
exponential = ot.Exponential(3)
pdfexp = exponential.drawPDF()
cdfexp = exponential.drawCDF()
grid = ot.GridLayout(2, 2)
grid.setGraph(0, 0, pdfbeta)
grid.setGraph(0, 1, cdfbeta)
grid.setGraph(1, 0, pdfexp)
grid.setGraph(1, 1, cdfexp)
view = otv.View(grid)
plot quick start guide distributions

Truncate a distribution

Any distribution can be truncated with the TruncatedDistribution class. Let f_X (resp. F_X) the PDF (resp. the CDF) of the real random variable X. Let a and b two reals with a<b. Let Y be the random variable defined by:

Y = \max(a, \min(b, X)).

Its distribution is the distribution of X truncated to the [a,b] interval. Therefore, the PDF of Y is:

f_Y(y) = \frac{f_X(y)}{F_X(b) - F_X(a)}

if y\in[a,b] and f_Y(y)=0 otherwise.

Consider for example the log-normal variable X with mean \mu=0 and standard deviation \sigma=1.

X = ot.LogNormal()
graph = X.drawPDF()
view = viewer.View(graph)
plot quick start guide distributions

We can truncate this distribution to the [1,2] interval. We see that the PDF of the distribution becomes discontinuous at the truncation points 1 and 2.

Y = ot.TruncatedDistribution(X, 1.0, 2.0)
graph = Y.drawPDF()
view = viewer.View(graph)
plot quick start guide distributions

We can also also truncate it with only a lower bound.

Y = ot.TruncatedDistribution(X, 1.0, ot.TruncatedDistribution.LOWER)
graph = Y.drawPDF()
view = viewer.View(graph)
plot quick start guide distributions

We can finally truncate a distribution with an upper bound.

Y = ot.TruncatedDistribution(X, 2.0, ot.TruncatedDistribution.UPPER)
graph = Y.drawPDF()
view = viewer.View(graph)

plt.show()
plot quick start guide distributions

In the specific case of the Gaussian distribution, the specialized TruncatedNormal distribution can be used instead of the generic TruncatedDistribution class.