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

.. code-block:: default

    import pylab as plt
    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 35-39

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

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

.. GENERATED FROM PYTHON SOURCE LINES 41-43

.. code-block:: default

    uniform = ot.Uniform(2, 5)








.. GENERATED FROM PYTHON SOURCE LINES 44-45

The `drawPDF` method plots the probability density function.

.. GENERATED FROM PYTHON SOURCE LINES 47-50

.. code-block:: default

    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 51-52

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

.. GENERATED FROM PYTHON SOURCE LINES 54-56

.. code-block:: default

    uniform.computePDF(3.5)





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

 Out:

 .. code-block:: none


    0.3333333333333333



.. GENERATED FROM PYTHON SOURCE LINES 57-58

The `drawCDF` method plots the cumulated distribution function.

.. GENERATED FROM PYTHON SOURCE LINES 60-63

.. code-block:: default

    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 64-65

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

.. GENERATED FROM PYTHON SOURCE LINES 67-69

.. code-block:: default

    uniform.computeCDF(3.5)





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

 Out:

 .. code-block:: none


    0.5



.. GENERATED FROM PYTHON SOURCE LINES 70-71

The `getSample` method generates a sample.

.. GENERATED FROM PYTHON SOURCE LINES 73-76

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

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

.. GENERATED FROM PYTHON SOURCE LINES 80-84

.. code-block:: default

    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 85-87

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

.. GENERATED FROM PYTHON SOURCE LINES 89-95

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 97-98

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 100-101

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 103-108

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

We can also use the `IndependentCopula` class.

.. GENERATED FROM PYTHON SOURCE LINES 112-118

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

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 122-123

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

.. GENERATED FROM PYTHON SOURCE LINES 125-127

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

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

.. GENERATED FROM PYTHON SOURCE LINES 131-138

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

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

.. GENERATED FROM PYTHON SOURCE LINES 142-144

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

.. GENERATED FROM PYTHON SOURCE LINES 146-147

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

.. GENERATED FROM PYTHON SOURCE LINES 149-154

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

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

.. GENERATED FROM PYTHON SOURCE LINES 158-161

.. code-block:: default

    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 162-164

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

.. GENERATED FROM PYTHON SOURCE LINES 166-167

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 169-176

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

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

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

.. GENERATED FROM PYTHON SOURCE LINES 188-190

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

.. GENERATED FROM PYTHON SOURCE LINES 192-193

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 195-202

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

.. code-block:: default

    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-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 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-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 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-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 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-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 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-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 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  0.871 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>`_