From 27305fc4ecb3a9342892bc0b88446cf77f970979 Mon Sep 17 00:00:00 2001 From: Prateek Bhustali Date: Sun, 8 May 2022 20:39:59 +0200 Subject: [PATCH] =?UTF-8?q?Added=20documentation=20Cram=C3=A9r-von=20Mises?= =?UTF-8?q?=20sensitivity?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../sensitivity/cramer_von_mises/README.rst | 3 + docs/source/sensitivity/cramer_von_mises.rst | 61 +++++++++++++++++++ docs/source/sensitivity/index.rst | 2 + 3 files changed, 66 insertions(+) create mode 100644 docs/code/sensitivity/cramer_von_mises/README.rst create mode 100644 docs/source/sensitivity/cramer_von_mises.rst diff --git a/docs/code/sensitivity/cramer_von_mises/README.rst b/docs/code/sensitivity/cramer_von_mises/README.rst new file mode 100644 index 00000000..ea5f804b --- /dev/null +++ b/docs/code/sensitivity/cramer_von_mises/README.rst @@ -0,0 +1,3 @@ +Cramér-von Mises Sensitivity indices +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + diff --git a/docs/source/sensitivity/cramer_von_mises.rst b/docs/source/sensitivity/cramer_von_mises.rst new file mode 100644 index 00000000..0c748bbb --- /dev/null +++ b/docs/source/sensitivity/cramer_von_mises.rst @@ -0,0 +1,61 @@ +Cramér-von Mises indices +---------------------------------------- + +A sensitivity index based on the Cramér-von Mises distance. In contrast to variance based Sobol indices it takes into account the whole distribution of the model output and is therefore considered as a moment-free method [5]_. Furthermore the index can be naturally extended to multivariate model outputs (not implemented yet in UQPy). + +Consider a model :math:`Y=f(X): \mathbb{R}^d \rightarrow \mathbb{R}^k` with :math:`d` inputs :math:`X_{(1)}, X_{(2)}, \ldots, X_{(d)}` and :math:`k` outputs :math:`Y_{(1)}, Y_{(2)}, \ldots, Y_{(k)}`. We define the cumulative distribution function :math:`F(t)` of :math:`Y` as: + +.. math:: + + F(t)=\mathbb{P}(Z \leqslant t)=\mathbb{E}\left[\mathbb{1}_{\{Z \leqslant t\}}\right] \text { for } t=\left(t_{1}, \ldots, t_{k}\right) \in \mathbb{R}^{k} + +and the conditional distribution function :math:`F(t)` of :math:`Y` as: + +.. math:: + + F^{v}(t)=\mathbb{P}\left(Z \leqslant t \mid X_{v}\right)=\mathbb{E}\left[\mathbb{1}_{\{Z \leqslant t\}} \mid X_{v}\right] \text { for } t=\left(t_{1}, \ldots, t_{k}\right) \in \mathbb{R}^{k} + +where, :math:`\{Z \leqslant t\} \text { means that } \left\{Z_{1} \leqslant t_{1}, \ldots, Z_{k} \leqslant t_{k}\right\}`. + +The first order Cramér-von Mises index :math:`S_{2, C V M}^{i}` (for input :math:`v = {i}`) is defined as: + +.. math:: + + S_{2, C V M}^{i}:=\frac{\int_{\mathbb{R}^{k}} \mathbb{E}\left[\left(F(t)-F^{i}(t)\right)^{2}\right] d F(t)}{\int_{\mathbb{R}^{k}} F(t)(1-F(t)) d F(t)} + +and the total Cramér-von Mises index :math:`S_{2, C V M}^{T o t, i}` (for input :math:`v = {i}`) is defined as: + +.. math:: + + S_{2, C V M}^{T o t, i}:=1-S_{2, C V M}^{\sim i}=1-\frac{\int_{\mathbb{R}^{k}} \mathbb{E}\left[\left(F(t)-F^{\sim i}(t)\right)^{2}\right] d F(t)}{\int_{\mathbb{R}^{k}} F(t)(1-F(t)) d F(t)} + +The above first and total order indices are estimated using the Pick-and-Freeze approach. This requires :math:`N(d+2)` model evaluations, where :math:`N` is the number of samples. (For implementation details, see also [6]_.) + +Cramér-von Mises Class +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The :class:`Cramér-von Mises` class is imported using the following command: + +>>> from UQpy.sensitivity.cramer_von_mises import CramerVonMises + +Methods +""""""" +.. autoclass:: UQpy.sensitivity.CramervonMises + :members: run + +Attributes +"""""""""" +.. autoattribute:: UQpy.sensitivity.CramervonMises.CVM_i +.. autoattribute:: UQpy.sensitivity.CramervonMises.CI_CVM_i +.. autoattribute:: UQpy.sensitivity.CramervonMises.sobol_i +.. autoattribute:: UQpy.sensitivity.CramervonMises.sobol_total_i +.. autoattribute:: UQpy.sensitivity.CramervonMises.n_samples +.. autoattribute:: UQpy.sensitivity.CramervonMises.num_vars + + +Examples +"""""""""" + +.. toctree:: + + Cramér-von Mises Examples <../auto_examples/sensitivity/cramer_von_mises/index> diff --git a/docs/source/sensitivity/index.rst b/docs/source/sensitivity/index.rst index 0e5fef5c..324fbf66 100644 --- a/docs/source/sensitivity/index.rst +++ b/docs/source/sensitivity/index.rst @@ -6,6 +6,7 @@ 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:`.CramervonMises`: Class to compute Cramér-von Mises sensitivity indices. - :py:class:`.MorrisSensitivity`: Class to perform Morris. - :py:class:`.PceSensitivity`: Class to compute the sensitivity indices using the :class:`.PolynomialChaosExpansion` method. @@ -20,3 +21,4 @@ Sensitivity analysis comprises techniques focused on determining how the variati Morris Sensitivity Polynomial Chaos Sensitivity Sobol Sensitivity + Cramér-von Mises Sensitivity