%define OT_SobolIndicesAlgorithm_doc
"
Sensitivity analysis.

Notes
-----
This method is concerned with analyzing the influence the random vector
:math:`\vect{X} = \left( X^1, \ldots, X^{n_X} \right)` has on a random variable
:math:`Y^k` which is being studied for uncertainty (see also [Sobol1993]_).

Here we attempt to evaluate the part of variance of :math:`Y^k` due to the different components :math:`X^i`.

We denote G the physical model such as :math:`\vect{Y}=G(\vect{X})`. Let us consider first the case where :math:`\vect{Y}` is of dimension 1.

The objective here is to develop the variability of the random variable :math:`\vect{Y}` as function of :math:`\vect{X} = \left( X^1, \ldots, X^{n_X} \right)`. Using the Hoeffding decomposition, we got:

.. math::

   \Var{\vect{Y}} = \sum_{i=1}^{n_X} V_i + \sum_{i<j} V_{i,j} + \sum_{i<k<j} V_{i,j,k} + \cdots + V_{1,2,..,n_X}

where :

:math:`V_i = \Var{\Expect{ Y \vert X_i}}` and :math:`V_{i,j} = \Var{\Expect{ Y \vert X_i, X_j}} - V_i - V_j`. Using the previous decomposition, it follows that sensitivity indices are defined as follow:


.. math::

   \begin{array}{ccc}
    S_i & = & \frac{V_i}{\Var{\vect{Y}}} \\
    S_{i,j} & = & \frac{V_{i,j}}{\Var{\vect{Y}}}
   \end{array}

:math:`(S_i)` are the first order sensitivity indices and measure the impact of :math:`X_i` in the variance :math:`\Var{\vect{Y}}`,
:math:`(S_{i,j})` are the second order sensitivity indices and measure the impact of the interaction of :math:`X_i` and :math:`X_j` in the variance :math:`\Var{\vect{Y}}`.

When :math:`n_X >> 1`, we use total sensitivity indices :math:`ST_i`, which is defined as the sum of all indices that count the i-th variable:

.. math::

    ST_i =  1 - \frac{V_{-i}}{\Var{\vect{Y}}} = \frac{VT_i}{\Var{\vect{Y}}}, \forall\ i\in(1,2,...,n_X)

where :math:`V_{-i}` is the part of variance of :math:`\Var{\vect{Y}}` that do not countain the i-th variable.

|

In practice, to estimate these quantities, Sobol proposes to use numerical methods that rely on the two independent realizations of the random vector :math:`\vect{X}`.
If we consider `A` and `B` two independent samples (of size `n`) of the previous random vector:

.. math::

   A = \left(
   \begin{array}{cccc}
   a_{1,1} & a_{1,2} & \cdots & a_{1, n_X} \\
   a_{2,1} & a_{2,2} & \cdots & a_{2, n_X} \\
   \vdots  & \vdots  & \ddots  & \vdots \\
   a_{n,1} & a_{1,2} & \cdots & a_{n, n_X}
   \end{array}
   \right), \  B = \left(
   \begin{array}{cccc}
   b_{1,1} & b_{1,2} & \cdots & b_{1, n_X} \\
   b_{2,1} & b_{2,2} & \cdots & b_{2, n_X} \\
   \vdots  & \vdots  & \vdots  & \vdots \\
   b_{n,1} & b_{1,2} & \cdots & b_{n, n_X}
   \end{array}
   \right)


Each line is a realization of the random vector. The purpose is to mix these two samples to get an estimate of the sensitivities.

`Sobol` method require respectively :math:`C^i` and :math:`D^{i,j}` sample designs for the evaluation of first order (respectively second order) sensitivity indices. These are defined as hereafter:

.. math::

   C^i = \left(
   \begin{array}{ccccc}
   b_{1,1} & b_{1,2} & a_{1,i} & \cdots & b_{1, n_X} \\
   b_{2,1} & b_{2,2} & a_{2,i} & \cdots & b_{2, n_X} \\
   \vdots  & \vdots  & \vdots  & \ddots  & \vdots \\
   b_{n,1} & b_{1,2} & a_{n,i} & \cdots & b_{n, n_X}
   \end{array}
   \right), \ D^{i,j} = \left(
   \begin{array}{ccccccc}
   b_{1,1} & b_{1,2} & a_{1,i} & \cdots & a_{1,j} & \cdots & b_{1, n_X} \\
   b_{2,1} & b_{2,2} & a_{2,i} & \cdots & a_{2,j} & \cdots & b_{2, n_X} \\
   \vdots  & \vdots  & \vdots  & \vdots & \vdots  & \ddots & \vdots \\
   b_{n,1} & b_{n,2} & a_{n,i} & \cdots & a_{n,j} & \cdots & b_{n, n_X} \\
   \end{array}
   \right)

It follows that :math:`V_{i}` and :math:`V_{i,j}` terms are defined as follow:

.. math::

   \begin{array}{ccc}
    V_i & = & \frac{1}{n} \sum_{k=1}^{n} G(A_k) G(C_k) - V_i - V_j - G_0^2 \\
    V_{i,j} & = & \frac{1}{n} \sum_{k=1}^{n} G(A_k) G(D_k) - G_0^2 \\
    G_0 & = & \frac{1}{n} \sum_{k=1}^{n} G(A_k)
   \end{array}

The implemented second order indices use this formula.

The major methods (`Saltelli`, `Jansen`, `Mauntz-Kucherenko`, `Martinez`) use the :math:`E^i` matrix to compute the indices (first order and total order). This matrix is defined as follows:

.. math::

   E^i = \left(
   \begin{array}{ccccc}
   a_{1,1} & a_{1,2} & b_{1,i} & \cdots & a_{1, n_X} \\
   a_{2,1} & a_{2,2} & b_{2,i} & \cdots & a_{2, n_X} \\
   \vdots  & \vdots  & \vdots  & \ddots  & \vdots \\
   a_{n,1} & a_{1,2} & b_{n,i} & \cdots & a_{n, n_X}
   \end{array}
   \right)

The formulas for the evaluation of the indices are given in each class documentation:
  - :class:`~openturns.SaltelliSensitivityAlgorithm` for the `Saltelli` method,
  - :class:`~openturns.JansenSensitivityAlgorithm` for the `Jansen` method,
  - :class:`~openturns.MauntzKucherenkoSensitivityAlgorithm` for the `Mauntz-Kucherenko` method,
  - :class:`~openturns.MartinezSensitivityAlgorithm` for the `Martinez` method

For multivariate outputs (see [Gamboa2013]_), aggregate indices can be computed thanks to the `getAggregatedFirstOrderIndices` and `getAggregatedTotalOrderIndices`. Such indices write as follow:


.. math::

   \begin{array}{ccc}
    S_i & = & \frac{ \sum_{k=1}^{q} V_{i}^{(k)} }{ \sum_{k=1}^{q} \Var{Y_k} }  \\
    S_{i,j} & = & \frac{ \sum_{k=1}^{q} V_{i,j}^{(k)} }{ \sum_{k=1}^{q} \Var{Y_k} }  \\
    ST_i & = & \frac{ \sum_{k=1}^{q} VT_{i}^{(k)} }{ \sum_{k=1}^{q} \Var{Y_k} }
   \end{array}

Aggregated second order indices have not been implemented.

|

Note finally that evaluation of intervals for indices might be done for first and total order thanks to
the `getFirstOrderIndicesInterval` and `getTotalOrderIndicesInterval` methods. Default bootstrap size 
and confidence level values are parametrized thanks to the resource map keys `SobolIndicesAlgorithm-BootstrapSize`
and `SobolIndicesAlgorithm-BootstrapConfidenceLevel`. Appropriate setters
might be called to change their values.

Also note that for numerical stability reasons the ouputs are centered before indices estimation:

.. math::

    Y_k = Y_k - \Eset(Y_k)
"
%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation
OT_SobolIndicesAlgorithm_doc

// ---------------------------------------------------------------------

%define OT_SobolIndicesAlgorithm_getFirstOrderIndices_doc
"Get first order Sobol indices.

Parameters
----------
i : int, optional
    Index of the marginal of the function, equals to :math:`0` by default.

Returns
-------
indices : :class:`~openturns.Point`
    Sequence containing first order Sobol indices."
%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation::getFirstOrderIndices
OT_SobolIndicesAlgorithm_getFirstOrderIndices_doc

// ---------------------------------------------------------------------

%define OT_SobolIndicesAlgorithm_getFirstOrderIndicesInterval_doc
"Get interval for the merged first order Sobol indices.

Returns
-------
interval : :class:`~openturns.Interval`
    Interval for first order Sobol indices for each component."
%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation::getFirstOrderIndicesInterval
OT_SobolIndicesAlgorithm_getFirstOrderIndicesInterval_doc

// ---------------------------------------------------------------------

%define OT_SobolIndicesAlgorithm_getAggregatedFirstOrderIndices_doc
"Get the evaluation of merged first order Sobol indices.

Returns
-------
indices : :class:`~openturns.Point`
    Sequence containing merged first order Sobol indices."
%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation::getAggregatedFirstOrderIndices
OT_SobolIndicesAlgorithm_getAggregatedFirstOrderIndices_doc

// ---------------------------------------------------------------------

%define OT_SobolIndicesAlgorithm_getAggregatedTotalOrderIndices_doc
"Get the evaluation of merged total order Sobol indices.

Returns
-------
indices : :class:`~openturns.Point`
    Sequence containing merged total order Sobol indices."

%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation::getAggregatedTotalOrderIndices
OT_SobolIndicesAlgorithm_getAggregatedTotalOrderIndices_doc

// ---------------------------------------------------------------------

%define OT_SobolIndicesAlgorithm_getSecondOrderIndices_doc
"Get second order Sobol indices.

Parameters
----------
i : int, optional
    Index of the marginal of the function, equals to :math:`0` by default.

Returns
-------
indices : :class:`~openturns.SymmetricMatrix`
    Tensor containing second order Sobol indices."
%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation::getSecondOrderIndices
OT_SobolIndicesAlgorithm_getSecondOrderIndices_doc

// ---------------------------------------------------------------------

%define OT_SobolIndicesAlgorithm_getTotalOrderIndices_doc
"Get total order Sobol indices.

Parameters
----------
i : int, optional
    Index of the marginal of the function, equals to :math:`0` by default.

Returns
-------
indices : :class:`~openturns.Point`
    Sequence containing total order Sobol indices."

%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation::getTotalOrderIndices
OT_SobolIndicesAlgorithm_getTotalOrderIndices_doc

// ---------------------------------------------------------------------

%define OT_SobolIndicesAlgorithm_getTotalOrderIndicesInterval_doc
"Get interval for the merged total order Sobol indices.

Returns
-------
interval : :class:`~openturns.Interval`
    Interval for total order Sobol indices for each component."
%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation::getTotalOrderIndicesInterval
OT_SobolIndicesAlgorithm_getTotalOrderIndicesInterval_doc

// ---------------------------------------------------------------------

%define OT_SobolIndicesAlgorithm_getBootstrapConfidenceLevel_doc
"Get the confidence interval level for bootstrap sampling.

Returns
-------
confidenceLevel : float
    Confidence level for boostrap sampling"
%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation::getBootstrapConfidenceLevel
OT_SobolIndicesAlgorithm_getBootstrapConfidenceLevel_doc

// ---------------------------------------------------------------------

%define OT_SobolIndicesAlgorithm_setBootstrapConfidenceLevel_doc
"Set the confidence interval level for bootstrap sampling.

Parameters
----------
confidenceLevel : float
    Confidence level for boostrap sampling"
%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation::setBootstrapConfidenceLevel
OT_SobolIndicesAlgorithm_setBootstrapConfidenceLevel_doc

// ---------------------------------------------------------------------

%define OT_SobolIndicesAlgorithm_getBootstrapSize_doc
"Get the number of bootstrap sampling size.

Returns
-------
bootstrapSize : int
    Number of bootsrap sampling"
%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation::getBootstrapSize
OT_SobolIndicesAlgorithm_getBootstrapSize_doc

// ---------------------------------------------------------------------

%define OT_SobolIndicesAlgorithm_setBootstrapSize_doc
"Set the number of bootstrap sampling size.

Default value is 0.

Parameters
----------
bootstrapSize : int
    Number of bootsrap sampling"
%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation::setBootstrapSize
OT_SobolIndicesAlgorithm_setBootstrapSize_doc

// ---------------------------------------------------------------------
%define OT_SobolIndicesAlgorithm_draw_doc
"Draw sensitivity indices.

Usage:
  draw()

  draw(*marginalIndex*)

With the first usage, draw the aggregated first and total order indices.
With the second usage, draw the first and total order indices of a specific marginal in case of vectorial output

Parameters
----------
marginalIndex: int
    marginal of interest (case of second usage)

Returns
-------
Graph : :class:`~openturns.Graph`
    A graph containing the aggregated first and total order indices.

Notes
-----
If number of bootstrap sampling is not 0, and confidence level associated > 0,
the graph includes confidence interval plots in the first usage."
%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation::draw
OT_SobolIndicesAlgorithm_draw_doc

// ---------------------------------------------------------------------
%define OT_SobolIndicesAlgorithm_DrawImportanceFactors_doc

"Draw the importance factors.

:Available usages:
    DrawImportanceFactors(*importanceFactors, title='Importance Factors'*)

    DrawImportanceFactors(*values, names, title='Importance Factors'*)

Parameters
----------
importanceFactors : :class:`~openturns.PointWithDescription`
    Sequence containing the importance factors with a description for each
    component. The descriptions are used to build labels for the created Pie.
    If they are not mentioned, default labels will be used.
values : sequence of float
    Importance factors.
names : sequence of str
    Variables' names used to build labels for the created Pie.
title : str
    Title of the graph.

Returns
-------
Graph : :class:`~openturns.Graph`
    A graph containing a :class:`~openturns.Pie` of the importance factors of
    the variables."
%enddef
%feature("docstring") OT::SobolIndicesAlgorithmImplementation::DrawImportanceFactors
OT_SobolIndicesAlgorithm_DrawImportanceFactors_doc
// ---------------------------------------------------------------------
