Ctrl+K

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.

\[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 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:

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 ProblemSpec interface.

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, \(x_1, x_2, x_3\) where \(x_i \in [-\pi, \pi]\). In SALib, we define a dict which holds the names of the inputs, and the bounds on each input. Optionally, the expected output(s) can also be named.

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 ProblemSpec simply wraps around a dict.

Here, the default is to assume all inputs are uniformly distributed.

See Advanced Examples on how to provide further details, including alternate distributions.

Note

If outputs is not provided, then SALib will automatically create generic names.

Y for a single output 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

(
    sp.sample_sobol(1024)
    .evaluate(Ishigami.evaluate)
    .analyze_sobol()
)

That said, each step can be run individually. Note that the sample_ and analyze_ methods are shown with default arguments.

sp.sample_sobol(1024, calc_second_order=True)
sp.evaluate(Ishigami.evaluate)
sp.analyze_sobol(print_to_console=False, calc_second_order=True)

The samples, results, and results of analysis are all held inside the sp object. If needed, these may be extracted via their respective attributes.

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 sp.sample_[name of method]

  • Likewise, for analysis methods use 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 calc_second_order).

sp.sample_sobol(1024, calc_second_order=True)

If we run sp.samples.shape, we will see the matrix is 8192 by 3. In other words, the Sobol’ sampler generated \(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 calc_second_order=False will exclude second-order indices, resulting in a smaller sample matrix with \(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 sp.sample method is also available, allowing use of your own sampling function.

sp.sample(my_sampler, *args, **kwargs)

The provided function must follow two requirements.

  1. A 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:

sp.set_samples(X)

where X is a numpy array.

Note

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.

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 evaluate function that looks something like:

def evaluate(X: np.ndarray, A: float = 7.0, B: float = 0.1):

The actual implementation can be seen here.

Note that the inputs (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: 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:

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:

np.savetxt("param_values.txt", sp.samples)

Each line in 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:

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.

sp.analyze_sobol()

We see an overview of the results once we print out the interface:

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 ST, S1, and 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:

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.

total_Si, first_Si, second_Si = Si.to_df()

If the sample was created with calc_second_order=False then the second order sensitivities will not be returned

total_Si, first_Si = Si.to_df()

For multi-output models, sensitivity results for individual outputs can be extracted:

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.

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 matplotlib.

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()
../_images/example_mod_plot.svg

In addition to the basic plot() command, SALib can also produce a basic heatmap.

sp.heatmap()
../_images/example_heatmap_plot.svg

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:

\[f(x) = a + b x^2\]

The parameters \(a\) and \(b\) will be subject to the sensitivity analysis, but \(x\) will be not.

We start with a set of imports:

import numpy as np
import matplotlib.pyplot as plt

from SALib import ProblemSpec

and define the parabola:

def parabola(x, a, b):
    """Return y = a + b*x**2."""
    return a + b*x**2

The dict describing the problem contains therefore only \(a\) and \(b\):

sp = ProblemSpec({
    'names': ['a', 'b'],
    'bounds': [[0, 1]]*2,
})

The triad of sampling, evaluating and analysing becomes:

# 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 \(x\) separately.

Now we can extract the first-order Sobol indices for each bin of \(x\) and plot:

# 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()
../_images/example_parabola.svg

With the help of the plots, we interpret the Sobol indices. At \(x=0\), the variation in \(y\) can be explained to 100 % by parameter \(a\) as the contribution to \(y\) from \(b x^2\) vanishes. With larger \(|x|\), the contribution to the variation from parameter \(b\) increases and the contribution from parameter \(a\) decreases.

On this page
Show Source