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]

Bases: gemseo.uncertainty.sensitivity.analysis.SensitivityAnalysis

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()
>>> parameter_space.add_random_variable(
...     "x1", "OTUniformDistribution", minimum=-pi, maximum=pi
... )
>>> parameter_space.add_random_variable(
...     "x2", "OTUniformDistribution", minimum=-pi, maximum=pi
... )
>>> parameter_space.add_random_variable(
...     "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.

export_to_dataset()

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

Union[gemseo.post.dataset.bars.BarPlot, gemseo.post.dataset.radar_chart.RadarChart]

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

Union[gemseo.post.dataset.curves.Curves, gemseo.post.dataset.surfaces.Surfaces]

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

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.

  • min_radius (Optional[float]) –

    The minimal radial value. If None, from data.

    By default it is set to None.

  • max_radius (Optional[float]) –

    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

gemseo.post.dataset.radar_chart.RadarChart

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