FunctionalChaosSobolIndices¶

class FunctionalChaosSobolIndices(*args)¶

Sensitivity analysis based on functional chaos expansion.

Parameters:

resultFunctionalChaosResult: A functional chaos result resulting from a polynomial chaos expansion.

See also

FunctionalChaosAlgorithm, FunctionalChaosResult

Notes

This structure is created from a FunctionalChaosResult in order to evaluate the Sobol’ indices associated to the polynomial chaos expansion of the model. The DrawSobolIndices() static method can be used to draw the indices.

This class provides methods to estimate the Sobol’ indices which are presented in Sensitivity analysis using Sobol’ indices. These indices can be easily computed from the polynomial chaos expansion using the methods presented in Sensitivity analysis using Sobol’ indices from polynomial chaos expansion.

The next table presents the map from the Sobol’ index to the corresponding method.

Single variable or group	Sensitivity Index	Notation	Method
One single variable $i$	First order	$S_i$	getSobolIndex(i)
	Total	$S^T_i$	getSobolTotalIndex(i)
Group interaction $\bdu$	First order	$S_\bdu$	getSobolIndex(variableIndices)
	Total interaction	$S^{T,i}_\bdu$	getSobolTotalIndex(variableIndices)
Group closed $\bdu$	First order closed	$S_\bdu^{\operatorname{cl}}$	getSobolGroupedIndex(variableIndices)
	Total	$S^T_\bdu$	getSobolGroupedTotalIndex(variableIndices)

Table 1. Sobol’ indices and the corresponding methods.

By default, printing the object will print the Sobol’ indices and the multi-indices ordered by decreasing part of variance. If a multi-index accounts for a smaller part of the variance than some threshold, it is not printed. This threshold can be customized using the FunctionalChaosSobolIndices-VariancePartThreshold key of the ResourceMap.

Examples

Create a polynomial chaos for the Ishigami function:

>>> import openturns as ot
>>> from math import pi
>>> import openturns.viewer as otv

Create the function:

>>> ot.RandomGenerator.SetSeed(0)
>>> formula = ['sin(X1) + 7. * sin(X2)^2 + 0.1 * X3^4 * sin(X1)']
>>> input_names = ['X1', 'X2', 'X3']
>>> g = ot.SymbolicFunction(input_names, formula)

Create the probabilistic model:

>>> distributionList = [ot.Uniform(-pi, pi)] * 3
>>> distribution = ot.ComposedDistribution(distributionList)

Create a training sample:

>>> N = 100 
>>> inputTrain = distribution.getSample(N)
>>> outputTrain = g(inputTrain)

Create the chaos:

>>> chaosalgo = ot.FunctionalChaosAlgorithm(inputTrain, outputTrain, distribution)
>>> chaosalgo.run()
>>> result = chaosalgo.getResult()

Print Sobol’ indices (see Compute grouped indices for the Ishigami function for details):

>>> chaosSI = ot.FunctionalChaosSobolIndices(result) 
>>> #print(chaosSI)  # Prints a table of multi-indices

Get first order Sobol’ index for X0:

>>> s0 = chaosSI.getSobolIndex(0)
>>> print('S(0) = ', s0)
S(0) =  0.26...

Get total Sobol’ index for X0:

>>> st0 = chaosSI.getSobolTotalIndex(0)
>>> print('ST(0) = ', st0)
ST(0) =  0.48...

Get interaction Sobol’ index for the group (X0, X1):

>>> s01 = chaosSI.getSobolIndex([0, 1])
>>> print('S([0, 1]) = ', s01)
S([0, 1]) =  0.00...

Get total interaction Sobol’ index for the group (X0, X1):

>>> st01 = chaosSI.getSobolTotalIndex([0, 1])
>>> print('ST([0, 1]) = ', st01)
ST([0, 1]) =  0.00...

Get first order Sobol’ index for group [X0,X1]:

>>> sg01 = chaosSI.getSobolGroupedIndex([0,1])
>>> print('SG([0, 1]) = ', sg01)
SG([0, 1]) =  0.76...

Get total Sobol’ index for group [X0,X1]:

>>> stg01 = chaosSI.getSobolGroupedTotalIndex([0,1])
>>> print('STG([0, 1]) = ', stg01)
STG([0, 1]) =  0.99...

Get the part of variance of first multi-indices:

>>> partOfVariance = chaosSI.getPartOfVariance()

Methods

`getClassName`()	Accessor to the object's name.
`getFunctionalChaosResult`()	Accessor to the functional chaos result.
`getId`()	Accessor to the object's id.
`getName`()	Accessor to the object's name.
`getPartOfVariance`([marginalIndex])	Get the part of variance corresponding to each multi-index.
`getShadowedId`()	Accessor to the object's shadowed id.
`getSobolGroupedIndex`(variableIndices[, ...])	Get the Sobol' first order closed index of a group of input variables.
`getSobolGroupedTotalIndex`(variableIndices[, ...])	Get the Sobol' total index of a group of input variables.
`getSobolIndex`(*args)	Get the first order Sobol' index of an input variable or the interaction (high order) index of a group of variables.
`getSobolTotalIndex`(*args)	Get the Sobol' total index of an input variable or the total interaction index of a group of input variables.
`getVisibility`()	Accessor to the object's visibility state.
`hasName`()	Test if the object is named.
`hasVisibleName`()	Test if the object has a distinguishable name.
`setName`(name)	Accessor to the object's name.
`setShadowedId`(id)	Accessor to the object's shadowed id.
`setVisibility`(visible)	Accessor to the object's visibility state.

__init__(*args)¶

getClassName()¶

Accessor to the object’s name.

Returns:

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

getFunctionalChaosResult()¶

Accessor to the functional chaos result.

Returns:

functionalChaosResultFunctionalChaosResult: The functional chaos result resulting from a polynomial chaos decomposition.

getId()¶

Accessor to the object’s id.

Returns:

idint: Internal unique identifier.

getName()¶

Accessor to the object’s name.

Returns:

namestr: The name of the object.

getPartOfVariance(marginalIndex=0)¶

Get the part of variance corresponding to each multi-index.

Parameters:

marginalIndexint: Output marginal index. Default value is 0, i.e. the first output.

Returns:

partOfVariancePoint: The part of variance partOfVariance[i] of each multi-index, for i = 0, …, indicesSize - 1 where indicesSize is the number of indices. The part of variance of a given multi-index is in the [0, 1] interval. This is a sensitivity index which represents the part of the variance explained by the corresponding function. The sum of part of variances is equal to 1. If the corresponding multi-index has total degree equal to 0, then the corresponding part of variance is equal to zero.

getShadowedId()¶

Accessor to the object’s shadowed id.

Returns:

idint: Internal unique identifier.

getSobolGroupedIndex(variableIndices, marginalIndex=0)¶

Get the Sobol’ first order closed index of a group of input variables.

Let $\bdu \subseteq \{0, ..., d - 1\}$ the list of variable indices in the group. Therefore, the method computes the first order closed Sobol’ index $S^{\operatorname{cl}}_\bdu$ of the group $\bdu$ . See Closed first order Sobol’ index of a group of variables for the computation of this sensitivity index based on a PCE.

Parameters:

variableIndicessequence of int, $0 \leq i \leq d - 1$: Indice(s) of the variable(s) in the group.
marginalIndexint: Output marginal index. Default value is 0, i.e. the first output.

Returns:

sfloat: The Sobol’ first order closed index of a group of input variables.

getSobolGroupedTotalIndex(variableIndices, marginalIndex=0)¶

Get the Sobol’ total index of a group of input variables.

Let $\bdu \subseteq \{0, ..., d - 1\}$ the list of variable indices in the group. Therefore, the method computes the total Sobol’ index $S^T_\bdu$ of the group $\bdu$ . See Total Sobol’ index of a group of variables for the computation of this sensitivity index based on a PCE.

Parameters:

variableIndicessequence of int, $0 \leq i \leq d - 1$: Indice(s) of the variable(s) in the group.
marginalIndexint: Output marginal index. Default value is 0, i.e. the first output.

Returns:

sfloat: The Sobol’ total closed index of a group of input variables.

getSobolIndex(*args)¶

Get the first order Sobol’ index of an input variable or the interaction (high order) index of a group of variables. This function can take a single variable or a group of variables as input argument.

Case 1: single variable. Let $i \in \{0, ..., d - 1\}$ the index of an input variable. Therefore, the method computes the first order Sobol’ index $S_i$ of the variable $X_i$ . See First order Sobol’ index of a single variable for the computation of this sensitivity index based on a PCE.

Case 2: group of variables. Let $\bdu \subseteq \{0, ..., d - 1\}$ the list of variable indices in the group. Therefore, the method computes the interaction (high order) Sobol’ index $S_\bdu$ of the group $\bdu$ . See Interaction Sobol’ index of a group of variables for the computation of this sensitivity index based on a PCE.

Parameters:

iint or sequence of int, $0 \leq i \leq d - 1$: Indice(s) of the variable(s).
marginalIndexint: Output marginal index. Default value is 0, i.e. the first output.

Returns:

sfloat: The Sobol’ first order index of an input variable or interaction index of a group of input variables.

getSobolTotalIndex(*args)¶

Get the Sobol’ total index of an input variable or the total interaction index of a group of input variables. This function can take a single variable or a group of variables as input argument.

Case 1: single variable. Let $i \in \{0, ..., d - 1\}$ the index of an input variable. Therefore, the method computes the total index $S^T_i$ of the variable $X_i$ . See Total Sobol’ index of a single variable for the computation of this sensitivity index based on a PCE.

Case 2: group of variables. Let $\bdu \subseteq \{0, ..., d - 1\}$ the list of variable indices in the group. Therefore, the method computes the total interaction (high order) Sobol’ index $S_\bdu^{T, i}$ of the group $\bdu$ . See Total interaction Sobol’ index of a group of variables for the computation of this sensitivity index based on a PCE.

Parameters:

iint or sequence of int, $0 \leq i \leq d - 1$: Indice(s) of the variable(s).
marginalIndexint: Output marginal index. Default value is 0, i.e. the first output.

Returns: