` to download the full example code
.. rst-class:: sphx-glr-example-title
.. _sphx_glr_auto_probabilistic_modeling_distributions_plot_quick_start_guide_distributions.py:
Create univariate and multivariate distributions: a 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 `ComposedDistribution` 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.
In the OpenTURNS platform, several *univariate distributions* are implemented. The most commonly used are:
- `Uniform`,
- `Normal`,
- `Beta`,
- `LogNormal`,
- `Exponential`,
- `Weibull`.
.. code-block:: default
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 :math:`\mathcal{U}(2,5)`.
.. code-block:: default
uniform = ot.Uniform(2,5)
The `drawPDF` method plots the probability density function.
.. code-block:: default
graph = uniform.drawPDF()
view = viewer.View(graph)
.. image:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_001.png
:alt: plot quick start guide distributions
:class: sphx-glr-single-img
The `computePDF` method computes the probability distribution at a specific point.
.. code-block:: default
uniform.computePDF(3.5)
.. rst-class:: sphx-glr-script-out
Out:
.. code-block:: none
0.3333333333333333
The `drawCDF` method plots the cumulated distribution function.
.. code-block:: default
graph = uniform.drawCDF()
view = viewer.View(graph)
.. image:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_002.png
:alt: plot quick start guide distributions
:class: sphx-glr-single-img
The `computeCDF` method computes the value of the cumulated distribution function a given point.
.. code-block:: default
uniform.computeCDF(3.5)
.. rst-class:: sphx-glr-script-out
Out:
.. code-block:: none
0.5
The `getSample` method generates a sample.
.. code-block:: default
sample = uniform.getSample(10)
sample
.. raw:: html
| X0 |
0 | 3.540217 |
1 | 4.186363 |
2 | 3.796623 |
3 | 2.244979 |
4 | 4.516745 |
5 | 2.706726 |
6 | 3.45518 |
7 | 4.295657 |
8 | 3.640201 |
9 | 2.055526 |
The most common way to "see" a sample is to plot the empirical histogram.
.. code-block:: default
sample = uniform.getSample(1000)
graph = ot.HistogramFactory().build(sample).drawPDF()
view = viewer.View(graph)
.. image:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_003.png
:alt: X0 PDF
:class: sphx-glr-single-img
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`.
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 `ComposedDistribution` class is optional: if it is not specified, the copula is independent by default.
.. code-block:: default
normal = ot.Normal()
uniform = ot.Uniform()
distribution = ot.ComposedDistribution([normal, uniform])
distribution
.. raw:: html
ComposedDistribution(Normal(mu = 0, sigma = 1), Uniform(a = -1, b = 1), IndependentCopula(dimension = 2))
We can also use the `IndependentCopula` class.
.. code-block:: default
normal = ot.Normal()
uniform = ot.Uniform()
copula = ot.IndependentCopula(2)
distribution = ot.ComposedDistribution([normal, uniform], copula)
distribution
.. raw:: html
ComposedDistribution(Normal(mu = 0, sigma = 1), Uniform(a = -1, b = 1), IndependentCopula(dimension = 2))
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.
.. code-block:: default
distribution.getSample(10)
.. raw:: html
| X0 | X1 |
0 | -0.8152716 | 0.5865111 |
1 | -0.6392132 | 0.738932 |
2 | 1.632357 | 0.9835865 |
3 | 2.147953 | -0.2462071 |
4 | -1.546417 | -0.1164286 |
5 | 1.931777 | 0.6615492 |
6 | -1.482484 | -0.6689347 |
7 | -0.7122513 | 0.4741733 |
8 | -0.03644661 | -0.4998729 |
9 | -0.01658812 | -0.2449791 |
In order to visualize a bivariate sample, we can use the `Cloud` class.
.. code-block:: default
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)
.. image:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_004.png
:alt: X0~N, X1~U
:class: sphx-glr-single-img
We see that the marginals are Gaussian and uniform and that the copula is independent.
Define a plot a copula
----------------------
The `NormalCopula` class allows to create a Gaussian copula. Such a copula is defined by its correlation matrix.
.. code-block:: default
R = ot.CorrelationMatrix(2)
R[0,1] = 0.6
copula = ot.NormalCopula(R)
copula
.. raw:: html
NormalCopula(R = [[ 1 0.6 ]
[ 0.6 1 ]])
We can draw the contours of a copula with the `drawPDF` method.
.. code-block:: default
graph = copula.drawPDF()
view = viewer.View(graph)
.. image:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_005.png
:alt: [X0,X1] iso-PDF
:class: sphx-glr-single-img
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 the Ali-Mikhail-Haq copula as an example of a non trivial dependence.
.. code-block:: default
normal = ot.Normal()
uniform = ot.Uniform()
theta = 0.9
copula = ot.AliMikhailHaqCopula(theta)
distribution = ot.ComposedDistribution([normal, uniform], copula)
distribution
.. raw:: html
ComposedDistribution(Normal(mu = 0, sigma = 1), Uniform(a = -1, b = 1), AliMikhailHaqCopula(theta = 0.9))
.. code-block:: default
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)
.. image:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_006.png
:alt: X0~N, X1~U, Ali-Mikhail-Haq copula
:class: sphx-glr-single-img
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.
.. code-block:: default
beta = ot.Beta(5, 7, 9, 10)
pdfbeta = beta.drawPDF()
cdfbeta = beta.drawCDF()
exponential = ot.Exponential(3)
pdfexp = exponential.drawPDF()
cdfexp = exponential.drawCDF()
.. code-block:: default
import openturns.viewer as otv
.. code-block:: default
import pylab as plt
fig = plt.figure(figsize=(12, 4))
ax = fig.add_subplot(2, 2, 1)
_ = otv.View(pdfbeta, figure=fig, axes=[ax])
ax = fig.add_subplot(2, 2, 2)
_ = otv.View(cdfbeta, figure=fig, axes=[ax])
ax = fig.add_subplot(2, 2, 3)
_ = otv.View(pdfexp, figure=fig, axes=[ax])
ax = fig.add_subplot(2, 2, 4)
_ = otv.View(cdfexp, figure=fig, axes=[ax])
.. image:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_007.png
:alt: plot quick start guide distributions
:class: sphx-glr-single-img
Truncate a distribution
-----------------------
Any distribution can be truncated with the `TruncatedDistribution` class.
Let :math:`f_X` (resp. :math:`F_X`) the PDF (resp. the CDF) of the real random variable :math:`X`. Let :math:`a` and :math:`b` two reals with :math:`a`
.. container:: sphx-glr-download sphx-glr-download-jupyter
:download:`Download Jupyter notebook: plot_quick_start_guide_distributions.ipynb `
.. only:: html
.. rst-class:: sphx-glr-signature
`Gallery generated by Sphinx-Gallery `_