pyuncertainnumber.sensitivity.sobol_analysis

Functions

sobol_analysis(x, f[, output_names, plot_results])

Performs a Sobol sensitivity analysis using the SALibe library.

Module Contents

pyuncertainnumber.sensitivity.sobol_analysis.sobol_analysis(x: list, f: Callable, output_names=None, plot_results: bool = True, **kwargs)

Performs a Sobol sensitivity analysis using the SALibe library.

Parameters:

  • x (list) – A list of UncertainNumber objects defining the input variables.

  • f (Callable) – The model function to be analyzed.

  • output_names (list, optional) – A list of strings to name the model outputs. Defaults to None.

  • plot_results (bool, optional) – If True, generates and displays plots of the results. Defaults to True.

  • **kwargs – Additional keyword arguments to pass to SALib’s sample and analyze functions. For example, N (the number of samples) must be a power of 2 (e.g., 1024, 2048) and defaults to 1024.

Returns:

A dictionary where keys are the output names and values are the

corresponding SALib analysis result objects.

Return type:

dict

Tip

This function is designed to work with a list of UncertainNumber objects that are defined as distributions. It evaluates the sensitivity of a model function f, which can have single or multiple outputs, to these inputs.

The code performs the following steps:

  1. Problem Definition: A SALib problem dictionary is constructed from the input list X of UncertainNumber objects. This dictionary defines the variables, their names, distributions, and parameters.

  2. Vectorization Auto-Detection: The function automatically probes the model function f to determine if it is “vectorized” (i.e., can process all samples at once with NumPy) or “non-vectorized” (processes one sample at a time). This allows for flexible use without needing to modify the model function.

  3. Direct Sampling: Input samples are generated using SALib.sample.sobol.sample. This function is passed the problem definition directly. Important Note: When using this direct method, SALib performs a linear scaling of the Sobol sequence from the [0, 1] domain to the bounds provided. It does not perform a distributional transformation (e.g., using the inverse CDF). For a ‘gaussian’ distribution defined with bounds [mean, std_dev], the generated samples will be uniformly distributed between mean and std_dev, not normally distributed.

  4. Model Evaluation: The model f is evaluated using the generated samples. The evaluation is performed efficiently if the model is vectorized, or iteratively (with a progress bar) if it is not.

  5. Output Handling: The function gracefully handles models that return single or multiple outputs, normalizing them for analysis.

  6. Sobol Analysis: For each model output, SALib.analyze.sobol.analyze is called to compute the first-order (S1), second-order (S2), and total-order (ST) sensitivity indices.

  7. Plotting: If plot_results is True, bar charts of the S1 and ST indices are generated for each output.

Example

>>> from pyuncertain import UncertainNumber as UN
>>>
>>> # 1. Define uncertain inputs
>>> inputs = [
...     UN(name='x1', essence='distribution', distribution_parameters=["uniform", (0, 1)]),
...     UN(name='x2', essence='distribution', distribution_parameters=["gaussian", (0.5, 0.1)])
... ]
>>>
>>> # 2. Define a model function (non-vectorized)
>>> def my_model(x):
...     return x[0]**2 + x[1]
>>>
>>> # 3. Run the analysis
>>> results = sobol_analysis(inputs, my_model, print_to_console = True, plot_results: bool = True, N=512)
>>>
>>> # 4. Print results for the first output
>>> results['Output_1']
>>>