.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_meta_modeling/polynomial_chaos_metamodel/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_meta_modeling_polynomial_chaos_metamodel_plot_chaos_distribution_transformation.py>`
        to download the full example code

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

.. _sphx_glr_auto_meta_modeling_polynomial_chaos_metamodel_plot_chaos_distribution_transformation.py:


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

.. GENERATED FROM PYTHON SOURCE LINES 6-13

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

In this document 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 `DistributionTransformation`.

.. GENERATED FROM PYTHON SOURCE LINES 16-36

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 38-55

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 57-59

.. code-block:: Python

    import openturns as ot








.. GENERATED FROM PYTHON SOURCE LINES 60-63

In the first step, we define the LogNormal 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 `ParametrizedDistribution` class.

.. GENERATED FROM PYTHON SOURCE LINES 65-68

.. code-block:: Python

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








.. GENERATED FROM PYTHON SOURCE LINES 69-70

Then we generate a 5-point sample.

.. GENERATED FROM PYTHON SOURCE LINES 72-75

.. 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>24851.57</td></tr>
      <tr><th>1</th><td>39644.81</td></tr>
      <tr><th>2</th><td>27619.95</td></tr>
      <tr><th>3</th><td>28962.72</td></tr>
      <tr><th>4</th><td>25575.91</td></tr>
    </table>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 76-77

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

.. GENERATED FROM PYTHON SOURCE LINES 79-81

.. code-block:: Python

    Z = ot.Normal()








.. GENERATED FROM PYTHON SOURCE LINES 82-83

We also generate a sample from it.

.. GENERATED FROM PYTHON SOURCE LINES 85-88

.. 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.2627547</td></tr>
      <tr><th>1</th><td>0.2319856</td></tr>
      <tr><th>2</th><td>-0.3728253</td></tr>
      <tr><th>3</th><td>-0.3093705</td></tr>
      <tr><th>4</th><td>-1.054682</td></tr>
    </table>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 89-90

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

.. GENERATED FROM PYTHON SOURCE LINES 92-94

.. code-block:: Python

    T = ot.DistributionTransformation(X, Z)








.. GENERATED FROM PYTHON SOURCE LINES 95-96

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

.. GENERATED FROM PYTHON SOURCE LINES 98-100

.. 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.4809216</td></tr>
      <tr><th>1</th><td>1.172666</td></tr>
      <tr><th>2</th><td>-0.03431651</td></tr>
      <tr><th>3</th><td>0.1480268</td></tr>
      <tr><th>4</th><td>-0.3529745</td></tr>
    </table>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 101-102

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

.. GENERATED FROM PYTHON SOURCE LINES 104-106

.. code-block:: Python

    Tinverse = T.inverse()








.. GENERATED FROM PYTHON SOURCE LINES 107-109

.. 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>26118.46</td></tr>
      <tr><th>1</th><td>29628.14</td></tr>
      <tr><th>2</th><td>25460.13</td></tr>
      <tr><th>3</th><td>25834.74</td></tr>
      <tr><th>4</th><td>22166.9</td></tr>
    </table>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 110-118

Conclusion
----------

The `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_meta_modeling_polynomial_chaos_metamodel_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>`