.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_probabilistic_modeling/distributions/plot_quick_start_guide_distributions.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_probabilistic_modeling_distributions_plot_quick_start_guide_distributions.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_probabilistic_modeling_distributions_plot_quick_start_guide_distributions.py:


Quick start guide to distributions
==================================

.. GENERATED FROM PYTHON SOURCE LINES 6-17

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 :class:`~openturns.ComposedDistribution` class, which creates a distribution based on its
marginals and its copula, is presented.
We show how to truncate any distribution with the :class:`~openturns.TruncatedDistribution` class.

.. GENERATED FROM PYTHON SOURCE LINES 19-32

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:

- :class:`~openturns.Uniform`,
- :class:`~openturns.Normal`,
- :class:`~openturns.Beta`,
- :class:`~openturns.LogNormal`,
- :class:`~openturns.Exponential`,
- :class:`~openturns.Weibull`.

.. GENERATED FROM PYTHON SOURCE LINES 34-41

.. code-block:: Python

    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)








.. GENERATED FROM PYTHON SOURCE LINES 42-46

The uniform distribution
------------------------

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

.. GENERATED FROM PYTHON SOURCE LINES 48-50

.. code-block:: Python

    uniform = ot.Uniform(2, 5)








.. GENERATED FROM PYTHON SOURCE LINES 51-52

The :meth:`~openturns.Distribution.drawPDF` method plots the probability density function.

.. GENERATED FROM PYTHON SOURCE LINES 54-57

.. code-block:: Python

    graph = uniform.drawPDF()
    view = viewer.View(graph)




.. image-sg:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_001.png
   :alt: plot quick start guide distributions
   :srcset: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 58-59

The :meth:`~openturns.Distribution.computePDF` method computes the probability distribution at a specific point.

.. GENERATED FROM PYTHON SOURCE LINES 61-63

.. code-block:: Python

    uniform.computePDF(3.5)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    0.3333333333333333



.. GENERATED FROM PYTHON SOURCE LINES 64-65

The :meth:`~openturns.Distribution.drawCDF` method plots the cumulated distribution function.

.. GENERATED FROM PYTHON SOURCE LINES 67-70

.. code-block:: Python

    graph = uniform.drawCDF()
    view = viewer.View(graph)




.. image-sg:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_002.png
   :alt: plot quick start guide distributions
   :srcset: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_002.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 71-72

The :meth:`~openturns.Distribution.computeCDF` method computes the value of the cumulated distribution function a given point.

.. GENERATED FROM PYTHON SOURCE LINES 74-76

.. code-block:: Python

    uniform.computeCDF(3.5)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    0.5



.. GENERATED FROM PYTHON SOURCE LINES 77-78

The :meth:`~openturns.Distribution.getSample` method generates a sample.

.. GENERATED FROM PYTHON SOURCE LINES 80-83

.. code-block:: Python

    sample = uniform.getSample(10)
    sample






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <table>
      <tr><td></td><th>X0</th></tr>
      <tr><th>0</th><td>4.468085</td></tr>
      <tr><th>1</th><td>4.220982</td></tr>
      <tr><th>2</th><td>4.276883</td></tr>
      <tr><th>3</th><td>4.91059</td></tr>
      <tr><th>4</th><td>4.557379</td></tr>
      <tr><th>5</th><td>4.453005</td></tr>
      <tr><th>6</th><td>3.422504</td></tr>
      <tr><th>7</th><td>2.536824</td></tr>
      <tr><th>8</th><td>4.410839</td></tr>
      <tr><th>9</th><td>2.9383</td></tr>
    </table>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 84-85

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

.. GENERATED FROM PYTHON SOURCE LINES 87-91

.. code-block:: Python

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




.. image-sg:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_003.png
   :alt: X0 PDF
   :srcset: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_003.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 92-94

Multivariate distributions with or without independent copula
-------------------------------------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 96-100

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: :class:`~openturns.Normal`, :class:`~openturns.Dirichlet`, :class:`~openturns.Student`.

.. GENERATED FROM PYTHON SOURCE LINES 102-103

Define a multivariate Normal distribution in dimension 4

.. GENERATED FROM PYTHON SOURCE LINES 105-108

.. code-block:: Python

    distribution = ot.Normal(4)
    distribution






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    Normal
    <ul>
      <li>name=Normal</li>
      <li>dimension=4</li>
      <li>weight=1</li>
      <li>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[</li>
      <li>description=[X0,X1,X2,X3]</li>
      <li>isParallel=true</li>
      <li>isCopula=false</li>
    </ul>

    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 109-112

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 :class:`~openturns.ComposedDistribution` class is optional: if it is not specified, the copula is independent by default.

.. GENERATED FROM PYTHON SOURCE LINES 114-119

.. code-block:: Python

    normal = ot.Normal()
    uniform = ot.Uniform()
    distribution = ot.ComposedDistribution([normal, uniform])
    distribution






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    ComposedDistribution
    <ul>
      <li>name=ComposedDistribution</li>
      <li>dimension: 2</li>
      <li>description=[X0,X1]
      <li>copula: IndependentCopula(dimension = 2)</li>
    </ul>

    <table>
      <tr>
        <th>Index</th>
        <th>Variable</th>
        <th>Distribution</th>
      </tr>
      <tr>
        <td>0</td>
        <td>X0</td>
        <td>Normal(mu = 0, sigma = 1)</td>
      </tr>
      <tr>
        <td>1</td>
        <td>X1</td>
        <td>Uniform(a = -1, b = 1)</td>
      </tr>
    </table>

    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 120-121

We can also use the :class:`~openturns.IndependentCopula` class.

.. GENERATED FROM PYTHON SOURCE LINES 123-129

.. code-block:: Python

    normal = ot.Normal()
    uniform = ot.Uniform()
    copula = ot.IndependentCopula(2)
    distribution = ot.ComposedDistribution([normal, uniform], copula)
    distribution






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    ComposedDistribution
    <ul>
      <li>name=ComposedDistribution</li>
      <li>dimension: 2</li>
      <li>description=[X0,X1]
      <li>copula: IndependentCopula(dimension = 2)</li>
    </ul>

    <table>
      <tr>
        <th>Index</th>
        <th>Variable</th>
        <th>Distribution</th>
      </tr>
      <tr>
        <td>0</td>
        <td>X0</td>
        <td>Normal(mu = 0, sigma = 1)</td>
      </tr>
      <tr>
        <td>1</td>
        <td>X1</td>
        <td>Uniform(a = -1, b = 1)</td>
      </tr>
    </table>

    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 130-131

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

.. GENERATED FROM PYTHON SOURCE LINES 133-134

The :meth:`~openturns.Distribution.getSample` method produces a sample from this distribution.

.. GENERATED FROM PYTHON SOURCE LINES 136-138

.. code-block:: Python

    distribution.getSample(10)






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <table>
      <tr><td></td><th>X0</th><th>X1</th></tr>
      <tr><th>0</th><td>0.4237752</td><td>0.03731124</td></tr>
      <tr><th>1</th><td>0.1448278</td><td>-0.9660635</td></tr>
      <tr><th>2</th><td>1.273868</td><td>-0.5232126</td></tr>
      <tr><th>3</th><td>1.384188</td><td>0.9786282</td></tr>
      <tr><th>4</th><td>0.5366251</td><td>0.720757</td></tr>
      <tr><th>5</th><td>1.283038</td><td>0.8316031</td></tr>
      <tr><th>6</th><td>0.6371329</td><td>-0.8106468</td></tr>
      <tr><th>7</th><td>-0.1327306</td><td>-0.6646291</td></tr>
      <tr><th>8</th><td>-1.113346</td><td>-0.1037191</td></tr>
      <tr><th>9</th><td>-0.1808409</td><td>-0.7662679</td></tr>
    </table>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 139-140

In order to visualize a bivariate sample, we can use the :class:`~openturns.Cloud` class.

.. GENERATED FROM PYTHON SOURCE LINES 142-149

.. code-block:: Python

    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-sg:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_004.png
   :alt: X0~N, X1~U
   :srcset: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_004.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 150-151

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

.. GENERATED FROM PYTHON SOURCE LINES 153-155

Define a plot a copula
----------------------

.. GENERATED FROM PYTHON SOURCE LINES 157-158

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

.. GENERATED FROM PYTHON SOURCE LINES 160-165

.. code-block:: Python

    R = ot.CorrelationMatrix(2)
    R[0, 1] = 0.6
    copula = ot.NormalCopula(R)
    copula






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    NormalCopula
    <ul>
      <li>name=NormalCopula</li>
      <li>dimension=2</li>
      <li>weight=1</li>
      <li>range=[0, 1]
    [0, 1]</li>
      <li>description=[X0,X1]</li>
      <li>isParallel=true</li>
      <li>isCopula=true</li>
    </ul>

    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 166-167

We can draw the contours of a copula with the :meth:`~openturns.NormalCopula.drawPDF` method.

.. GENERATED FROM PYTHON SOURCE LINES 169-172

.. code-block:: Python

    graph = copula.drawPDF()
    view = viewer.View(graph)




.. image-sg:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_005.png
   :alt: [X0,X1] iso-PDF
   :srcset: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_005.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 173-175

Multivariate distribution with arbitrary copula
-----------------------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 177-179

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.

.. GENERATED FROM PYTHON SOURCE LINES 181-188

.. code-block:: Python

    normal = ot.Normal()
    uniform = ot.Uniform()
    theta = 0.9
    copula = ot.AliMikhailHaqCopula(theta)
    distribution = ot.ComposedDistribution([normal, uniform], copula)
    distribution






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    ComposedDistribution
    <ul>
      <li>name=ComposedDistribution</li>
      <li>dimension: 2</li>
      <li>description=[X0,X1]
      <li>copula: AliMikhailHaqCopula(theta = 0.9)</li>
    </ul>

    <table>
      <tr>
        <th>Index</th>
        <th>Variable</th>
        <th>Distribution</th>
      </tr>
      <tr>
        <td>0</td>
        <td>X0</td>
        <td>Normal(mu = 0, sigma = 1)</td>
      </tr>
      <tr>
        <td>1</td>
        <td>X1</td>
        <td>Uniform(a = -1, b = 1)</td>
      </tr>
    </table>

    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 189-196

.. code-block:: Python

    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-sg:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_006.png
   :alt: X0~N, X1~U, Ali-Mikhail-Haq copula
   :srcset: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_006.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 197-198

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

.. GENERATED FROM PYTHON SOURCE LINES 200-202

Draw several distributions in the same plot
-------------------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 204-205

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

.. GENERATED FROM PYTHON SOURCE LINES 207-214

.. code-block:: Python

    beta = ot.Beta(5, 7, 9, 10)
    pdfbeta = beta.drawPDF()
    cdfbeta = beta.drawCDF()
    exponential = ot.Exponential(3)
    pdfexp = exponential.drawPDF()
    cdfexp = exponential.drawCDF()








.. GENERATED FROM PYTHON SOURCE LINES 217-224

.. code-block:: Python

    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)




.. image-sg:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_007.png
   :alt: plot quick start guide distributions
   :srcset: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_007.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 225-244

Truncate a distribution
-----------------------

Any distribution can be truncated with the :class:`~openturns.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<b`.
Let :math:`Y` be the random variable defined by:

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

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

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


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

.. GENERATED FROM PYTHON SOURCE LINES 246-247

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

.. GENERATED FROM PYTHON SOURCE LINES 249-253

.. code-block:: Python

    X = ot.LogNormal()
    graph = X.drawPDF()
    view = viewer.View(graph)




.. image-sg:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_008.png
   :alt: plot quick start guide distributions
   :srcset: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_008.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 254-255

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

.. GENERATED FROM PYTHON SOURCE LINES 257-261

.. code-block:: Python

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




.. image-sg:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_009.png
   :alt: plot quick start guide distributions
   :srcset: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_009.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 262-263

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

.. GENERATED FROM PYTHON SOURCE LINES 265-269

.. code-block:: Python

    Y = ot.TruncatedDistribution(X, 1.0, ot.TruncatedDistribution.LOWER)
    graph = Y.drawPDF()
    view = viewer.View(graph)




.. image-sg:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_010.png
   :alt: plot quick start guide distributions
   :srcset: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_010.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 270-271

We can finally truncate a distribution with an upper bound.

.. GENERATED FROM PYTHON SOURCE LINES 273-278

.. code-block:: Python

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

    plt.show()



.. image-sg:: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_011.png
   :alt: plot quick start guide distributions
   :srcset: /auto_probabilistic_modeling/distributions/images/sphx_glr_plot_quick_start_guide_distributions_011.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 279-281

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


.. _sphx_glr_download_auto_probabilistic_modeling_distributions_plot_quick_start_guide_distributions.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_quick_start_guide_distributions.ipynb <plot_quick_start_guide_distributions.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_quick_start_guide_distributions.py <plot_quick_start_guide_distributions.py>`