.. 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_simulationalgorithm.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_simulationalgorithm.py>`
        to download the full example code.

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

.. _sphx_glr_auto_reliability_sensitivity_sensitivity_analysis_plot_sensitivity_sobol_simulationalgorithm.py:


Estimate Sobol' indices for the beam by simulation algorithm
============================================================

.. GENERATED FROM PYTHON SOURCE LINES 7-10

In this example, we estimate the Sobol' indices for the
:ref:`cantilever beam <use-case-cantilever-beam>` by simulation algorithm.


.. GENERATED FROM PYTHON SOURCE LINES 13-52

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 54-56

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

.. GENERATED FROM PYTHON SOURCE LINES 58-64

.. code-block:: Python

    from openturns.usecases import cantilever_beam
    import openturns as ot
    import openturns.viewer as otv

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








.. GENERATED FROM PYTHON SOURCE LINES 65-66

We load the distribution and model from the example:

.. GENERATED FROM PYTHON SOURCE LINES 66-70

.. code-block:: Python

    beam = cantilever_beam.CantileverBeam()
    distribution = beam.independentDistribution
    model = beam.model








.. GENERATED FROM PYTHON SOURCE LINES 71-73

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

.. GENERATED FROM PYTHON SOURCE LINES 75-77

We first create the algorithm from `SobolSimulationAlgorithm` with the Saltelli estimator
it will allow one to control the number of evaluations by convergence instead of using a fixed-size experiment

.. GENERATED FROM PYTHON SOURCE LINES 77-87

.. code-block:: Python

    estimator = ot.SaltelliSensitivityAlgorithm()
    estimator.setUseAsymptoticDistribution(True)
    algo = ot.SobolSimulationAlgorithm(distribution, model, estimator)
    algo.setMaximumOuterSampling(50)  # number of iterations
    algo.setExperimentSize(1000)  # size of Sobol experiment at each iteration
    algo.setBlockSize(4)  # number of points evaluated simultaneously
    # algo.setIndexQuantileLevel(0.05)  # alpha
    # algo.setIndexQuantileEpsilon(1e-2)  # epsilon
    algo.run()








.. GENERATED FROM PYTHON SOURCE LINES 88-90

Extract the results
-------------------

.. GENERATED FROM PYTHON SOURCE LINES 90-97

.. code-block:: Python

    result = algo.getResult()
    fo = result.getFirstOrderIndicesEstimate()
    to = result.getTotalOrderIndicesEstimate()
    foDist = result.getFirstOrderIndicesDistribution()
    graph = result.draw()
    _ = otv.View(graph)




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





.. GENERATED FROM PYTHON SOURCE LINES 98-109

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 111-112

.. code-block:: Python

    otv.View.ShowAll()








.. _sphx_glr_download_auto_reliability_sensitivity_sensitivity_analysis_plot_sensitivity_sobol_simulationalgorithm.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_simulationalgorithm.ipynb <plot_sensitivity_sobol_simulationalgorithm.ipynb>`

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

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

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

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