SobolIndicesAlgorithm

class SobolIndicesAlgorithm(*args)

Sensitivity analysis.

Notes

This method is concerned with analyzing the influence the random vector \vect{X} = \left( X^1, \ldots, X^{n_X} \right) has on a random variable Y^k which is being studied for uncertainty.

Here we attempt to evaluate the part of variance of Y^k due to the different components X^i.

We denote G the physical model such as \vect{Y}=G(\vect{X}). Let us consider first the case where \vect{Y} is of dimension 1.

The objective here is to develop the variability of the random variable \vect{Y} as function of \vect{X} = \left( X^1, \ldots, X^{n_X} \right). Using the Hoeffding decomposition, we got:

\Var{\vect{Y}} = \sum_{i=1}^{n_X} V_i + \sum_{i<j} V_{i,j} + \sum_{i<k<j} V_{i,j,k} + \cdots + V_{1,2,..,n_X}

where :

V_i = \Var{\Expect{ Y \vert X_i}} and V_{i,j} = \Var{\Expect{ Y \vert X_i, X_j}} - V_i - V_j. Using the previous decomposition, it follows that sensitivity indices are defined as follow:

\begin{array}{ccc}
 S_i & = & \frac{V_i}{\Var{\vect{Y}}} \\
 S_{i,j} & = & \frac{V_{i,j}}{\Var{\vect{Y}}}
\end{array}

(S_i) are the first order sensitivity indices and measure the impact of X_i in the variance \Var{\vect{Y}}, (S_{i,j}) are the second order sensitivity indices and measure the impact of the interaction of X_i and X_j in the variance \Var{\vect{Y}}.

When n_X >> 1, we use total sensitivity indices ST_i, which is defined as the sum of all indices that count the i-th variable:

ST_i =  1 - \frac{V_{-i}}{\Var{\vect{Y}}} = \frac{VT_i}{\Var{\vect{Y}}}, \forall\ i\in(1,2,...,n_X)

where V_{-i} is the part of variance of \Var{\vect{Y}} that do not countain the i-th variable.


In practice, to estimate these quantities, Sobol proposes to use numerical methods that rely on the two independent realizations of the random vector \vect{X}. If we consider A and B two independent samples (of size n) of the previous random vector:

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), \  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. The purpose is to mix these two samples to get an estimate of the sensitivities.

Sobol method require respectively C^i and D^{i,j} sample designs for the evaluation of first order (respectively second order) sensitivity indices. These are defined as hereafter:

C^i = \left(
\begin{array}{ccccc}
b_{1,1} & b_{1,2} & a_{1,i} & \cdots & b_{1, n_X} \\
b_{2,1} & b_{2,2} & a_{2,i} & \cdots & b_{2, n_X} \\
\vdots  & \vdots  & \vdots  & \ddots  & \vdots \\
b_{n,1} & b_{1,2} & a_{n,i} & \cdots & b_{n, n_X}
\end{array}
\right), \ D^{i,j} = \left(
\begin{array}{ccccccc}
b_{1,1} & b_{1,2} & a_{1,i} & \cdots & a_{1,j} & \cdots & b_{1, n_X} \\
b_{2,1} & b_{2,2} & a_{2,i} & \cdots & a_{2,j} & \cdots & b_{2, n_X} \\
\vdots  & \vdots  & \vdots  & \vdots & \vdots  & \ddots & \vdots \\
b_{n,1} & b_{n,2} & a_{n,i} & \cdots & a_{n,j} & \cdots & b_{n, n_X} \\
\end{array}
\right)

It follows that V_{i} and V_{i,j} terms are defined as follow:

\begin{array}{ccc}
 V_i & = & \frac{1}{n} \sum_{k=1}^{n} G(A_k) G(C_k) - V_i - V_j - G_0^2 \\
 V_{i,j} & = & \frac{1}{n} \sum_{k=1}^{n} G(A_k) G(D_k) - G_0^2 \\
 G_0 & = & \frac{1}{n} \sum_{k=1}^{n} G(A_k)
\end{array}

The implemented second order indices use this formula.

The major methods (Saltelli, Jansen, Mauntz-Kucherenko, Martinez) use the E^i matrix to compute the indices (first order and total order). This matrix is defined as follows:

E^i = \left(
\begin{array}{ccccc}
a_{1,1} & a_{1,2} & b_{1,i} & \cdots & a_{1, n_X} \\
a_{2,1} & a_{2,2} & b_{2,i} & \cdots & a_{2, n_X} \\
\vdots  & \vdots  & \vdots  & \ddots  & \vdots \\
a_{n,1} & a_{1,2} & b_{n,i} & \cdots & a_{n, n_X}
\end{array}
\right)

The formulas for the evaluation of the indices are given in each class documentation:

For multivariate outputs, aggregate indices can be computed thanks to the getAggregatedFirstOrderIndices and getAggregatedTotalOrderIndices. Such indices write as follow:

\begin{array}{ccc}
 S_i & = & \frac{ \sum_{k=1}^{q} V_{i}^{(k)} }{ \sum_{k=1}^{q} \Var{Y_k} }  \\
 S_{i,j} & = & \frac{ \sum_{k=1}^{q} V_{i,j}^{(k)} }{ \sum_{k=1}^{q} \Var{Y_k} }  \\
 ST_i & = & \frac{ \sum_{k=1}^{q} VT_{i}^{(k)} }{ \sum_{k=1}^{q} \Var{Y_k} }
\end{array}

Aggregated second order indices have not been implemented.


Note finally that evaluation of intervals for indices might be done for first and total order thanks to the getFirstOrderIndicesInterval and getTotalOrderIndicesInterval methods. Default bootstrap size and confidence level values are parametrized thanks to the resource map keys SobolIndicesAlgorithm-BootstrapSize and SobolIndicesAlgorithm-BootstrapConfidenceLevel. Appropriate setters might be called to change their values.

Also note that for numerical stability reasons the ouputs are centered before indices estimation:

Y_k = Y_k - \Eset(Y_k)

Methods

draw(*args) Draw sensitivity indices.
getAggregatedFirstOrderIndices() Get the evaluation of merged first order Sobol indices.
getAggregatedTotalOrderIndices() Get the evaluation of merged total order Sobol indices.
getBootstrapConfidenceLevel() Get the confidence interval level for bootstrap sampling.
getBootstrapSize() Get the number of bootstrap sampling size.
getClassName() Accessor to the object’s name.
getFirstOrderIndices([marginalIndex]) Get first order Sobol indices.
getFirstOrderIndicesInterval() Get interval for the merged first order Sobol indices.
getId() Accessor to the object’s id.
getImplementation(*args) 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.
getTotalOrderIndicesInterval() Get interval for the merged total order Sobol indices.
setBootstrapConfidenceLevel(confidenceLevel) Set the confidence interval level for bootstrap sampling.
setBootstrapSize(bootstrapSize) Set the number of bootstrap sampling size.
setName(name) Accessor to the object’s name.
__init__(*args)
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:

Graph : Graph

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 merged first order Sobol indices.

Returns:

indices : Point

Sequence containing merged first order Sobol indices.

getAggregatedTotalOrderIndices()

Get the evaluation of merged total order Sobol indices.

Returns:

indices : Point

Sequence containing merged total order Sobol indices.

getBootstrapConfidenceLevel()

Get the confidence interval level for bootstrap sampling.

Returns:

confidenceLevel : float

Confidence level for boostrap sampling

getBootstrapSize()

Get the number of bootstrap sampling size.

Returns:

bootstrapSize : int

Number of bootsrap sampling

getClassName()

Accessor to the object’s name.

Returns:

class_name : str

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

getFirstOrderIndices(marginalIndex=0)

Get first order Sobol indices.

Parameters:

i : int, optional

Index of the marginal of the function, equals to 0 by default.

Returns:

indices : Point

Sequence containing first order Sobol indices.

getFirstOrderIndicesInterval()

Get interval for the merged first order Sobol indices.

Returns:

interval : Interval

Interval for first order Sobol indices for each component.

getId()

Accessor to the object’s id.

Returns:

id : int

Internal unique identifier.

getImplementation(*args)

Accessor to the underlying implementation.

Returns:

impl : Implementation

The implementation class.

getName()

Accessor to the object’s name.

Returns:

name : str

The name of the object.

getSecondOrderIndices(marginalIndex=0)

Get second order Sobol indices.

Parameters:

i : int, optional

Index of the marginal of the function, equals to 0 by default.

Returns:

indices : SymmetricMatrix

Tensor containing second order Sobol indices.

getTotalOrderIndices(marginalIndex=0)

Get total order Sobol indices.

Parameters:

i : int, optional

Index of the marginal of the function, equals to 0 by default.

Returns:

indices : Point

Sequence containing total order Sobol indices.

getTotalOrderIndicesInterval()

Get interval for the merged total order Sobol indices.

Returns:

interval : Interval

Interval for total order Sobol indices for each component.

setBootstrapConfidenceLevel(confidenceLevel)

Set the confidence interval level for bootstrap sampling.

Parameters:

confidenceLevel : float

Confidence level for boostrap sampling

setBootstrapSize(bootstrapSize)

Set the number of bootstrap sampling size.

Default value is 0.

Parameters:

bootstrapSize : int

Number of bootsrap sampling

setName(name)

Accessor to the object’s name.

Parameters:

name : str

The name of the object.