.. 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

        Click :ref:`here <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
=================

.. GENERATED FROM PYTHON SOURCE LINES 6-10

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.

.. GENERATED FROM PYTHON SOURCE LINES 12-25

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`.

.. GENERATED FROM PYTHON SOURCE LINES 27-32

.. code-block:: default

    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 33-37

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

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

.. GENERATED FROM PYTHON SOURCE LINES 39-41

.. code-block:: default

    uniform = ot.Uniform(2,5)








.. GENERATED FROM PYTHON SOURCE LINES 42-43

The `drawPDF` method plots the probability density function.

.. GENERATED FROM PYTHON SOURCE LINES 45-48

.. 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





.. GENERATED FROM PYTHON SOURCE LINES 49-50

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

.. GENERATED FROM PYTHON SOURCE LINES 52-54

.. code-block:: default

    uniform.computePDF(3.5)





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

 Out:

 .. code-block:: none


    0.3333333333333333



.. GENERATED FROM PYTHON SOURCE LINES 55-56

The `drawCDF` method plots the cumulated distribution function.

.. GENERATED FROM PYTHON SOURCE LINES 58-61

.. 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





.. GENERATED FROM PYTHON SOURCE LINES 62-63

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

.. GENERATED FROM PYTHON SOURCE LINES 65-67

.. code-block:: default

    uniform.computeCDF(3.5)





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

 Out:

 .. code-block:: none


    0.5



.. GENERATED FROM PYTHON SOURCE LINES 68-69

The `getSample` method generates a sample.

.. GENERATED FROM PYTHON SOURCE LINES 71-74

.. code-block:: default

    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>3.381575</TD></TR>
    <TR><TH>1</TH><TD>2.455457</TD></TR>
    <TR><TH>2</TH><TD>2.112089</TD></TR>
    <TR><TH>3</TH><TD>3.161566</TD></TR>
    <TR><TH>4</TH><TD>4.26751</TD></TR>
    <TR><TH>5</TH><TD>4.602825</TD></TR>
    <TR><TH>6</TH><TD>2.90427</TD></TR>
    <TR><TH>7</TH><TD>2.935678</TD></TR>
    <TR><TH>8</TH><TD>4.596476</TD></TR>
    <TR><TH>9</TH><TD>3.3442</TD></TR>
    </TABLE>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 75-76

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

.. GENERATED FROM PYTHON SOURCE LINES 78-82

.. 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





.. GENERATED FROM PYTHON SOURCE LINES 83-85

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

.. GENERATED FROM PYTHON SOURCE LINES 87-93

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.

.. GENERATED FROM PYTHON SOURCE LINES 95-96

In the following script, we define a bivariate distribution made of two univariate distributions (Gaussian and uniform) and an independent copula. 

.. GENERATED FROM PYTHON SOURCE LINES 98-99

The second input argument of the `ComposedDistribution` class is optional: if it is not specified, the copula is independent by default. 

.. GENERATED FROM PYTHON SOURCE LINES 101-106

.. code-block:: default

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






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <p>ComposedDistribution(Normal(mu = 0, sigma = 1), Uniform(a = -1, b = 1), IndependentCopula(dimension = 2))</p>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 107-108

We can also use the `IndependentCopula` class.

.. GENERATED FROM PYTHON SOURCE LINES 110-116

.. code-block:: default

    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">
    <p>ComposedDistribution(Normal(mu = 0, sigma = 1), Uniform(a = -1, b = 1), IndependentCopula(dimension = 2))</p>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 117-118

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 120-121

The `getSample` method produces a sample from this distribution.

.. GENERATED FROM PYTHON SOURCE LINES 123-125

.. code-block:: default

    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>-1.613947</TD><TD>-0.4068471</TD></TR>
    <TR><TH>1</TH><TD>0.2413744</TD><TD>-0.4410861</TD></TR>
    <TR><TH>2</TH><TD>0.0771823</TD><TD>-0.294428</TD></TR>
    <TR><TH>3</TH><TD>-0.3650858</TD><TD>0.9705679</TD></TR>
    <TR><TH>4</TH><TD>1.998394</TD><TD>-0.9066062</TD></TR>
    <TR><TH>5</TH><TD>-0.6699183</TD><TD>-0.9759509</TD></TR>
    <TR><TH>6</TH><TD>-0.8385734</TD><TD>-0.5352073</TD></TR>
    <TR><TH>7</TH><TD>0.5329387</TD><TD>0.6859457</TD></TR>
    <TR><TH>8</TH><TD>0.7407017</TD><TD>-0.1581027</TD></TR>
    <TR><TH>9</TH><TD>0.7210714</TD><TD>0.9109365</TD></TR>
    </TABLE>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 126-127

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

.. GENERATED FROM PYTHON SOURCE LINES 129-136

.. 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





.. GENERATED FROM PYTHON SOURCE LINES 137-138

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

.. GENERATED FROM PYTHON SOURCE LINES 140-142

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

.. GENERATED FROM PYTHON SOURCE LINES 144-145

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

.. GENERATED FROM PYTHON SOURCE LINES 147-152

.. code-block:: default

    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">
    <p>NormalCopula(R = [[ 1   0.6 ]<br>
     [ 0.6 1   ]])</p>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 153-154

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

.. GENERATED FROM PYTHON SOURCE LINES 156-159

.. 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





.. GENERATED FROM PYTHON SOURCE LINES 160-162

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

.. GENERATED FROM PYTHON SOURCE LINES 164-165

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. 

.. GENERATED FROM PYTHON SOURCE LINES 167-174

.. 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

    <div class="output_subarea output_html rendered_html output_result">
    <p>ComposedDistribution(Normal(mu = 0, sigma = 1), Uniform(a = -1, b = 1), AliMikhailHaqCopula(theta = 0.9))</p>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 175-182

.. 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





.. GENERATED FROM PYTHON SOURCE LINES 183-184

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

.. GENERATED FROM PYTHON SOURCE LINES 186-188

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

.. GENERATED FROM PYTHON SOURCE LINES 190-191

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 193-200

.. 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()








.. GENERATED FROM PYTHON SOURCE LINES 201-203

.. code-block:: default

    import openturns.viewer as otv








.. GENERATED FROM PYTHON SOURCE LINES 204-215

.. 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





.. GENERATED FROM PYTHON SOURCE LINES 216-230

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<b`. Let :math:`Y` be the random variable :math:`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 232-233

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 235-239

.. code-block:: default

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




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





.. GENERATED FROM PYTHON SOURCE LINES 240-241

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 243-247

.. code-block:: default

    Y = ot.TruncatedDistribution(X,1.,2.)
    graph = Y.drawPDF()
    view = viewer.View(graph)




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





.. GENERATED FROM PYTHON SOURCE LINES 248-249

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

.. GENERATED FROM PYTHON SOURCE LINES 251-255

.. code-block:: default

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




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





.. GENERATED FROM PYTHON SOURCE LINES 256-257

We can finally truncate a distribution with an upper bound.

.. GENERATED FROM PYTHON SOURCE LINES 259-264

.. code-block:: default

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

    plt.show()



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





.. GENERATED FROM PYTHON SOURCE LINES 265-266

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


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  1.471 seconds)


.. _sphx_glr_download_auto_probabilistic_modeling_distributions_plot_quick_start_guide_distributions.py:


.. only :: html

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



  .. 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>`



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

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


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_