Added documentation for Sobol indices

docs/code/sensitivity/sobol/README.rst

@@ -0,0 +1,24 @@
+Sobol Sensitivity indices
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These examples serve as a guide for using the Sobol sensitivity module. They have been taken from various papers to enable validation of the implementation and have been referenced accordingly.
+
+Single output models
+======================
+We demonstrate the computation of the Sobol indices for models with a single output using the following examples:
+
+1. Ishigami function
+2. Exponential function
+3. Sobol function with parameters a := [0., 0.5, 3., 9., 99., 99.] : Example from [2] page 11
+
+Multiple output models
+========================
+
+We demonstrate the computation of the Sobol indices for models with multiple outputs using the following example:
+
+1. Mechanical oscillator ODE (numerical model): Example from [1] page 19
+
+
+[1] Gamboa F, Janon A, Klein T, Lagnoux A, others. Sensitivity analysis for multidimensional and functional outputs. Electronic journal of statistics 2014; 8(1): 575-603.
+
+[2] Saltelli, A. (2002). Making best use of model evaluations to compute  indices.

docs/source/sensitivity/index.rst

@@ -5,10 +5,10 @@ This module contains functionality for all the sampling methods supported in :py
 
 The module currently contains the following classes:
 
+- :py:class:`.Sobol`: Class to compute Sobol sensitivity indices.
 - :py:class:`.MorrisSensitivity`: Class to perform Morris.
 - :py:class:`.PceSensitivity`: Class to compute the sensitivity indices using the :class:`.PolynomialChaosExpansion` method.
 
-
 Sensitivity analysis comprises techniques focused on determining how the variations of input variables :math:`X=\left[ X_{1}, X_{2},…,X_{d} \right]` of a mathematical model influence the response value :math:`Y=h(X)`.
 
 
@@ -18,4 +18,5 @@ Sensitivity analysis comprises techniques focused on determining how the variati
    :caption: Sensitivity
 
     Morris Sensitivity <morris>
-    Polynomial Chaos Sensitivity <pce>
+    Polynomial Chaos Sensitivity <pce>
+    Sobol Sensitivity <sobol>

docs/source/sensitivity/sobol.rst

@@ -0,0 +1,79 @@
+
+Sobol indices
+----------------------------------------
+
+Sobol indices are the standard approach to calculate a global variance based sensitivity analysis. 
+The indices are based on a variance decomposition of the model output. Using this decomposition allows us to assign the contribution of uncertain inputs to the variance of the model output.
+
+There are three main groups of indices:
+
+- First order indices (:math:`S_{i}`): Describe the fraction of the output variance due to a single uncertain input parameter. This amount of variance can be reduced if the uncertainty in the corresponding input is eliminated.
+
+- Higher order indices: Describe the fraction of the output variance due to interactions between uncertain input parameters. For example, the second order indices (:math:`S_{ij}`) describe the fraction of the output variance due to interactions between two uncertain input parameters :math:`i` and :math:`j`.
+
+- Total order indices (:math:`S_{T_{i}}`): Describe the fraction of the output variance due to a single input parameter and all higher order effects the input parameter is involved.
+
+If the first order index of an input parameter is equal to the total order index it implies that the parameter is not involved in any interaction effects. 
+
+The Sobol indices are computed using the Pick-and-Freeze approach for single output and multi-output models. Since there are several variants of the Pick-and-Freeze approach, the schemes implemented to compute Sobol indices are listed below:
+
+(where, :math:`N` is the number of Monte Carlo samples and :math:`m` being the number of input parameters in the model)
+
+1. **First order indices** (:math:`S_{i}`)
+
+- Janon2014: Requires :math:`N(m + 1)` model evaluations
+
+.. math:: 
+   \frac{\mathbb{V}\left[E\left(Y \mid X_{i}\right)\right]}{\mathbb{V}(Y)} = \frac{\operatorname{Cov}\left(Y, Y_{C_{i}}\right)}{\mathbb{V}(Y)} = \frac{ (1 / N) Y_{A} \cdot Y_{C_{i}}-f_{0}^{2}}{ (1 / N)\frac{Y_{A} \cdot Y_{A} + Y_{C_{i}} \cdot Y_{C_{i}}}{2}-f_{0}^{2}}
+
+.. math:: 
+   y_{A}=f(A), \quad y_{C_{i}}=f(C_{i}), \quad f_{0}^{2}=\left(\frac{1}{2N} \sum_{j=1}^{N} y_{A}^{(j)} + y_{C_{i}}^{(j)} \right)^{2}
+
+Compared to "Sobol1993", the "Janon2014" estimator makes more efficient use of model evaluations and produces better smaller confidence intervals.
+
+- Sobol1993: Requires :math:`N(m + 1)` model evaluations [2]_.
+
+.. math::
+   S_{i} = \frac{\mathbb{V}\left[E\left(Y \mid X_{i}\right)\right]}{\mathbb{V}(Y)} = \frac{ (1/N) Y_{A} \cdot Y_{C_{i}}-f_{0}^{2}}{(1 / N) Y_{A} \cdot Y_{A}-f_{0}^{2}}
+
+.. math:: 
+   y_{A}=f(A), \quad y_{C_{i}}=f(C_{i}), \quad f_{0}^{2}=\left(\frac{1}{N} \sum_{j=1}^{N} y_{A}^{(j)} \right)^{2}
+
+- Saltelli2002: Requires :math:`N(2m + 2)` model evaluations [4]_.
+
+2. **Second order indices** (:math:`S_{ij}`)
+
+- Saltelli2002: Requires :math:`N(2m + 2)` model evaluations [4]_.
+
+3. **Total order indices** (:math:`S_{T_{i}}`)
+
+- Homma1996: Requires :math:`N(m + 1)` model evaluations [2]_.
+
+.. math:: 
+   S_{T_{i}} = 1 - \frac{\mathbb{V}\left[E\left(Y \mid \mathbf{X}_{\sim_{i}}\right)\right]}{\mathbb{V}(Y)} = 1 - \frac{ (1 / N) Y_{B} \cdot Y_{C_{i}}-f_{0}^{2}}{(1 / N) Y_{A} \cdot Y_{A}-f_{0}^{2}}
+
+.. math:: 
+   y_{A}=f(A), \quad y_{B}=f(B), \quad y_{C_{i}}=f(C_{i}), \quad f_{0}^{2}=\left(\frac{1}{2N} \sum_{j=1}^{N} y_{A}^{(j)} + y_{B}^{(j)} \right)^{2}
+
+- Saltelli2002: Requires :math:`N(2m + 2)` model evaluations [4]_.
+
+
+Sobol Class
+^^^^^^^^^^^^^^^^^^
+
+The :class:`Sobol` class is imported using the following command:
+
+>>> from UQpy.sensitivity.Sobol import Sobol
+
+Methods
+"""""""
+
+.. autoclass:: UQpy.sensitivity.Sobol
+     :members: run
+
+Examples
+""""""""""
+
+.. toctree::
+
+   Sobol Examples <../auto_examples/sensitivity/sobol/index>