pyuncertainnumber.sensitivity.sobol_analysis
============================================

.. py:module:: pyuncertainnumber.sensitivity.sobol_analysis


Functions
---------

.. autoapisummary::

   pyuncertainnumber.sensitivity.sobol_analysis.sobol_analysis


Module Contents
---------------

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

   Performs a Sobol sensitivity analysis using the SALibe library.

   :param x: A list of ``UncertainNumber`` objects defining the input variables.
   :type x: list
   :param f: The model function to be analyzed.
   :type f: Callable
   :param output_names: A list of strings to name the model outputs.
                        Defaults to None.
   :type output_names: list, optional
   :param plot_results: If True, generates and displays plots of the
                        results. Defaults to True.
   :type plot_results: bool, optional
   :param \*\*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.
   :rtype: 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.

   .. rubric:: 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']
   >>>