From 5de396e2efbeffd97c0f000be6e126bca16fc6c7 Mon Sep 17 00:00:00 2001 From: Prateek Bhustali Date: Sun, 8 May 2022 14:22:13 +0200 Subject: [PATCH] Added documentation for Sobol indices --- docs/code/sensitivity/sobol/README.rst | 24 ++++++++ docs/source/sensitivity/index.rst | 5 +- docs/source/sensitivity/sobol.rst | 79 ++++++++++++++++++++++++++ 3 files changed, 106 insertions(+), 2 deletions(-) create mode 100644 docs/code/sensitivity/sobol/README.rst create mode 100644 docs/source/sensitivity/sobol.rst diff --git a/docs/code/sensitivity/sobol/README.rst b/docs/code/sensitivity/sobol/README.rst new file mode 100644 index 000000000..1be801c21 --- /dev/null +++ b/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. diff --git a/docs/source/sensitivity/index.rst b/docs/source/sensitivity/index.rst index 8fbf6b391..0e5fef5c0 100644 --- a/docs/source/sensitivity/index.rst +++ b/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 - Polynomial Chaos Sensitivity \ No newline at end of file + Polynomial Chaos Sensitivity + Sobol Sensitivity diff --git a/docs/source/sensitivity/sobol.rst b/docs/source/sensitivity/sobol.rst new file mode 100644 index 000000000..1966330c1 --- /dev/null +++ b/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>