Sensitivity analysis

The package sensitivity

Capabilities to run a sensitivity analysis.

This package contains:

• an abstract class BaseSensitivityAnalysis to define the concept of sensitivity analysis,

• a factory SensitivityAnalysisFactory to create instances of BaseSensitivityAnalysis,

• concrete classes implementing this abstract class:

  • CorrelationAnalysis (based on OpenTURNS capabilities)

  • MorrisAnalysis,

  • SobolAnalysis (based on OpenTURNS capabilities),

  • HSICAnalysis (based on OpenTURNS capabilities).

The base class BaseSensitivityAnalysis

Base class for the computation and analysis of sensitivity indices.

class BaseSensitivityAnalysis(samples='')

Base class for sensitivity analysis.

A sensitivity analysis aims to qualify or quantify how the model's uncertain input variables impact its output variables from input-output samples relying on a specific design of experiments (DOE).

A BaseSensitivityAnalysis can be created from such samples (passed as an IODataset) or use its compute_samples() method to generate them, using a Discipline representing the model, a ParameterSpace describing the uncertain input variables and a set of options. In the second case, the samples returned by compute_samples() can be saved on the disk for future use.

Parameters:

samples (IODataset | str | Path) --

The samples for the estimation of the sensitivity indices, either as an IODataset or as a pickle file path generated from the IODataset.to_pickle method. If empty, use compute_samples().

By default it is set to "".

class Method(value)

The names of the sensitivity methods.

class SensitivityIndices

The sensitivity indices.

Given a sensitivity method, an input variable and an output variable, the sensitivity index which is a 1D NumPy array can be accessed through indices.method_name[output_name][output_component][input_name].

abstract compute_indices(output_names=())

Compute the sensitivity indices.

Parameters:

output_names (str | Iterable[str]) --

The name(s) of the output(s) for which to compute the sensitivity indices. If empty, use the names of the outputs set at instantiation.

By default it is set to ().

Returns:

The sensitivity indices.

Given a sensitivity method, an input variable and an output variable, the sensitivity index which is a 1D NumPy array can be accessed through indices.method_name[output_name][output_component][input_name].

Return type:

dict[str, FirstOrderIndicesType | SecondOrderIndicesType]

compute_samples(disciplines, parameter_space, n_samples, output_names=(), algo='', algo_settings=mappingproxy({}), backup_settings=None, formulation_name='MDF', **formulation_settings)

Compute the samples for the estimation of the sensitivity indices.

Parameters:

• disciplines (Collection[Discipline]) -- The discipline or disciplines to use for the analysis.

• parameter_space (ParameterSpace) -- A parameter space.

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

• output_names (Iterable[str]) --

  The disciplines' outputs to be considered for the analysis. If empty, use all the outputs.

  By default it is set to ().

• algo (str) --

  The name of the DOE algorithm. If empty, use the BaseSensitivityAnalysis.DEFAULT_DRIVER.

  By default it is set to "".

• algo_settings (Mapping[str, DriverSettingType]) --

  The settings of the DOE algorithm.

  By default it is set to {}.

• backup_settings (BackupSettings | None) -- The settings of the backup file to store the evaluations if any.

• formulation_name (str) --

  The name of the BaseMDOFormulation to sample the disciplines.

  By default it is set to "MDF".

• **formulation_settings (Any) -- The settings of the BaseMDOFormulation.

Returns:

The samples for the estimation of the sensitivity indices.

Return type:

IODataset

plot(output, input_names=(), title='', save=True, show=False, file_path='', file_format='')

Plot the sensitivity indices.

Parameters:

• output (VariableType) -- 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.

• input_names (Iterable[str]) --

  The input variables for which to display the sensitivity indices. If empty, display all the input variables.

  By default it is set to ().

• title (str) --

  The title of the plot, if any.

  By default it is set to "".

• 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 (str | Path) --

  A file path. Either a complete file path, a directory name or a file name. If empty, 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 "".

• file_format (str) --

  A file format, e.g. 'png', 'pdf', 'svg', ... Used when file_path does not have any extension. If empty, use a default file extension.

  By default it is set to "".

Returns:

The plot figure.

Return type:

DatasetPlot | Figure

plot_bar(outputs=(), input_names=(), standardize=False, title='', save=True, show=False, file_path='', directory_path='', file_name='', file_format='', sort=True, sorting_output='', **settings)

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 (OutputsType) --

  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 empty, use the default outputs.

  By default it is set to ().

• input_names (Iterable[str]) --

  The input variables for which to display the sensitivity indices. If empty, display all the input variables.

  By default it is set to ().

• standardize (bool) --

  Whether to scale the indices to \([0,1]\).

  By default it is set to False.

• title (str) --

  The title of the plot, if any.

  By default it is set to "".

• 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 (str | Path) --

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

  By default it is set to "".

• directory_path (str | Path) --

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

  By default it is set to "".

• file_name (str) --

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

  By default it is set to "".

• file_format (str) --

  A file extension, e.g. 'png', 'pdf', 'svg', ... If None, use a default file extension.

  By default it is set to "".

• sort (bool) --

  Whether to sort the input variables by decreasing order of the sensitivity indices associated with the sorting output variable.

  By default it is set to True.

• sorting_output (VariableType) --

  The sorting output variable If empty, use the first one.

  By default it is set to "".

• **settings (int) -- The settings to instantiate the BarPlot.

Returns:

A bar chart representing the sensitivity indices.

Return type:

BarPlot

plot_comparison(indices, output, input_names=(), title='', use_bar_plot=True, save=True, show=False, file_path='', directory_path='', file_name='', file_format='', **settings)

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[BaseSensitivityAnalysis]) -- The sensitivity indices.

• output (VariableType) -- 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.

• input_names (Iterable[str]) --

  The input variables for which to display the sensitivity indices. If empty, display all the input variables.

  By default it is set to ().

• title (str) --

  The title of the plot, if any.

  By default it is set to "".

• 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 (str | Path) --

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

  By default it is set to "".

• directory_path (str | Path) --

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

  By default it is set to "".

• file_name (str) --

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

  By default it is set to "".

• file_format (str) --

  A file format, e.g. 'png', 'pdf', 'svg', ... If empty, use a default file extension.

  By default it is set to "".

• **settings (bool) -- The settings passed to the underlying DatasetPlot.

Returns:

A graph comparing sensitivity indices.

Return type:

BarPlot | RadarChart

plot_field(output, mesh=None, input_names=(), standardize=False, title='', save=True, show=False, file_path='', directory_path='', file_name='', file_format='', properties=mappingproxy({}))

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 (VariableType) -- The output for which to display sensitivity indices, either a name or a tuple of the form (name, component) where (name, component) is used to sort the inputs. If it is a name, its first component is considered.

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

• input_names (Iterable[str]) --

  The input variables for which to display the sensitivity indices. If empty, display all the input variables.

  By default it is set to ().

• standardize (bool) --

  Whether to scale the indices to \([0,1]\).

  By default it is set to False.

• title (str) --

  The title of the plot, if any.

  By default it is set to "".

• 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 (str | Path) --

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

  By default it is set to "".

• directory_path (str | Path) --

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

  By default it is set to "".

• file_name (str) --

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

  By default it is set to "".

• file_format (str) --

  A file extension, e.g. 'png', 'pdf', 'svg', ... If empty, use a default file extension.

  By default it is set to "".

• properties (Mapping[str, DatasetPlotPropertyType]) --

  The general properties of a DatasetPlot.

  By default it is set to {}.

Returns:

A bar plot representing the sensitivity indices.

Raises:

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

Return type:

Curves | Surfaces

plot_radar(outputs=(), input_names=(), standardize=False, title='', save=True, show=False, file_path='', directory_path='', file_name='', file_format='', min_radius=None, max_radius=None, sort=True, sorting_output='', **settings)

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 (OutputsType) --

  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 empty, use the default outputs.

  By default it is set to ().

• input_names (Iterable[str]) --

  The input variables for which to display the sensitivity indices. If empty, display all the input variables.

  By default it is set to ().

• standardize (bool) --

  Whether to scale the indices to \([0,1]\).

  By default it is set to False.

• title (str) --

  The title of the plot, if any.

  By default it is set to "".

• 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 (str | Path) --

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

  By default it is set to "".

• directory_path (str | Path) --

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

  By default it is set to "".

• file_name (str) --

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

  By default it is set to "".

• file_format (str) --

  A file extension, e.g. 'png', 'pdf', 'svg', ... If empty, use a default file extension.

  By default it is set to "".

• min_radius (float | None) -- The minimal radial value. If None, from data.

• max_radius (float | None) -- The maximal radial value. If None, from data.

• sort (bool) --

  Whether to sort the input variables by decreasing order of the sensitivity indices associated with the sorting output variable.

  By default it is set to True.

• sorting_output (VariableType) --

  The sorting output variable If empty, use the first one.

  By default it is set to "".

• **settings (bool | int) -- The settings to instantiate the RadarChart.

Returns:

A radar chart representing the sensitivity indices.

Return type:

RadarChart

sort_input_variables(output)

Return the input variables sorted in descending order.

Parameters:

output (VariableType) -- Either a tuple as (output_name, output_component) or an output name; in the second case, use the first output component.

Returns:

The names of the inputs sorted by cumulative sensitivity index, which is the sum of the absolute values of the sensitivity indices associated to the different components of an input.

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, ndarray[Any, dtype[floating[Any]]]]]]) -- The indices to be standardized.

Returns:

The standardized indices.

Return type:

dict[str, list[dict[str, ndarray[Any, dtype[floating[Any]]]]]]

to_dataset()

Convert BaseSensitivityAnalysis.indices into a Dataset.

Returns:

The sensitivity indices.

Return type:

Dataset

dataset: IODataset | None

The dataset containing the discipline evaluations.

The samples must be either passed at instantiation or generated with compute_samples().

property default_output_names: list[str]

The default outputs of interest.

property indices: SensitivityIndices

The sensitivity indices.

Given a sensitivity method, an input variable and an output variable, the sensitivity index which is a 1D NumPy array can be accessed through indices.method_name[output_name][output_component][input_name].

property input_names: list[str]

The names of the inputs.

property main_indices: dict[str, list[dict[str, ndarray[Any, dtype[floating[Any]]]]]]

The main sensitivity indices.

Given an input variable and an output variable, the sensitivity index which is a 1D NumPy array can be accessed through main_indices[output_name][output_component][input_name].

main_method: Method

The name of the main sensitivity analysis method.

Examples

See the examples about sensitivity analysis.

Architecture