gemseo / uncertainty / sensitivity / sobol

# analysis module¶

Class for the estimation of Sobol’ indices.

Let us consider the model $$Y=f(X_1,\ldots,X_d)$$ where:

• $$X_1,\ldots,X_d$$ are independent random variables,

• $$E\left[f(X_1,\ldots,X_d)^2\right]<\infty$$.

Then, the following decomposition is unique:

$Y=f_0 + \sum_{i=1}^df_i(X_i) + \sum_{i,j=1\atop i\neq j}^d f_{i,j}(X_i,X_j) + \sum_{i,j,k=1\atop i\neq j\neq k}^d f_{i,j,k}(X_i,X_j,X_k) + \ldots + f_{1,\ldots,d}(X_1,\ldots,X_d)$

where:

• $$f_0=E[Y]$$,

• $$f_i(X_i)=E[Y|X_i]-f_0$$,

• $$f_{i,j}(X_i,X_j)=E[Y|X_i,X_j]-f_i(X_i)-f_j(X_j)-f_0$$

• and so on.

Then, the shift to variance leads to:

$V[Y]=\sum_{i=1}^dV\left[f_i(X_i)\right] + \sum_{i,j=1\atop j\neq i}^d V\left[f_{i,j}(X_i,X_j)\right] + \ldots + V\left[f_{1,\ldots,d}(X_1,\ldots,X_d)\right]$

and the Sobol’ indices are obtained by dividing by the variance and sum up to 1:

$1=\sum_{i=1}^dS_i + \sum_{i,j=1\atop j\neq i}^d S_{i,j} + \sum_{i,j,k=1\atop i\neq j\neq k}^d S_{i,j,k} + \ldots + S_{1,\ldots,d}$

A Sobol’ index represents the share of output variance explained by a parameter or a group of parameters. For the parameter $$X_i$$,

• $$S_i$$ is the first-order Sobol’ index measuring the individual effect of $$X_i$$,

• $$S_{i,j}$$ is the second-order Sobol’ index measuring the joint effect between $$X_i$$ and $$X_j$$,

• $$S_{i,j,k}$$ is the third-order Sobol’ index measuring the joint effect between $$X_i$$, $$X_j$$ and $$X_k$$,

• and so on.

In practice, we only consider the first-order Sobol’ index:

$S_i=\frac{V[E[Y|X_i]]}{V[Y]}$

and the total-order Sobol’ index:

$S_i^T=\sum_{u\subset\{1,\ldots,d\}\atop u \ni i}S_u$

The latter represents the sum of the individual effect of $$X_i$$ and the joint effects between $$X_i$$ and any parameter or group of parameters.

This methodology relies on the SobolAnalysis class. Precisely, SobolAnalysis.indices contains both SobolAnalysis.first_order_indices and SobolAnalysis.total_order_indices while SobolAnalysis.main_indices represents total-order Sobol’ indices. Lastly, the SobolAnalysis.plot() method represents the estimations of both first-order and total-order Sobol’ indices along with their 95% confidence interval.

The user can select the algorithm to estimate the Sobol’ indices. The computation relies on OpenTURNS capabilities.

Classes:

 SobolAnalysis(discipline, parameter_space, ...) Sensitivity analysis based on the Sobol' indices.
class gemseo.uncertainty.sensitivity.sobol.analysis.SobolAnalysis(discipline, parameter_space, n_samples, algo=None, algo_options=None)[source]

Sensitivity analysis based on the Sobol’ indices.

default_output

The default outputs of interest.

Type

list(str)

dataset

The dataset containing the discipline evaluations.

Type

Dataset

Examples

>>> from numpy import pi
>>> from gemseo.api import create_discipline, create_parameter_space
>>> from gemseo.uncertainty.sensitivity.sobol.analysis import SobolAnalysis
>>>
>>> expressions = {"y": "sin(x1)+7*sin(x2)**2+0.1*x3**4*sin(x1)"}
>>> discipline = create_discipline(
...     "AnalyticDiscipline", expressions_dict=expressions
... )
>>>
>>> parameter_space = create_parameter_space()
...     "x1", "OTUniformDistribution", minimum=-pi, maximum=pi
... )
...     "x2", "OTUniformDistribution", minimum=-pi, maximum=pi
... )
...     "x3", "OTUniformDistribution", minimum=-pi, maximum=pi
... )
>>>
>>> analysis = SobolAnalysis(discipline, parameter_space, n_samples=10000)
>>> indices = analysis.compute_indices()


Initialize self. See help(type(self)) for accurate signature.

Parameters
• discipline (MDODiscipline) – A discipline.

• parameter_space (ParameterSpace) – A parameter space.

• n_samples (int) – A number of samples. If None, the number of samples is computed by the algorithm.

• algo (Optional[str]) –

The name of the DOE algorithm. If None, use the DEFAULT_DRIVER.

By default it is set to None.

• algo_options (Optional[Mapping[str,DOELibraryOptionType]]) –

The options of the DOE algorithm.

By default it is set to None.

Return type

None

Attributes:

 AVAILABLE_ALGOS DEFAULT_DRIVER first_order_indices The first-order Sobol' indices. indices The sensitivity indices. inputs_names The names of the inputs. main_indices The main sensitivity indices. main_method The name of the main method. total_order_indices The total-order Sobol' indices.

Methods:

 compute_indices([outputs, algo]) Compute the sensitivity indices. Convert SensitivityAnalysis.indices into a Dataset. get_intervals([first_order]) Get the confidence interval for Sobol' indices. plot(output[, inputs, title, save, show, ...]) Plot the first- and total-order Sobol' indices. plot_bar(outputs[, inputs, standardize, ...]) Plot the sensitivity indices on a bar chart. plot_comparison(indices, output[, inputs, ...]) Plot a comparison between the current sensitivity indices and other ones. plot_field(output[, mesh, inputs, ...]) Plot the sensitivity indices related to a 1D or 2D functional output. plot_radar(outputs[, inputs, standardize, ...]) Plot the sensitivity indices on a radar chart. sort_parameters(output) Return the parameters sorted in descending order. standardize_indices(indices) Standardize the sensitivity indices for each output component.
AVAILABLE_ALGOS = ['Jansen', 'Martinez', 'MauntzKucherenko', 'Saltelli']
DEFAULT_DRIVER = 'OT_SOBOL_INDICES'
compute_indices(outputs=None, algo='Saltelli')[source]

Compute the sensitivity indices.

Parameters
• outputs (Optional[Sequence[str]]) –

The outputs for which to display sensitivity indices. If None, use the default outputs, that are all the discipline outputs.

By default it is set to None.

• algo (str) –

The name of the algorithm to estimate the Sobol’ indices

By default it is set to Saltelli.

Returns

The sensitivity indices.

With the following structure:

{
"method_name": {
"output_name": [
{
"input_name": data_array,
}
]
}
}


Return type

Dict[str, Dict[str, List[Dict[str, numpy.ndarray]]]]

export_to_dataset()

Convert SensitivityAnalysis.indices into a Dataset.

Returns

The sensitivity indices.

Return type

Dataset

property first_order_indices

The first-order Sobol’ indices.

With the following structure:

{
"output_name": [
{
"input_name": data_array,
}
]
}

Type

dict

get_intervals(first_order=True)[source]

Get the confidence interval for Sobol’ indices.

Parameters

first_order (bool) –

The type of indices. If True, returns the intervals for the first-order indices. Otherwise, for the total-order indices.

By default it is set to True.

Returns

The confidence intervals for the Sobol’ indices.

With the following structure:

{
"output_name": [
{
"input_name": data_array,
}
]
}


Return type

dict

property indices

The sensitivity indices.

With the following structure:

{
"method_name": {
"output_name": [
{
"input_name": data_array,
}
]
}
}

property inputs_names

The names of the inputs.

property main_indices

The main sensitivity indices.

With the following structure:

{
"output_name": [
{
"input_name": data_array,
}
]
}

property main_method

The name of the main method.

plot(output, inputs=None, title=None, save=True, show=False, file_path=None, directory_path=None, file_name=None, file_format=None, sort=True, sort_by_total=True)[source]

Plot the first- and total-order Sobol’ indices.

For $$i\in\{1,\ldots,d\}$$, plot $$S_i^{1}$$ and $$S_T^{1}$$ with their confidence intervals,

Parameters
• output – The output for which to display sensitivity indices, either a name or a tuple of the form (name, component). If name, its first component is considered.

• inputs

The inputs to display. If None, display all.

By default it is set to None.

• title

The title of the plot. If None, no title.

By default it is set to None.

• save

If True, save the figure.

By default it is set to True.

• show

If True, show the figure.

By default it is set to False.

• file_path

A file path. Either a complete file path, a directory name or a file name. If None, use a default file name and a default directory. The file extension is inferred from filepath extension, if any.

By default it is set to None.

• file_format

A file format, e.g. ‘png’, ‘pdf’, ‘svg’, … Used when file_path does not have any extension. If None, use a default file extension.

By default it is set to None.

• sort

The sorting option. If True, sort variables before display.

By default it is set to True.

• sort_by_total

The type of sorting. If True, sort variables according to total-order Sobol’ indices. Otherwise, use first-order Sobol’ indices.

By default it is set to True.

plot_bar(outputs, inputs=None, standardize=False, title=None, save=True, show=False, file_path=None, directory_path=None, file_name=None, file_format=None, **options)

Plot the sensitivity indices on a bar chart.

This method may consider one or more outputs, as well as all inputs (default behavior) or a subset.

Parameters
• outputs (Union[str, Tuple[str, int], Sequence[Union[str, Tuple[str, int]]]]) – The outputs for which to display sensitivity indices, either a name, a list of names, a (name, component) tuple, a list of such tuples or a list mixing such tuples and names. When a name is specified, all its components are considered. If None, use the default outputs.

• inputs (Optional[Iterable[str]]) –

The inputs to display. If None, display all.

By default it is set to None.

• standardize (bool) –

If True, standardize the indices between 0 and 1 for each output.

By default it is set to False.

• title (Optional[str]) –

The title of the plot. If None, no title.

By default it is set to None.

• save (bool) –

If True, save the figure.

By default it is set to True.

• show (bool) –

If True, show the figure.

By default it is set to False.

• file_path (Optional[Union[str, pathlib.Path]]) –

The path of the file to save the figures. If the extension is missing, use file_extension. If None, create a file path from directory_path, file_name and file_extension.

By default it is set to None.

• directory_path (Optional[Union[str, pathlib.Path]]) –

The path of the directory to save the figures. If None, use the current working directory.

By default it is set to None.

• file_name (Optional[str]) –

The name of the file to save the figures. If None, use a default one generated by the post-processing.

By default it is set to None.

• file_format (Optional[str]) –

A file extension, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.

By default it is set to None.

• **options (int) –

Returns

A bar chart representing the sensitivity indices.

Return type

gemseo.post.dataset.bars.BarPlot

plot_comparison(indices, output, inputs=None, title=None, use_bar_plot=True, save=True, show=False, file_path=None, directory_path=None, file_name=None, file_format=None, **options)

Plot a comparison between the current sensitivity indices and other ones.

This method allows to use either a bar chart (default option) or a radar one.

Parameters
• indices (List[gemseo.uncertainty.sensitivity.analysis.SensitivityAnalysis]) – The sensitivity indices.

• output (Union[str, Tuple[str, int]]) – The output for which to display sensitivity indices, either a name or a tuple of the form (name, component). If name, its first component is considered.

• inputs (Optional[Iterable[str]]) –

The inputs to display. If None, display all.

By default it is set to None.

• title (Optional[str]) –

The title of the plot. If None, no title.

By default it is set to None.

• use_bar_plot (bool) –

The type of graph. If True, use a bar plot. Otherwise, use a radar chart.

By default it is set to True.

• save (bool) –

If True, save the figure.

By default it is set to True.

• show (bool) –

If True, show the figure.

By default it is set to False.

• file_path (Optional[Union[str, pathlib.Path]]) –

The path of the file to save the figures. If None, create a file path from directory_path, file_name and file_format.

By default it is set to None.

• directory_path (Optional[Union[str, pathlib.Path]]) –

The path of the directory to save the figures. If None, use the current working directory.

By default it is set to None.

• file_name (Optional[str]) –

The name of the file to save the figures. If None, use a default one generated by the post-processing.

By default it is set to None.

• file_format (Optional[str]) –

A file format, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.

By default it is set to None.

• **options (bool) – The options passed to the underlying DatasetPlot.

Returns

A graph comparing sensitivity indices.

Return type
plot_field(output, mesh=None, inputs=None, standardize=False, title=None, save=True, show=False, file_path=None, directory_path=None, file_name=None, file_format=None, properties=None)

Plot the sensitivity indices related to a 1D or 2D functional output.

The output is considered as a 1D or 2D functional variable, according to the shape of the mesh on which it is represented.

Parameters
• output (Union[str, Tuple[str, int]]) – The output for which to display sensitivity indices, either a name or a tuple of the form (name, component). If name, its first component is considered.

• mesh (Optional[numpy.ndarray]) –

The mesh on which the p-length output is represented. Either a (1, p) array for a 1D functional output or a (2, p) array for a 2D one. If None, assume a 1D functional output.

By default it is set to None.

• inputs (Optional[Iterable[str]]) –

The inputs to display. If None, display all inputs.

By default it is set to None.

• standardize (bool) –

If True, standardize the indices between 0 and 1 for each output.

By default it is set to False.

• title (Optional[str]) –

The title of the plot. If None, no title is displayed.

By default it is set to None.

• save (bool) –

If True, save the figure.

By default it is set to True.

• show (bool) –

If True, show the figure.

By default it is set to False.

• file_path (Optional[Union[str, pathlib.Path]]) –

The path of the file to save the figures. If None, create a file path from directory_path, file_name and file_extension.

By default it is set to None.

• directory_path (Optional[Union[str, pathlib.Path]]) –

The path of the directory to save the figures. If None, use the current working directory.

By default it is set to None.

• file_name (Optional[str]) –

The name of the file to save the figures. If None, use a default one generated by the post-processing.

By default it is set to None.

• file_format (Optional[str]) –

A file extension, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.

By default it is set to None.

• properties (Optional[Mapping[str, Union[str, int, float, Sequence[Union[str, int, float]]]]]) –

The general properties of a DatasetPlot.

By default it is set to None.

Returns

A bar plot representing the sensitivity indices.

Raises

NotImplementedError – If the dimension of the mesh is greater than 2.

Return type

Plot the sensitivity indices on a radar chart.

This method may consider one or more outputs, as well as all inputs (default behavior) or a subset.

For visualization purposes, it is also possible to change the minimum and maximum radius values.

Parameters
• outputs (Union[str, Tuple[str, int], Sequence[Union[str, Tuple[str, int]]]]) – The outputs for which to display sensitivity indices, either a name, a list of names, a (name, component) tuple, a list of such tuples or a list mixing such tuples and names. When a name is specified, all its components are considered. If None, use the default outputs.

• inputs (Optional[Iterable[str]]) –

The inputs to display. If None, display all.

By default it is set to None.

• standardize (bool) –

If True, standardize the indices between 0 and 1 for each output.

By default it is set to False.

• title (Optional[str]) –

The title of the plot. If None, no title.

By default it is set to None.

• save (bool) –

If True, save the figure.

By default it is set to True.

• show (bool) –

If True, show the figure.

By default it is set to False.

• file_path (Optional[Union[str, pathlib.Path]]) –

The path of the file to save the figures. If the extension is missing, use file_extension. If None, create a file path from directory_path, file_name and file_extension.

By default it is set to None.

• directory_path (Optional[Union[str, pathlib.Path]]) –

The path of the directory to save the figures. If None, use the current working directory.

By default it is set to None.

• file_name (Optional[str]) –

The name of the file to save the figures. If None, use a default one generated by the post-processing.

By default it is set to None.

• file_format (Optional[str]) –

A file extension, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.

By default it is set to None.

The minimal radial value. If None, from data.

By default it is set to None.

The maximal radial value. If None, from data.

By default it is set to None.

• **options (bool) –

Returns

A radar chart representing the sensitivity indices.

Return type

sort_parameters(output)

Return the parameters sorted in descending order.

Parameters

output (Union[str, Tuple[str, int]]) – An output of the form (name, component), where name is the output name and component is the output component. If a string is passed, the tuple (name, 0) will be considered corresponding to the first component of the output name.

Returns

The input parameters sorted in descending order.

Return type

List[str]

static standardize_indices(indices)

Standardize the sensitivity indices for each output component.

Each index is replaced by its absolute value divided by the largest index. Thus, the standardized indices belong to the interval $$[0,1]$$.

Parameters

indices (Dict[str, List[Dict[str, numpy.ndarray]]]) – The indices to be standardized.

Returns

The standardized indices.

Return type

Dict[str, List[Dict[str, numpy.ndarray]]]

property total_order_indices

The total-order Sobol’ indices.

With the following structure:

{
"output_name": [
{
"input_name": data_array,
}
]
}

Type

dict