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

.. only:: html

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

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

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

.. _sphx_glr_auto_reliability_sensitivity_sensitivity_analysis_plot_sensitivity_sobol.py:


Estimate Sobol' indices for the Ishigami function by a sampling method: a quick start guide to sensitivity analysis
===================================================================================================================

.. GENERATED FROM PYTHON SOURCE LINES 6-8

In this example, we estimate the Sobol' indices for the :ref:`Ishigami function <use-case-ishigami>` by sampling methods.


.. GENERATED FROM PYTHON SOURCE LINES 11-39

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

In this example we are going to quantify the correlation between the input variables and the output variable of a model thanks to Sobol indices.

Sobol indices are designed to evaluate the importance of a single variable or a specific set of variables.
Here the Sobol indices are estimated by sampling from the distributions of the input variables and propagating uncertainty through a function.

In theory, Sobol indices range from 0 to 1; the closer an index value is to 1, the better the associated input variable explains the function output.

Let us denote by :math:`d` the input dimension of the model.

Sobol' indices can be computed at different orders.

* First order indices evaluate the importance of one input variable at a time.

* Total indices give the relative importance of one input variable and all its interactions with other variables.
  Alternatively, they can be viewed as measuring how much wriggle room remains to the output when all but one input variables are fixed.

* In general, we are only interested in first order and total Sobol' indices.
  There are situations, however, where we want to estimate interactions.
  Second order indices evaluate the importance of every pair of input variables. The number of second order indices is:

.. math::
   \binom{d}{2} = \frac{d \times \left( d-1\right)}{2}.

In practice, when the number of input variables is not small (say, when :math:`d>5`), then the number of second order indices is too large to be easily analyzed.
In these situations, we limit the analysis to the first order and total Sobol' indices.

.. GENERATED FROM PYTHON SOURCE LINES 41-43

Define the model
----------------

.. GENERATED FROM PYTHON SOURCE LINES 45-54

.. code-block:: Python

    from openturns.usecases import ishigami_function
    import openturns as ot
    import pylab as pl
    import openturns.viewer
    import openturns.viewer as viewer
    from matplotlib import pylab as plt

    ot.Log.Show(ot.Log.NONE)








.. GENERATED FROM PYTHON SOURCE LINES 55-56

We load the Ishigami model from the usecases model :

.. GENERATED FROM PYTHON SOURCE LINES 56-58

.. code-block:: Python

    im = ishigami_function.IshigamiModel()








.. GENERATED FROM PYTHON SOURCE LINES 59-61

The `IshigamiModel` data class contains the input distribution :math:`X=(X_1, X_2, X_3)` in `im.distributionX` and the Ishigami function in `im.model`.
We also have access to the input variable names with

.. GENERATED FROM PYTHON SOURCE LINES 61-63

.. code-block:: Python

    input_names = im.distributionX.getDescription()








.. GENERATED FROM PYTHON SOURCE LINES 64-66

Draw the function
-----------------

.. GENERATED FROM PYTHON SOURCE LINES 68-73

.. code-block:: Python

    n = 10000
    sampleX = im.distributionX.getSample(n)
    sampleY = im.model(sampleX)









.. GENERATED FROM PYTHON SOURCE LINES 74-89

.. code-block:: Python

    def plotXvsY(sampleX, sampleY, figsize=(15, 3)):
        dimX = sampleX.getDimension()
        inputdescr = sampleX.getDescription()
        fig = pl.figure(figsize=figsize)
        for i in range(dimX):
            ax = fig.add_subplot(1, dimX, i + 1)
            graph = ot.Graph("", inputdescr[i], "Y", True, "")
            cloud = ot.Cloud(sampleX[:, i], sampleY)
            graph.add(cloud)
            _ = ot.viewer.View(graph, figure=fig, axes=[ax])
        return fig


    plotXvsY(sampleX, sampleY, figsize=(10, 4))




.. image-sg:: /auto_reliability_sensitivity/sensitivity_analysis/images/sphx_glr_plot_sensitivity_sobol_001.png
   :alt: plot sensitivity sobol
   :srcset: /auto_reliability_sensitivity/sensitivity_analysis/images/sphx_glr_plot_sensitivity_sobol_001.png
   :class: sphx-glr-single-img


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

 .. code-block:: none


    <Figure size 1000x400 with 3 Axes>



.. GENERATED FROM PYTHON SOURCE LINES 90-93

.. code-block:: Python

    graph = ot.HistogramFactory().build(sampleY).drawPDF()
    view = viewer.View(graph)




.. image-sg:: /auto_reliability_sensitivity/sensitivity_analysis/images/sphx_glr_plot_sensitivity_sobol_002.png
   :alt: y PDF
   :srcset: /auto_reliability_sensitivity/sensitivity_analysis/images/sphx_glr_plot_sensitivity_sobol_002.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 94-95

We see that the distribution of the output has two modes.

.. GENERATED FROM PYTHON SOURCE LINES 97-99

Estimate the Sobol' indices
---------------------------

.. GENERATED FROM PYTHON SOURCE LINES 101-103

We first create a design of experiments with the `SobolIndicesExperiment`.
Since we are not interested in second order indices for the moment, we use the default value of the third argument (we will come back to this topic later).

.. GENERATED FROM PYTHON SOURCE LINES 105-112

.. code-block:: Python

    size = 1000
    sie = ot.SobolIndicesExperiment(im.distributionX, size)
    inputDesign = sie.generate()
    input_names = im.distributionX.getDescription()
    inputDesign.setDescription(input_names)
    inputDesign.getSize()





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

 .. code-block:: none


    5000



.. GENERATED FROM PYTHON SOURCE LINES 113-114

We see that 5000 function evaluations are required to estimate the first order and total Sobol' indices.

.. GENERATED FROM PYTHON SOURCE LINES 116-117

Then we evaluate the outputs corresponding to this design of experiments.

.. GENERATED FROM PYTHON SOURCE LINES 119-121

.. code-block:: Python

    outputDesign = im.model(inputDesign)








.. GENERATED FROM PYTHON SOURCE LINES 122-123

Then we estimate the Sobol' indices with the `SaltelliSensitivityAlgorithm`.

.. GENERATED FROM PYTHON SOURCE LINES 125-127

.. code-block:: Python

    sensitivityAnalysis = ot.SaltelliSensitivityAlgorithm(inputDesign, outputDesign, size)








.. GENERATED FROM PYTHON SOURCE LINES 128-129

The `getFirstOrderIndices` and `getTotalOrderIndices` method respectively return estimates of all first order and total Sobol' indices.

.. GENERATED FROM PYTHON SOURCE LINES 131-133

.. code-block:: Python

    sensitivityAnalysis.getFirstOrderIndices()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    class=Point name=Unnamed dimension=3 values=[0.240497,0.42218,-0.0275219]
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 134-136

.. code-block:: Python

    sensitivityAnalysis.getTotalOrderIndices()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    class=Point name=Unnamed dimension=3 values=[0.590134,0.424195,0.269467]
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 137-138

The `draw` method produces the following graph. The vertical bars represent the 95% confidence intervals of the estimates.

.. GENERATED FROM PYTHON SOURCE LINES 140-143

.. code-block:: Python

    graph = sensitivityAnalysis.draw()
    view = viewer.View(graph)




.. image-sg:: /auto_reliability_sensitivity/sensitivity_analysis/images/sphx_glr_plot_sensitivity_sobol_003.png
   :alt: Sobol' indices - SaltelliSensitivityAlgorithm
   :srcset: /auto_reliability_sensitivity/sensitivity_analysis/images/sphx_glr_plot_sensitivity_sobol_003.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 144-155

- We see that the variable :math:`X_1`, with a total Sobol' index close
  to 0.6, is the most significant variable, taking into account both its direct
  effect and its interactions with other variables.
  Its first order index is close to 0.3, which implies that its interactions
  alone produce almost 30% (0.6 - 0.3) of the total variance.
- The variable :math:`X_2` has the highest first order index: approximately 0.4.
  However, it has little interaction with other variables since its total order indice is close to its first order index.
- The variable :math:`X_3` has a first order index close to zero.
  However, it has an impact to the total variance thanks to its interactions with :math:`X_1`.
- We see that the variability of the estimates is quite high even with a relatively large sample size.
  Moreover, since the exact first order Sobol' index for :math:`X_3` is zero, its estimate has a 50% chance of being nonpositive.

.. GENERATED FROM PYTHON SOURCE LINES 157-159

Estimate the second order indices
---------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 161-169

.. code-block:: Python

    size = 1000
    computeSecondOrder = True
    sie = ot.SobolIndicesExperiment(im.distributionX, size, computeSecondOrder)
    inputDesign = sie.generate()
    print(inputDesign.getSize())
    inputDesign.setDescription(input_names)
    outputDesign = im.model(inputDesign)





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

 .. code-block:: none

    8000




.. GENERATED FROM PYTHON SOURCE LINES 170-171

We see that 8000 function evaluations are now required; that is 3000 more evaluations than in the previous situation.

.. GENERATED FROM PYTHON SOURCE LINES 173-175

.. code-block:: Python

    sensitivityAnalysis = ot.SaltelliSensitivityAlgorithm(inputDesign, outputDesign, size)








.. GENERATED FROM PYTHON SOURCE LINES 176-181

.. code-block:: Python

    second_order = sensitivityAnalysis.getSecondOrderIndices()
    for i in range(im.dim):
        for j in range(i):
            print("2nd order indice (%d,%d)=%g" % (i, j, second_order[i, j]))





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

 .. code-block:: none

    2nd order indice (1,0)=0.097439
    2nd order indice (2,0)=0.353784
    2nd order indice (2,1)=0.121106




.. GENERATED FROM PYTHON SOURCE LINES 182-183

This shows that the only significant interaction is the one between :math:`X_1` and :math:`X_3` (beware of Python's index shift: 0 denotes the first input variable).

.. GENERATED FROM PYTHON SOURCE LINES 185-195

Using a different estimator
---------------------------

We have used the `SaltelliSensitivityAlgorithm` class to estimate the indices. Others are available in the library:

* `SaltelliSensitivityAlgorithm`
* `MartinezSensitivityAlgorithm`
* `JansenSensitivityAlgorithm`
* `MauntzKucherenkoSensitivityAlgorithm`


.. GENERATED FROM PYTHON SOURCE LINES 197-198

In order to compare the results with another method, we use the `MartinezSensitivityAlgorithm` class.

.. GENERATED FROM PYTHON SOURCE LINES 200-202

.. code-block:: Python

    sensitivityAnalysis = ot.MartinezSensitivityAlgorithm(inputDesign, outputDesign, size)








.. GENERATED FROM PYTHON SOURCE LINES 203-207

.. code-block:: Python

    graph = sensitivityAnalysis.draw()
    view = viewer.View(graph)

    plt.show()



.. image-sg:: /auto_reliability_sensitivity/sensitivity_analysis/images/sphx_glr_plot_sensitivity_sobol_004.png
   :alt: Sobol' indices - MartinezSensitivityAlgorithm
   :srcset: /auto_reliability_sensitivity/sensitivity_analysis/images/sphx_glr_plot_sensitivity_sobol_004.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 208-209

We see that the results do not change significantly in this particular situation.


.. _sphx_glr_download_auto_reliability_sensitivity_sensitivity_analysis_plot_sensitivity_sobol.py:

.. only:: html

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

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

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

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

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