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.
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.
A
ProblemSpec
must be accepted as its first argument. This can simply be defined as a dictionary following the same format as outlined above.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()
In addition to the basic plot()
command, SALib can also produce a basic
heatmap.
sp.heatmap()
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:
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()
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.