SobolIndicesAlgorithm¶

class SobolIndicesAlgorithm(*args)¶

Sensitivity analysis.

Notes

This method analyzes the influence of each component of an input random vector $\vect{X} = \left( X^1, \ldots, X^{n_X} \right)$ on an output random vector $\vect{Y} = \left( Y^1, \ldots, Y^{n_Y} \right)$ by computing Sobol’ indices (see [sobol1993]). It computes, for every output random variable $Y^k$ ( $1 \leqslant k \leqslant n_Y$ ), the part of its variance due to each input component $X^i$ ( $1 \leqslant i \leqslant n_X$ ) of $\vect{X}$ .

Let $\vect{g}$ be the physical model such as $\vect{Y}=\vect{g}(\vect{X})$ . Let us first consider the case where $n_Y=1$ . In that case, we denote $\vect{Y}$ by $Y$ . Let us write the variance of $Y$ as a function of $\vect{X} = \left( X^1, \ldots, X^{n_X} \right)$ . For any subset $I \subseteq \{1, \ldots, n_X\}$ , define $\vect{X}_I = \left( X^i \right)_{i \in I}$ .

Using the Hoeffding decomposition, we get:

$\Var{Y} = \sum_{ I \subseteq \{1, \ldots, n_X\} } V_I$

where:

$V_I = \Var{ \sum_{J \subseteq I} (-1)^{ |I| - |J| } \Expect{ Y \vert \mat{X}_J} }.$

For the sake of conciseness, for any integers $1 \leqslant i, j \leqslant n_X$ , define $V_i = V_{\{i\}}$ and $V_{i,j} = V_{\{i,j\}}$ . We have:

$V_i & = \Var{ \Expect{Y \vert X_i} } \\ V_{i,j} & = \Var{ \Expect{ Y \vert X_i, X_j} - \Expect{Y \vert X_i} - \Expect{Y \vert X_j} } \\ & = \Var{ \Expect{ Y \vert X_i, X_j} } - V_i - V_j$

for $i=1,\ldots,n_X$ .

First and second order Sobol’ indices are defined as follows:

$S_i & = \frac{V_i}{\Var{Y}} \\ S_{i,j} & = \frac{V_{i,j}}{\Var{Y}}$

for $i, j = 1,\ldots,n_X$ .

The first order Sobol’ index $S_i$ measures the part of the variance of $Y$ explained by $X_i$ alone. The second order Sobol’ index $S_{i,j}$ measures the part of the variance of $Y$ explained by the interaction of $X_i$ and $X_j$ .

For any $i=1,\ldots,n_X$ , let us define

$VT_i & = \sum_{I \ni i} V_I \\ V_{-i} & = \Var{ \Expect{Y \vert X_1, \ldots, X_{i-1}, X_{i+1}, \ldots X_{n_X}} }.$

Total order Sobol’ indices are defined as follows:

$ST_i = \frac{VT_i}{\Var{Y}} = 1 - \frac{V_{-i}}{\Var{Y}}$

for $i=1,\ldots,n_X$ .

The total order Sobol’ index $ST_i$ quantifies the part of the variance of $Y$ that is due to the effect of $X_i$ and its interactions with all the other input variables. It can also be viewed as the part of the variance of $Y$ that cannot be explained without $X_i$ .

In practice, to estimate these quantities, Sobol’ proposes to use numerical methods that rely on two independent realizations of the random vector $\vect{X}$ . Let $\mat{A}$ and $\mat{B}$ be two independent samples (of size $N$ ) of $\vect{X}$ :

$\mat{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), \ \mat{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 $\vect{X}$ .

We are now going to mix these two samples to get an estimate of the sensitivity indices.

$\mat{E}^i = \left( \begin{array}{cccccc} a_{1,1} & a_{1,2} & \cdots & b_{1,i} & \cdots & a_{1, n_X} \\ a_{2,1} & a_{2,2} & \cdots & b_{2,i} & \cdots & a_{2, n_X} \\ \vdots & \vdots & & \vdots & \ddots & \vdots \\ a_{N,1} & a_{1,2} & \cdots & b_{N,i} & \cdots & a_{N, n_X} \end{array} \right), \mat{C}^i = \left( \begin{array}{cccccc} b_{1,1} & b_{1,2} & \cdots & a_{1,i} & \cdots & b_{1, n_X} \\ b_{2,1} & b_{2,2} & \cdots & a_{2,i} & \cdots & b_{2, n_X} \\ \vdots & \vdots & & \vdots & \ddots & \vdots \\ b_{N,1} & b_{1,2} & \cdots & a_{N,i} & \cdots & b_{N, n_X} \end{array} \right)$

For the sake of stability, computations will be performed with centered output. Let $\overline{\vect{g}}$ be the mean of the combined samples $\vect{g}(\mat{A})$ and $\vect{g}(\mat{B})$ . Let $\tilde{\vect{g}}$ be the empirically centered function defined, for any $\vect{x} \in \Rset^{n_X}$ , by:

$\tilde{\vect{g}}(\vect{x}) = \vect{g}(\vect{x}) - \overline{\vect{g}}.$

To estimate the total variance $\Var{Y}$ , we use the computeVariance() method of the Sample $\tilde{g}(\mat{A})$ .

Several estimators of $V_i$ , $VT_i$ and $V_{-i}$ are provided by the SobolIndicesAlgorithm implementations:

SaltelliSensitivityAlgorithm for the Saltelli method,
JansenSensitivityAlgorithm for the Jansen method,
MauntzKucherenkoSensitivityAlgorithm for the Mauntz-Kucherenko method,
MartinezSensitivityAlgorithm for the Martinez method.

Specific formulas for $\hat{V}_i$ , $\widehat{VT}_i$ and $\hat{V}_{-i}$ are given in the corresponding documentation pages.

The estimator $\hat{V}_{i,j}$ of $V_{i,j}$ is the same for all these classes:

$\hat{V}_{i,j} = \frac{1}{N-1} \sum_{k=1}^{N} \tilde{g}(\vect{E}_k^i) \tilde{g}(\vect{C}_k^j) - \frac{1}{N} \sum_{k=1}^{N} \tilde{g}(\vect{A}_k) \tilde{g}(\vect{B}_k) - \hat{V}_i - \hat{V}_j.$

Notice that the value of the second order conditional variance depends on the estimators $\hat{V}_i$ and $\hat{V}_j$ which are method-dependent. This implies that the value of the second order indices may depend on the specific Sobol’ estimator we use.

For multivariate outputs i.e. when $n_Y>1$ , we compute the Sobol’ indices with respect to each output variable. In this case, the methods getFirstOrderIndices() and getTotalOrderIndices() return the Sobol’ indices of the first output, but the index of the output can be specified as input argument. Moreover, the indices can be aggregated [gamboa2013]. Let $V_i^{(k)}$ be the (first order) variance of the conditional expectation of the k-th output $Y^{(k)}$ :

$V_i^{(k)} & = \Var{ \Expect{Y^{(k)} \vert X_i} }$

for $i=1,\ldots,n_X$ and $k=1,\ldots,n_Y$ . Similarily, let $VT_i^{(k)}$ be the total variance of the conditional expectation of $Y^{(k)}$ for $i=1,\ldots,n_X$ and $k=1,\ldots,n_Y$ .

The indices can be aggregated with the following formulas:

$S_i^{(a)} & = \frac{ \sum_{k=1}^{n_Y} V_{i}^{(k)} }{ \sum_{k=1}^{n_Y} \Var{Y_k} } \\ ST_i^{(a)} & = \frac{ \sum_{k=1}^{n_Y} VT_{i}^{(k)} }{ \sum_{k=1}^{n_Y} \Var{Y_k} }$

for $i=1,\ldots,n_X$ .

Aggregated indices can be retrieved with the getAggregatedFirstOrderIndices() and getAggregatedTotalOrderIndices() methods.

Notice that the distribution of the estimators of the first and total order indices can be estimated thanks to the getFirstOrderIndicesDistribution() and getTotalOrderIndicesDistribution() methods. This is done either through bootstrapping or using an asymptotic estimator. The ResourceMap key SobolIndicesAlgorithm-DefaultUseAsymptoticDistribution stores a boolean that decides the default behavior, but it can be overridden by the method setUseAsymptoticDistribution().

Corresponding confidence intervals are provided by the methods getFirstOrderIndicesInterval() and getTotalOrderIndicesInterval(). Their confidence level can be adjusted with setConfidenceLevel(). The default confidence level is stored in the ResourceMap and can be accessed with the SobolIndicesAlgorithm-DefaultConfidenceLevel key.

Indices estimates can be slightly outside of [0,1] if the estimator has not converged. For the same reason some first order indices estimates can be greater than the corresponding total order indices estimates.

The asymptotic estimator of the distribution requires an asymptotic estimate of its variance, which is computed using the [janon2014] delta method, as expained in the technical report [pmfre01116].

Methods

`DrawCorrelationCoefficients`(*args)	Draw the correlation coefficients.
`DrawImportanceFactors`(*args)	Draw the importance factors.
`DrawSobolIndices`(*args)	Draw the Sobol' indices.
`draw`(*args)	Draw sensitivity indices.
`getAggregatedFirstOrderIndices`()	Get the evaluation of aggregated first order Sobol indices.
`getAggregatedTotalOrderIndices`()	Get the evaluation of aggregated total order Sobol indices.
`getBootstrapSize`()	Get the number of bootstrap sampling size.
`getClassName`()	Accessor to the object's name.
`getConfidenceLevel`()	Get the confidence interval level for confidence intervals.
`getFirstOrderIndices`([marginalIndex])	Get first order Sobol indices.
`getFirstOrderIndicesDistribution`()	Get the distribution of the aggregated first order Sobol indices.
`getFirstOrderIndicesInterval`()	Get interval for the aggregated first order Sobol indices.
`getId`()	Accessor to the object's id.
`getImplementation`()	Accessor to the underlying implementation.
`getName`()	Accessor to the object's name.
`getSecondOrderIndices`([marginalIndex])	Get second order Sobol indices.
`getTotalOrderIndices`([marginalIndex])	Get total order Sobol indices.
`getTotalOrderIndicesDistribution`()	Get the distribution of the aggregated total order Sobol indices.
`getTotalOrderIndicesInterval`()	Get interval for the aggregated total order Sobol indices.
`getUseAsymptoticDistribution`()	Select asymptotic or bootstrap confidence intervals.
`setBootstrapSize`(bootstrapSize)	Set the number of bootstrap sampling size.
`setConfidenceLevel`(confidenceLevel)	Set the confidence interval level for confidence intervals.
`setDesign`(inputDesign, outputDesign, size)	Sample accessor.
`setName`(name)	Accessor to the object's name.
`setUseAsymptoticDistribution`(...)	Select asymptotic or bootstrap confidence intervals.

__init__(*args)¶

static DrawCorrelationCoefficients(*args)¶

Draw the correlation coefficients.

As correlation coefficients are considered, values might be positive or negative.

Available usages:

DrawCorrelationCoefficients(correlationCoefficients, title=’Correlation coefficients’)

DrawCorrelationCoefficients(values, names, title=’Correlation coefficients’)

Parameters:

correlationCoefficientsPointWithDescription: Sequence containing the correlation coefficients with a description for each component. The descriptions are used to build labels for the created graph. If they are not mentioned, default labels will be used.
valuessequence of float: Correlation coefficients.
namessequence of str: Variables’ names used to build labels for the created the graph.
titlestr: Title of the graph.

Returns:

graphGraph: A graph containing a Cloud and a Text of the correlation coefficients.

static DrawImportanceFactors(*args)¶

Draw the importance factors.

Available usages:

DrawImportanceFactors(importanceFactors, title=’Importance Factors’)

DrawImportanceFactors(values, names, title=’Importance Factors’)

Parameters:

importanceFactorsPointWithDescription: 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.
valuessequence of float: Importance factors.
namessequence of str: Variables’ names used to build labels for the created Pie.
titlestr: Title of the graph.

Returns:

graphGraph: A graph containing a Pie of the importance factors of the variables.

static DrawSobolIndices(*args)¶

Draw the Sobol’ indices.

Parameters:

inputDescriptionsequence of str: Variable names
firstOrderIndicessequence of float: First order indices values
totalOrderIndicessequence of float: Total order indices values
fo_ciInterval, optional: First order indices confidence interval
to_ciInterval, optional: Total order indices confidence interval

Returns:

graphGraph: For each variable, draws first and total indices

draw(*args)¶

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:

graphGraph: 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.

getAggregatedFirstOrderIndices()¶

Get the evaluation of aggregated first order Sobol indices.

Returns:

indicesPoint: Sequence containing aggregated first order Sobol indices.

getAggregatedTotalOrderIndices()¶

Get the evaluation of aggregated total order Sobol indices.

Returns:

indicesPoint: Sequence containing aggregated total order Sobol indices.

getBootstrapSize()¶

Get the number of bootstrap sampling size.

Returns:

bootstrapSizeint: Number of bootstrap sampling

getClassName()¶

Accessor to the object’s name.

Returns:

class_namestr: The object class name (object.__class__.__name__).

getConfidenceLevel()¶

Get the confidence interval level for confidence intervals.

Returns:

confidenceLevelfloat: Confidence level for confidence intervals

getFirstOrderIndices(marginalIndex=0)¶

Get first order Sobol indices.

Parameters:

iint, optional: Index of the output marginal of the function, equal to $0$ by default.

Returns:

indicesPoint: Sequence containing first order Sobol indices.

getFirstOrderIndicesDistribution()¶

Get the distribution of the aggregated first order Sobol indices.

Returns:

distributionDistribution: Distribution for first order Sobol indices for each component.

getFirstOrderIndicesInterval()¶

Get interval for the aggregated first order Sobol indices.

Returns:

intervalInterval: Interval for first order Sobol indices for each component. Computed marginal by marginal (not from the joint distribution).

getId()¶

Accessor to the object’s id.

Returns:

idint: Internal unique identifier.

getImplementation()¶

Accessor to the underlying implementation.

Returns:

implImplementation: A copy of the underlying implementation object.

getName()¶

Accessor to the object’s name.

Returns:

namestr: The name of the object.

getSecondOrderIndices(marginalIndex=0)¶

Get second order Sobol indices.

Parameters:

iint, optional: Index of the marginal of the function, equals to $0$ by default.

Returns:

indicesSymmetricMatrix: Tensor containing second order Sobol indices.

getTotalOrderIndices(marginalIndex=0)¶

Get total order Sobol indices.

Parameters:

iint, optional: Index of the output marginal of the function, equal to $0$ by default.

Returns:

indicesPoint: Sequence containing total order Sobol indices.

getTotalOrderIndicesDistribution()¶

Get the distribution of the aggregated total order Sobol indices.

Returns:

distributionDistribution: Distribution for total order Sobol indices for each component.

getTotalOrderIndicesInterval()¶

Get interval for the aggregated total order Sobol indices.

Returns:

intervalInterval: Interval for total order Sobol indices for each component. Computed marginal by marginal (not from the joint distribution).

getUseAsymptoticDistribution()¶

Select asymptotic or bootstrap confidence intervals.

Returns:

useAsymptoticDistributionbool: Whether to use bootstrap or asymptotic intervals

setBootstrapSize(bootstrapSize)¶

Set the number of bootstrap sampling size.

Default value is 0.

Parameters:

bootstrapSizeint: Number of bootstrap sampling

setConfidenceLevel(confidenceLevel)¶

Set the confidence interval level for confidence intervals.

Parameters:

confidenceLevelfloat: Confidence level for confidence intervals

setDesign(inputDesign, outputDesign, size)¶

Sample accessor.

Allows one to estimate indices from a predefined Sobol design.

Parameters:

inputDesignSample: Design for the evaluation of sensitivity indices, obtained thanks to the SobolIndicesAlgorithmImplementation.Generate method
outputDesignSample: Design for the evaluation of sensitivity indices, obtained as the evaluation of a Function (model) on the previous inputDesign
Nint: Base size of the Sobol design

setName(name)¶

Accessor to the object’s name.

Parameters:

namestr: The name of the object.

setUseAsymptoticDistribution(useAsymptoticDistribution)¶

Select asymptotic or bootstrap confidence intervals.

Default value is set by the SobolIndicesAlgorithm-DefaultUseAsymptoticDistribution key.

Parameters:

useAsymptoticDistributionbool: Whether to use bootstrap or asymptotic intervals

OpenTURNS

An Open source initiative for the Treatment of Uncertainties, Risks'N Statistics

Previous topic

Next topic

This Page

SobolIndicesAlgorithm¶