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

.. only:: html

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

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

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

.. _sphx_glr_auto_surrogate_modeling_polynomial_chaos_plot_chaos_distribution_transformation.py:


Apply a transform or inverse transform on your polynomial chaos
===============================================================

.. GENERATED FROM PYTHON SOURCE LINES 7-14

Introduction
------------

In this example, we present the transformation involved in the creation of a polynomial chaos.
Indeed, the polynomial chaos expansion is never directly applied to the input random variable of a model :math:`g`.
Instead, the expansion is expressed based on the associated standard random variable.
In this example,  we show how to transform a Log-Normal random variable into its standardized variable with the class :class:`~openturns.DistributionTransformation`.

.. GENERATED FROM PYTHON SOURCE LINES 17-37

Probabilistic transform
-----------------------

Let :math:`T` be the probabilistic transform which maps the physical random variable :math:`X` to the standardized random variable :math:`\xi`:

.. math::
   \xi = T(X).


Let :math:`F_X` be the Cumulative Distribution Function (CDF) associated with
the random variable :math:`X` and let :math:`F_\xi` be the CDF associated
with the random variable :math:`\xi`. Therefore, :math:`F_\xi` is the CDF
associated with the orthogonal polynomials involved in the polynomial chaos expansion.
In this case, the transform is:

.. math::
   \xi = F_\xi^{-1} \left( F_X(X) \right),


for any :math:`X \in \mathbb{R}`.

.. GENERATED FROM PYTHON SOURCE LINES 39-56

Example
-------

We want to use the Hermite orthogonal polynomials to expand a Log-Normal random variable:

* let :math:`X` follow the Log-Normal distribution with the following parameters: LogNormal(:math:`\mu=3 \times 10^4`, :math:`\sigma=9\times 10^3`),
* let :math:`Z=\xi` follow the Normal distribution with zero mean and unit standard deviation (the letter :math:`Z` is often used for standard Normal random variables).

Let :math:`F_{LN}` be the CDF of the Log-Normal distribution associated with :math:`X` and let :math:`\Phi` be the CDF of the standard Normal distribution.

Therefore,

.. math::
   Z = T(X) = \Phi^{-1}(F_{LN}(X)),


for any :math:`X \in \mathbb{R}`.

.. GENERATED FROM PYTHON SOURCE LINES 58-60

.. code-block:: Python

    import openturns as ot








.. GENERATED FROM PYTHON SOURCE LINES 61-64

In the first step, we define the Log-Normal distribution.
Its parameters - mean and standard deviation - have been selected so that there is no ambiguity with the standard Normal distribution.
This parametrization can be used thanks to the :class:`~openturns.ParametrizedDistribution` class.

.. GENERATED FROM PYTHON SOURCE LINES 66-69

.. code-block:: Python

    Xparam = ot.LogNormalMuSigma(3.0e4, 9.0e3, 15.0e3)  # in N
    X = ot.ParametrizedDistribution(Xparam)








.. GENERATED FROM PYTHON SOURCE LINES 70-71

Then we generate a 5-point sample.

.. GENERATED FROM PYTHON SOURCE LINES 73-76

.. code-block:: Python

    sampleX = X.getSample(5)
    sampleX






.. 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>33021.47</td></tr>
      <tr><th>1</th><td>21373.82</td></tr>
      <tr><th>2</th><td>25087.37</td></tr>
      <tr><th>3</th><td>40097.32</td></tr>
      <tr><th>4</th><td>18837.04</td></tr>
    </table>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 77-78

In the second step, we define the random variable :math:`Z` with standard Normal distribution.

.. GENERATED FROM PYTHON SOURCE LINES 80-82

.. code-block:: Python

    Z = ot.Normal()








.. GENERATED FROM PYTHON SOURCE LINES 83-84

We also generate a sample from it.

.. GENERATED FROM PYTHON SOURCE LINES 86-89

.. code-block:: Python

    sampleZ = Z.getSample(5)
    sampleZ






.. 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>0.3500421</td></tr>
      <tr><th>1</th><td>-0.355007</td></tr>
      <tr><th>2</th><td>1.437249</td></tr>
      <tr><th>3</th><td>0.810668</td></tr>
      <tr><th>4</th><td>0.793156</td></tr>
    </table>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 90-91

In the third step, we create the transform :math:`T` which maps :math:`X` to :math:`Z`.

.. GENERATED FROM PYTHON SOURCE LINES 93-95

.. code-block:: Python

    T = ot.DistributionTransformation(X, Z)








.. GENERATED FROM PYTHON SOURCE LINES 96-97

We apply this transform on the sample generated from :math:`X`.

.. GENERATED FROM PYTHON SOURCE LINES 99-101

.. code-block:: Python

    T(sampleX)






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <table>
      <tr><td></td><th>y0</th></tr>
      <tr><th>0</th><td>0.6082017</td></tr>
      <tr><th>1</th><td>-1.266173</td></tr>
      <tr><th>2</th><td>-0.4382656</td></tr>
      <tr><th>3</th><td>1.205478</td></tr>
      <tr><th>4</th><td>-2.181385</td></tr>
    </table>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 102-103

The inverse transform maps :math:`Z` into :math:`X`.

.. GENERATED FROM PYTHON SOURCE LINES 105-107

.. code-block:: Python

    Tinverse = T.inverse()








.. GENERATED FROM PYTHON SOURCE LINES 108-110

.. code-block:: Python

    Tinverse(sampleZ)






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <table>
      <tr><td></td><th>y0</th></tr>
      <tr><th>0</th><td>30617.79</td></tr>
      <tr><th>1</th><td>25564</td></tr>
      <tr><th>2</th><td>43539.28</td></tr>
      <tr><th>3</th><td>35162.69</td></tr>
      <tr><th>4</th><td>34967.84</td></tr>
    </table>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 111-119

Conclusion
----------

The :class:`~openturns.DistributionTransformation` class is rarely used directly because the polynomial chaos classes perform the transformation automatically.
However, understanding how this transform is done clarifies why the coefficients of the chaos expansion cannot be related to the input random variable :math:`X`
the expansion is based on the standard variables :math:`\xi`.
Hence, the absolute values of the corresponding coefficients have no straightforward interpretation,
even though squaring them yields the part of the global variance associated with each coefficient.


.. _sphx_glr_download_auto_surrogate_modeling_polynomial_chaos_plot_chaos_distribution_transformation.py:

.. only:: html

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

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

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

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

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

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_chaos_distribution_transformation.zip <plot_chaos_distribution_transformation.zip>`