====== SALib Interface Basics ====== The earlier example is repeated on this page with the SALib `ProblemSpec` interface. The interface provides an object-oriented approach to using SALib which some may find easier to use. Note that the interface does add computational overhead (thereby increasing runtimes) as it provides additional checks for users. Developers who wish to integrate SALib into their own work may wish to use the core API as detailed in the first example instead. The Ishigami function --------------------- As a reminder, we will perform a Sobol' sensitivity analysis of the Ishigami function, shown below. .. math:: f(x) = \sin(x_1) + a \sin^2(x_2) + b x_3^4 \sin(x_1) The ProblemSpec Interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ SALib provides a single interface from which all methods can be accessed. The interface is called the :code:`ProblemSpec` (the Problem Specification). One advantage to the interface is the method chaining approach which offers a concise workflow. The sampling, evaluation and analysis trifecta can be run with: .. code:: python import numpy as np from SALib.test_functions import Ishigami from SALib import ProblemSpec sp = ProblemSpec({ "names": ["x1", "x2", "x3"], "groups": None, "bounds": [[-np.pi, np.pi]] * 3, "outputs": ["Y"], }) ( sp.sample_sobol(1024) .evaluate(Ishigami.evaluate) .analyze_sobol() ) total_Si, first_Si, second_Si = sp.to_df() sp.plot() sp.heatmap() Each step in the above is outlined in the sections below. Importing SALib ~~~~~~~~~~~~~~~ First, the necessary packages are imported. Here, we import numpy as well as the Ishigami test function (to use for this example) and the :code:`ProblemSpec` interface. .. code:: python import numpy as np from SALib.test_functions import Ishigami from SALib import ProblemSpec Defining the Model Inputs ~~~~~~~~~~~~~~~~~~~~~~~~~ Next, we must define the model inputs. The Ishigami function has three inputs, :math:`x_1, x_2, x_3` where :math:`x_i \in [-\pi, \pi]`. In SALib, we define a :code:`dict` which holds the names of the inputs, and the bounds on each input. Optionally, the expected output(s) can also be named. .. code:: python sp = ProblemSpec({ 'names': ['x1', 'x2', 'x3'], 'bounds': [ [-np.pi, np.pi], # bounds for x1 [-np.pi, np.pi], # ... x2 [-np.pi, np.pi] # ... x3 ], 'outputs': ['Y'] }) As seen above, the :code:`ProblemSpec` simply wraps around a :code:`dict`. Here, the default is to assume all inputs are uniformly distributed. See :doc:`advanced` on how to provide further details, including alternate distributions. .. note:: If :code:`outputs` is not provided, then SALib will automatically create generic names. :code:`Y` for a single output :code:`Y1, Y2, ... Yn` for multiple outputs Method Chaining ~~~~~~~~~~~~~~~ Since we are performing a Sobol' sensitivity analysis, we need to generate samples using the Sobol' sampler, run the model, then analyze the outputs. In the example above, all the steps are expressed as a `method chain `_ .. code:: python ( sp.sample_sobol(1024) .evaluate(Ishigami.evaluate) .analyze_sobol() ) That said, each step can be run individually. Note that the :code:`sample_` and :code:`analyze_` methods are shown with default arguments. .. code:: python sp.sample_sobol(1024, calc_second_order=True) sp.evaluate(Ishigami.evaluate) sp.analyze_sobol(print_to_console=False, calc_second_order=True) The :code:`samples`, :code:`results`, and results of :code:`analysis` are all held inside the :code:`sp` object. If needed, these may be extracted via their respective attributes. .. code:: python X = sp.samples y = sp.results S = sp.analysis Internally, all data is handled as a numpy array/matrix. .. tip:: All sampling, evaluation and analysis methods may be accessed through the ProblemSpec interface and follow a standard pattern. - Sampling methods can be accessed with :code:`sp.sample_[name of method]` - Likewise, for analysis methods use :code:`sp.analyze_[name of method]` See the documentation of each method for further information. Generating Samples ~~~~~~~~~~~~~~~~~~ In this example we are using the Sobol' sampling method (shown below with the default value for :code:`calc_second_order`). .. code:: python sp.sample_sobol(1024, calc_second_order=True) If we run :code:`sp.samples.shape`, we will see the matrix is 8192 by 3. In other words, the Sobol' sampler generated :math:`N*(2D+2)` samples, where in this example N is 1024 (the argument we supplied) and D is 3 (the number of model inputs). The keyword argument :code:`calc_second_order=False` will exclude second-order indices, resulting in a smaller sample matrix with :math:`N*(D+2)` rows instead. .. note:: Specific sampling methods have their own requirements and behaviours. The documentation for each method lists a brief overview and includes references to provide further details. A generic :code:`sp.sample` method is also available, allowing use of your own sampling function. .. code:: python sp.sample(my_sampler, *args, **kwargs) The provided function must follow two requirements. 1. A :code:`ProblemSpec` must be accepted as its first argument. This can simply be defined as a dictionary following the same format as outlined above. 2. The function must return a numpy array. If a sample has already been defined, this can be provided to the interface like so: .. code:: python sp.set_samples(X) where :code:`X` is a numpy array. .. note:: :code:`sp.set_results(Y)` can be used to set existing results. .. warning:: Care must be taken to avoid inappropriately mix-and-matching sampling and analysis methods. For example, Sobol' analysis must be conducted with a Sobol' sample. Running a Model ~~~~~~~~~~~~~~~ If the model is written in Python, and is written such that it can accept a numpy array as an input in its first position, then it may be called directly with the interface. Here, we use the Ishigami function as an example. .. code:: python sp.evaluate(Ishigami.evaluate) .. note:: SALib also supports parallel model evaluation with `sp.evaluate_parallel()`. It is assumed that all results can be held in memory. The Ishigami module provides an :code:`evaluate` function that looks something like: .. code:: python def evaluate(X: np.ndarray, A: float = 7.0, B: float = 0.1): The actual implementation can be seen `here `_. Note that the inputs (:code:`X`) is the first argument. .. tip:: For user-provided models, a wrapper can be written. A wrapper is a function that accepts parameters in the expected order, then runs the model itself. See also: :ref:`Another Example` , `functools.partial `_ Note that SALib does not require direct interaction with the model. If the model is written in Python, then it may be run manually without SALib. Generally, you will loop over each sample input and evaluate the model: .. code:: python Y = np.zeros([param_values.shape[0]]) for i, X in enumerate(param_values): Y[i] = evaluate_model(X) # Provide the results to the interface sp.set_results(Y) If the model is not written in Python, then the samples can be saved to a text file: .. code:: python np.savetxt("param_values.txt", sp.samples) Each line in :code:`param_values.txt` is one input to the model. The output from the model should be saved to another file with a similar format: one output on each line. The outputs can then be loaded with: .. code:: python Y = np.loadtxt("outputs.txt", float) # Provide the results to the interface sp.set_results(Y) Perform Analysis ~~~~~~~~~~~~~~~~ With the model outputs loaded, we can finally compute the sensitivity indices. In this example, we use Sobol' analysis, which will compute first, second, and total-order indices. .. code:: python sp.analyze_sobol() We see an overview of the results once we print out the interface: .. code:: python print(sp) Samples: 3 parameters: ['x1', 'x2', 'x3'] 8192 evaluations Outputs: 1 outputs: ['Y'] 8192 evaluations Analysis: ST ST_conf x1 0.557271 0.078640 x2 0.442311 0.040564 x3 0.247103 0.025728 S1 S1_conf x1 0.317728 0.060368 x2 0.442253 0.056459 x3 0.002556 0.054109 S2 S2_conf (x1, x2) -0.000604 0.071442 (x1, x3) 0.247521 0.096797 (x2, x3) -0.002954 0.072420 Here :code:`ST`, :code:`S1`, and :code:`S2` relate to the total, first-order, and second-order sensitivity indices respectively. Those ending with `_conf` indicate the corresponding confidence intervals, typically with a confidence level of 95%. We see that x1 and x2 exhibit first-order sensitivities but x3 appears to have no first-order effects. If the total-order indices are substantially larger than the first-order indices, then there is likely higher-order interactions occurring. We can look at the second-order indices to see these higher-order interactions: .. code:: python y_S2 = sp.analysis['S2'] print("x1-x2:", y_S2[0,1]) print("x1-x3:", y_S2[0,2]) print("x2-x3:", y_S2[1,2]) x1-x2: 0.0092542 x1-x3: 0.2381721 x2-x3: -0.0048877 Results can also be extracted as Pandas DataFrames for further analysis. .. code:: python total_Si, first_Si, second_Si = Si.to_df() If the sample was created with :code:`calc_second_order=False` then the second order sensitivities will not be returned .. code:: python total_Si, first_Si = Si.to_df() For multi-output models, sensitivity results for individual outputs can be extracted: .. code:: python sp.analysis['Y1']['S1'] # First order for Y1 sp.analysis['Y2']['S2'] # Second order for Y2 Basic Plotting ~~~~~~~~~~~~~~~~ Basic plotting facilities are provided for convenience. .. code:: python Si.plot() All plotting methods will return matplotlib axes objects to allow later adjustment. In the example below, the figure is created, the y-axis for the first subplot is set to use log scale, and the figure size is adjusted with :code:`matplotlib`. .. code:: python import matplotlib.pyplot as plt axes = sp.plot() axes[0].set_yscale('log') fig = plt.gcf() # get current figure fig.set_size_inches(10, 4) plt.tight_layout() .. figure:: ../assets/example_mod_plot.svg :width: 800 :align: center In addition to the basic :code:`plot()` command, SALib can also produce a basic heatmap. .. code:: python sp.heatmap() .. figure:: ../assets/example_heatmap_plot.svg :width: 800 :align: center .. _Another example: Another Example --------------- When the model you want to analyse depends on parameters that are not part of the sensitivity analysis, like position or time, the analysis can be performed for each time/position "bin" separately. This can be useful for the purpose of factor mapping, to identify where in parameter space the model is sensitive to. Consider the example of a parabola: .. math:: f(x) = a + b x^2 The parameters :math:`a` and :math:`b` will be subject to the sensitivity analysis, but :math:`x` will be not. We start with a set of imports: .. code:: python import numpy as np import matplotlib.pyplot as plt from SALib import ProblemSpec and define the parabola: .. code:: python def parabola(x, a, b): """Return y = a + b*x**2.""" return a + b*x**2 The :code:`dict` describing the problem contains therefore only :math:`a` and :math:`b`: .. code:: python sp = ProblemSpec({ 'names': ['a', 'b'], 'bounds': [[0, 1]]*2, }) The triad of sampling, evaluating and analysing becomes: .. code:: python # Create "bins" of x x = np.linspace(-1, 1, 100) # Create wrapper (runs each a, b combination separately) def wrapped_parabola(ab, x=x): y = np.zeros((ab.shape[0], x.shape[0])) for i, (a, b) in enumerate(ab): y[i,:] = parabola(x, a, b) return y ( sp.sample_sobol(2**6) .evaluate(wrapped_parabola) .analyze_sobol() ) Note how we analyzed for each :math:`x` separately. Now we can extract the first-order Sobol indices for each bin of :math:`x` and plot: .. code:: python # Get first order sensitivities for all outputs S1s = np.array([sp.analysis[_y]['S1'] for _y in sp['outputs']]) # Get model outputs y = sp.results # Set up figure fig = plt.figure(figsize=(10, 6), constrained_layout=True) gs = fig.add_gridspec(2, 2) ax0 = fig.add_subplot(gs[:, 0]) ax1 = fig.add_subplot(gs[0, 1]) ax2 = fig.add_subplot(gs[1, 1]) # Populate figure subplots for i, ax in enumerate([ax1, ax2]): ax.plot(x, S1s[:, i], label=r'S1$_\mathregular{{{}}}$'.format(problem["names"][i]), color='black') ax.set_xlabel("x") ax.set_ylabel("First-order Sobol index") ax.set_ylim(0, 1.04) ax.yaxis.set_label_position("right") ax.yaxis.tick_right() ax.legend(loc='upper right') ax0.plot(x, np.mean(y, axis=0), label="Mean", color='black') # in percent prediction_interval = 95 ax0.fill_between(x, np.percentile(y, 50 - prediction_interval/2., axis=0), np.percentile(y, 50 + prediction_interval/2., axis=0), alpha=0.5, color='black', label=f"{prediction_interval} % prediction interval") ax0.set_xlabel("x") ax0.set_ylabel("y") ax0.legend(title=r"$y=a+b\cdot x^2$", loc='upper center')._legend_box.align = "left" plt.show() .. figure:: ../assets/example_parabola.svg :width: 800 :align: center With the help of the plots, we interpret the Sobol indices. At :math:`x=0`, the variation in :math:`y` can be explained to 100 % by parameter :math:`a` as the contribution to :math:`y` from :math:`b x^2` vanishes. With larger :math:`|x|`, the contribution to the variation from parameter :math:`b` increases and the contribution from parameter :math:`a` decreases.