.. only:: html

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

        Click :ref:`here <sphx_glr_download_auto_reliability_sensitivity_sensitivity_analysis_plot_sensitivity_ancova.py>`     to download the full example code
    .. rst-class:: sphx-glr-example-title

    .. _sphx_glr_auto_reliability_sensitivity_sensitivity_analysis_plot_sensitivity_ancova.py:


ANCOVA sensitivity indices
==========================

In this example we are going to use the ANCOVA decomposition to estimate sensitivity indices from a model with correlated inputs.

ANCOVA allows to estimate the Sobol' indices, and thanks to a functional decomposition of the model it allows to separate the part of variance explained by a variable itself from the part of variance explained by a correlation which is due to its correlation with the other input parameters.


In theory, ANCOVA indices range is :math:`\left[0; 1\right]` ; the closer to 1 the index is,
the greater the model response sensitivity to the variable is.
These indices are a sum of a physical part :math:`S_i^U` and correlated part :math:`S_i^C`.
The correlation has a weak influence on the contribution of :math:`X_i`, if :math:`|S_i^C|`
is low and :math:`S_i` is close to :math:`S_i^U`.
On the contrary, the correlation has a strong influence on the contribution of
the input :math:`X_i`, if :math:`|S_i^C|` is high and :math:`S_i` is close to :math:`S_i^C`.

The ANCOVA indices :math:`S_i` evaluate the importance of one variable at a time
(:math:`d` indices stored, with :math:`d` the input dimension of the model).
The :math:`d` uncorrelated parts of variance of the output due to each input :math:`S_i^U`
and the effects of the correlation are represented by the indices resulting
from the subtraction of these two previous lists.

To evaluate the indices, the library needs of a functional chaos result
approximating the model response with uncorrelated inputs and a sample with
correlated inputs used to compute the real values of the output.



.. code-block:: default

    from __future__ import print_function
    import openturns as ot
    import openturns.viewer as viewer
    from matplotlib import pylab as plt
    ot.Log.Show(ot.Log.NONE)








Create the model (x1,x2) --> (y) = (4.*x1+5.*x2)


.. code-block:: default

    model = ot.SymbolicFunction(['x1', 'x2'], ['4.*x1+5.*x2'])








Create the input independent joint distribution


.. code-block:: default

    distribution = ot.Normal(2)
    distribution.setDescription(['X1', 'X2'])








Create the correlated input distribution


.. code-block:: default

    S = ot.CorrelationMatrix(2)
    S[1, 0] = 0.3
    R = ot.NormalCopula.GetCorrelationFromSpearmanCorrelation(S)
    copula = ot.NormalCopula(R)
    distribution_corr = ot.ComposedDistribution([ot.Normal()] * 2, copula)








ANCOVA needs a functional decomposition of the model


.. code-block:: default

    enumerateFunction = ot.LinearEnumerateFunction(2)
    productBasis = ot.OrthogonalProductPolynomialFactory([ot.HermiteFactory()]*2, enumerateFunction)
    adaptiveStrategy = ot.FixedStrategy(productBasis, enumerateFunction.getStrataCumulatedCardinal(4))
    samplingSize = 250
    projectionStrategy = ot.LeastSquaresStrategy(ot.MonteCarloExperiment(samplingSize))
    algo = ot.FunctionalChaosAlgorithm(model, distribution, adaptiveStrategy, projectionStrategy)
    algo.run()
    result = ot.FunctionalChaosResult(algo.getResult())








Create the input sample taking account the correlation


.. code-block:: default

    size = 2000
    sample = distribution_corr.getSample(size)








Perform the decomposition


.. code-block:: default

    ancova = ot.ANCOVA(result, sample)
    # Compute the ANCOVA indices (first order and uncorrelated indices are computed together)
    indices = ancova.getIndices()
    # Retrieve uncorrelated indices
    uncorrelatedIndices = ancova.getUncorrelatedIndices()
    # Retrieve correlated indices:
    correlatedIndices = indices - uncorrelatedIndices








Print Sobol' indices, the physical part, and the correlation part


.. code-block:: default

    print("ANCOVA indices ", indices)
    print("ANCOVA uncorrelated indices ", uncorrelatedIndices)
    print("ANCOVA correlated indices ", correlatedIndices)





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

 Out:

 .. code-block:: none

    ANCOVA indices  [0.415068,0.584932]
    ANCOVA uncorrelated indices  [0.297552,0.467416]
    ANCOVA correlated indices  [0.117516,0.117516]





.. code-block:: default

    graph = ot.SobolIndicesAlgorithm.DrawImportanceFactors(indices, distribution.getDescription(), 'ANCOVA indices (Sobol\')')
    view = viewer.View(graph)




.. image:: /auto_reliability_sensitivity/sensitivity_analysis/images/sphx_glr_plot_sensitivity_ancova_001.png
    :alt: ANCOVA indices (Sobol')
    :class: sphx-glr-single-img






.. code-block:: default

    graph = ot.SobolIndicesAlgorithm.DrawImportanceFactors(uncorrelatedIndices, distribution.getDescription(), 'ANCOVA uncorrelated indices\n(part of physical variance in the model)')
    view = viewer.View(graph)




.. image:: /auto_reliability_sensitivity/sensitivity_analysis/images/sphx_glr_plot_sensitivity_ancova_002.png
    :alt: ANCOVA uncorrelated indices (part of physical variance in the model)
    :class: sphx-glr-single-img






.. code-block:: default

    graph = ot.SobolIndicesAlgorithm.DrawImportanceFactors(correlatedIndices, distribution.getDescription(), 'ANCOVA correlated indices\n(part of variance due to the correlation)')
    view = viewer.View(graph)
    plt.show()



.. image:: /auto_reliability_sensitivity/sensitivity_analysis/images/sphx_glr_plot_sensitivity_ancova_003.png
    :alt: ANCOVA correlated indices (part of variance due to the correlation)
    :class: sphx-glr-single-img






.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  0.130 seconds)


.. _sphx_glr_download_auto_reliability_sensitivity_sensitivity_analysis_plot_sensitivity_ancova.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_sensitivity_ancova.py <plot_sensitivity_ancova.py>`



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

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


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_