Sobol indices

Sobol indices are the standard approach for performing a global 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 (\(S_{i}\)): Describe the fraction of the output variance due to a single uncertain input parameter \(i\). 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 (\(S_{ij}\)) describe the fraction of the output variance due to interactions between two uncertain input parameters \(i\) and \(j\).

  • Total order indices (\(S_{T_{i}}\)): Describe the fraction of the output variance due to a single input parameter \(i\) and all higher order effects of the input parameter.

If the first order index of an input parameter is equal to the total order index it implies that the parameter does not have any interaction effects.

The Sobol indices are typically 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:

Here, \(N\) is the Monte Carlo sample size and \(m\) is the number of input parameters in the model.

  1. First order indices (\(S_{i}\))

  • Janon2014: Requires \(N(m + 1)\) model evaluations

\[\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}}\]
\[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 smaller (better) confidence intervals.

  • Sobol1993: Requires \(N(m + 1)\) model evaluations [41].

\[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}}\]
\[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 \(N(2m + 2)\) model evaluations [42].

  1. Second order indices (\(S_{ij}\))

  • Saltelli2002: Requires \(N(2m + 2)\) model evaluations [42].

  1. Total order indices (\(S_{T_{i}}\))

  • Homma1996: Requires \(N(m + 1)\) model evaluations [41].

\[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}}\]
\[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 \(N(2m + 2)\) model evaluations [42].

Sobol Class

The SobolSensitivity class is imported using the following command:

>>> from UQpy.sensitivity.SobolSensitivity import SobolSensitivity

Methods

class SobolSensitivity(runmodel_object, dist_object, random_state=None)[source]

Compute Sobol sensitivity indices using the pick and freeze algorithm. For models with multiple outputs (vector-valued response), the sensitivity indices are computed for each output separately. For time-series models, the sensitivity indices are computed for each time instant separately. (Pointwise-in-time Sobol indices)

Parameters:

  • runmodel_object – The computational model. It should be of type RunModel. The output QoI can be a scalar or vector of length ny, then the sensitivity indices of all ny outputs are computed independently.

  • distributions – List of Distribution objects corresponding to each random variable, or JointIndependent object (multivariate RV with independent marginals).

  • random_state – Random seed used to initialize the pseudo-random number generator. Default is None.

Methods:

run(n_samples=1000, n_bootstrap_samples=None, confidence_level=0.95, estimate_second_order=False, first_order_scheme='Janon2014', total_order_scheme='Homma1996', second_order_scheme='Saltelli2002')[source]

Compute the sensitivity indices and confidence intervals.

Parameters:

  • n_samples (int) – Number of samples used to compute the sensitivity indices. Default is 1,000.

  • n_bootstrap_samples (Optional[int]) – Number of bootstrap samples used to compute the confidence intervals. Default is None.

  • confidence_interval – Confidence level used to compute the confidence intervals. Default is 0.95.

  • estimate_second_order (bool) – If True, the second order Sobol indices are estimated. Default is False.

  • first_order_scheme (str) – Scheme used to compute the first order Sobol indices. Default is “Janon2014”.

  • total_order_scheme (str) – Scheme used to compute the total order Sobol indices. Default is “Homma1996”.

  • second_order_scheme (str) – Scheme used to compute the second order Sobol indices. Default is “Saltelli2002”.

Attributes

SobolSensitivity.first_order_indices

First order Sobol indices, numpy.ndarray of shape (n_variables, n_outputs)

SobolSensitivity.second_order_indices

Second order Sobol indices, numpy.ndarray of shape (num_second_order_terms, n_outputs)

SobolSensitivity.total_order_indices

Total order Sobol indices, numpy.ndarray of shape (n_variables, n_outputs)

SobolSensitivity.first_order_confidence_interval

Confidence intervals for the first order Sobol indices, numpy.ndarray of shape (n_variables, 2)

SobolSensitivity.second_order_confidence_interval

Confidence intervals for the second order Sobol indices, numpy.ndarray of shape (num_second_order_terms, 2)

SobolSensitivity.total_order_confidence_interval

Confidence intervals for the total order Sobol indices, numpy.ndarray of shape (n_variables, 2)

SobolSensitivity.n_samples

Number of samples used to compute the sensitivity indices, int

SobolSensitivity.n_variables

Number of model input variables, int

SobolSensitivity.is_multi_output

True if the model has multiple outputs, bool

Examples