SALib - Sensitivity Analysis Library in Python¶

https://coveralls.io/repos/github/SALib/SALib/badge.svg?branch=master

http://joss.theoj.org/papers/431262803744581c1d4b6a95892d3343/status.svg

Python implementations of commonly used sensitivity analysis methods, including Sobol, Morris, and FAST methods. Useful in systems modeling to calculate the effects of model inputs or exogenous factors on outputs of interest.

Supported Methods¶

Sobol Sensitivity Analysis ([Sobol 2001], [Saltelli 2002], [Saltelli et al. 2010])
Method of Morris, including groups and optimal trajectories ([Morris 1991], [Campolongo et al. 2007])
Fourier Amplitude Sensitivity Test (FAST) ([Cukier et al. 1973], [Saltelli et al. 1999])
Random Balance Designs - Fourier Amplitude Sensitivity Test (RBD-FAST) ([Tarantola et al. 2006], [Elmar Plischke 2010], [Tissot et al. 2012])
Delta Moment-Independent Measure ([Borgonovo 2007], [Plischke et al. 2013])
Derivative-based Global Sensitivity Measure (DGSM) ([Sobol and Kucherenko 2009])
Fractional Factorial Sensitivity Analysis ([Saltelli et al. 2008])
High Dimensional Model Representation ([Li et al. 2010])

Getting Started¶

Installing SALib¶

To install the latest stable version of SALib using pip, together with all the dependencies, run the following command:

pip install SALib

To install the latest development version of SALib, run the following commands. Note that the development version may be unstable and include bugs. We encourage users use the latest stable version.

git clone https://github.com/SALib/SALib.git
cd SALib
python setup.py develop

Installing Prerequisite Software¶

SALib requires NumPy, SciPy, and matplotlib installed on your computer. Using pip, these libraries can be installed with the following command:

pip install numpy
pip install scipy
pip install matplotlib

The packages are normally included with most Python bundles, such as Anaconda and Canopy. In any case, they are installed automatically when using pip or setuptools to install SALib.

Testing Installation¶

To test your installation of SALib, run the following command

pytest

Alternatively, if you’d like also like a taste of what SALib provides, start a new interactive Python session and copy/paste the code below.

from SALib.sample import saltelli
from SALib.analyze import sobol
from SALib.test_functions import Ishigami
import numpy as np

# Define the model inputs
problem = {
    'num_vars': 3,
    'names': ['x1', 'x2', 'x3'],
    'bounds': [[-3.14159265359, 3.14159265359],
               [-3.14159265359, 3.14159265359],
               [-3.14159265359, 3.14159265359]]
}

# Generate samples
param_values = saltelli.sample(problem, 1000)

# Run model (example)
Y = Ishigami.evaluate(param_values)

# Perform analysis
Si = sobol.analyze(problem, Y, print_to_console=True)

# Print the first-order sensitivity indices
print(Si['S1'])

If installed correctly, the last line above will print three values, similar to [ 0.30644324 0.44776661 -0.00104936].

Basics¶

What is Sensitivity Analysis?¶

According to Wikipedia, sensitivity analysis is “the study of how the uncertainty in the output of a mathematical model or system (numerical or otherwise) can be apportioned to different sources of uncertainty in its inputs.” The sensitivity of each input is often represented by a numeric value, called the sensitivity index. Sensitivity indices come in several forms:

First-order indices: measures the contribution to the output variance by a single model input alone.
Second-order indices: measures the contribution to the output variance caused by the interaction of two model inputs.
Total-order index: measures the contribution to the output variance caused by a model input, including both its first-order effects (the input varying alone) and all higher-order interactions.

What is SALib?¶

SALib is an open source library written in Python for performing sensitivity analysis. SALib provides a decoupled workflow, meaning it does not directly interface with the mathematical or computational model. Instead, SALib is responsible for generating the model inputs, using one of the sample functions, and computing the sensitivity indices from the model outputs, using one of the analyze functions. A typical sensitivity analysis using SALib follows four steps:

Determine the model inputs (parameters) and their sample range.
Run the sample function to generate the model inputs.
Evaluate the model using the generated inputs, saving the model outputs.
Run the analyze function on the outputs to compute the sensitivity indices.

SALib provides several sensitivity analysis methods, such as Sobol, Morris, and FAST. There are many factors that determine which method is appropriate for a specific application, which we will discuss later. However, for now, just remember that regardless of which method you choose, you need to use only two functions: sample and analyze. To demonstrate the use of SALib, we will walk you through a simple example.

An Example¶

In this example, we will perform a Sobol’ sensitivity analysis of the Ishigami function, shown below. The Ishigami function is commonly used to test uncertainty and sensitivity analysis methods because it exhibits strong nonlinearity and nonmonotonicity.

\[f(x) = sin(x_1) + a sin^2(x_2) + b x_3^4 sin(x_1)\]

Importing SALib¶

The first step is the import the necessary libraries. In SALib, the sample and analyze functions are stored in separate Python modules. For example, below we import the saltelli sample function and the sobol analyze function. We also import the Ishigami function, which is provided as a test function within SALib. Lastly, we import numpy, as it is used by SALib to store the model inputs and outputs in a matrix.

from SALib.sample import saltelli
from SALib.analyze import sobol
from SALib.test_functions import Ishigami
import numpy as np

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 defining the number of inputs, the names of the inputs, and the bounds on each input, as shown below.

problem = {
    'num_vars': 3,
    'names': ['x1', 'x2', 'x3'],
    'bounds': [[-3.14159265359, 3.14159265359],
               [-3.14159265359, 3.14159265359],
               [-3.14159265359, 3.14159265359]]
}

Generate Samples¶

Next, we generate the samples. Since we are performing a Sobol’ sensitivity analysis, we need to generate samples using the Saltelli sampler, as shown below.

param_values = saltelli.sample(problem, 1000)

Here, param_values is a NumPy matrix. If we run param_values.shape, we see that the matrix is 8000 by 3. The Saltelli sampler generated 8000 samples. The Saltelli sampler generates \(N*(2D+2)\) samples, where in this example N is 1000 (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.

Run Model¶

As mentioned above, SALib is not involved in the evaluation of the mathematical or computational model. If the model is written in Python, then 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)

If the model is not written in Python, then the samples can be saved to a text file:

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

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)

In this example, we are using the Ishigami function provided by SALib. We can evaluate these test functions as shown below:

Y = Ishigami.evaluate(param_values)

Perform Analysis¶

With the model outputs loaded into Python, we can finally compute the sensitivity indices. In this example, we use sobol.analyze, which will compute first, second, and total-order indices.

Si = sobol.analyze(problem, Y)

Si is a Python dict with the keys "S1", "S2", "ST", "S1_conf", "S2_conf", and "ST_conf". The _conf keys store the corresponding confidence intervals, typically with a confidence level of 95%. Use the keyword argument print_to_console=True to print all indices. Or, we can print the individual values from Si as shown below.

print(Si['S1'])

[ 0.30644324  0.44776661 -0.00104936 ]

Here, we see that x1 and x2 exhibit first-order sensitivities but x3 appears to have no first-order effects.

print(Si['ST'])

[ 0.56013728  0.4387225   0.24284474]

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:

print "x1-x2:", Si['S2'][0,1]
print "x1-x3:", Si['S2'][0,2]
print "x2-x3:", Si['S2'][1,2]

x1-x2: 0.0155279
x1-x3: 0.25484902
x2-x3: -0.00995392

We can see there are strong interactions between x1 and x3. Some computing error will appear in the sensitivity indices. For example, we observe a negative value for the x2-x3 index. Typically, these computing errors shrink as the number of samples increases.

The output can then be converted to a Pandas DataFrame for further analysis.

..code:: python

total_Si, first_Si, second_Si = Si.to_df()

# Note that 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()

Basic Plotting¶

Basic plotting facilities are provided for convenience.

Si.plot()

The plot() method returns matplotlib axes objects to allow later adjustment.

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.

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.sample import saltelli
from SALib.analyze import sobol

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

problem = {
    'num_vars': 2,
    'names': ['a', 'b'],
    'bounds': [[0, 1]]*2
}

The triad of sampling, evaluating and analysing becomes:

# sample
param_values = saltelli.sample(problem, 2**6)

# evaluate
x = np.linspace(-1, 1, 100)
y = np.array([parabola(x, *params) for params in param_values])

# analyse
sobol_indices = [sobol.analyze(problem, Y) for Y in y.T]

Note how we analysed for each \(x\) separately.

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

S1s = np.array([s['S1'] for s in sobol_indices])

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])

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

Advanced Examples¶

Group sampling (Sobol and Morris methods only)¶

It is sometimes useful to perform sensitivity analysis on groups of input variables to reduce the number of model runs required, when variables belong to the same component of a model, or there is some reason to believe that they should behave similarly.

Groups can be specified in two ways for the Sobol and Morris methods.

First, as a fourth column in the parameter file:

# name lower_bound upper_bound group_name
P1 0.0 1.0 Group_1
P2 0.0 5.0 Group_2
P3 0.0 5.0 Group_2
...etc.

Or in the problem dictionary:

problem = {
    'groups': ['Group_1', 'Group_2', 'Group_2'],
    'names': ['x1', 'x2', 'x3'],
    'num_vars': 3,
    'bounds': [[-3.14, 3.14], [-3.14, 3.14], [-3.14, 3.14]]
}

groups is a list of strings specifying the group name to which each variable belongs. The rest of the code stays the same:

param_values = saltelli.sample(problem, 1000)
Y = Ishigami.evaluate(param_values)
Si = sobol.analyze(problem, Y, print_to_console=True)

But the output is printed by group:

Group S1 S1_conf ST ST_conf
Group_1 0.307834 0.066424 0.559577 0.082978
Group_2 0.444052 0.080255 0.667258 0.060871

Group_1 Group_2 S2 S2_conf
Group_1 Group_2 0.242964 0.124229

Generating alternate distributions¶

In Essential basic functionality, we generate a uniform sample of parameter space.

from SALib.sample import saltelli
from SALib.analyze import sobol
from SALib.test_functions import Ishigami
import numpy as np

problem = {
    'num_vars': 3,
    'names': ['x1', 'x2', 'x3'],
    'bounds': [[-3.14159265359, 3.14159265359],
               [-3.14159265359, 3.14159265359],
               [-3.14159265359, 3.14159265359]]
}

param_values = saltelli.sample(problem, 1000)

SALib is also capable of generating alternate sampling distributions by specifying a dists entry in the problem specification.

As implied in the basic example, a uniform distribution is the default.

When an entry for dists is not ‘unif’, the bounds entry does not indicate parameter bounds but sample-specific metadata.

bounds definitions for available distributions:

unif: uniform distribution

e.g. [-np.pi, np.pi] defines the lower and upper bounds
triang: triangular with width (scale) and location of peak.

Location of peak is in percentage of width. Lower bound assumed to be zero.

e.g. [3, 0.5] assumes 0 to 3, with a peak at 1.5
norm: normal distribution with mean and standard deviation
lognorm: lognormal with ln-space mean and standard deviation

An example specification is shown below:

problem = {
    'names': ['x1', 'x2', 'x3'],
    'num_vars': 3,
    'bounds': [[-np.pi, np.pi], [1.0, 0.2], [3, 0.5]],
    'groups': ['G1', 'G2', 'G1'],
    'dists': ['unif', 'lognorm', 'triang']
}

Concise API Reference¶

This page documents the sensitivity analysis methods supported by SALib.

FAST - Fourier Amplitude Sensitivity Test¶

SALib.sample.fast_sampler.sample(problem, N, M=4, seed=None)[source]

Generate model inputs for the extended Fourier Amplitude Sensitivity Test (eFAST).

Returns a NumPy matrix containing the model inputs required by the extended Fourier Amplitude sensitivity test. The resulting matrix contains N * D rows and D columns, where D is the number of parameters. The samples generated are intended to be used by SALib.analyze.fast.analyze().

Parameters:	problem (dict) – The problem definition N (int) – The number of samples to generate M (int) – The interference parameter, i.e., the number of harmonics to sum in the Fourier series decomposition (default 4)

References

[1]	Cukier, R.I., Fortuin, C.M., Shuler, K.E., Petschek, A.G., Schaibly, J.H., 1973. Study of the sensitivity of coupled reaction systems to uncertainties in rate coefficients. I theory. Journal of Chemical Physics 59, 3873–3878. https://doi.org/10.1063/1.1680571

[2]	Saltelli, A., S. Tarantola, and K. P.-S. Chan (1999). “A Quantitative Model-Independent Method for Global Sensitivity Analysis of Model Output.” Technometrics, 41(1):39-56, doi:10.1080/00401706.1999.10485594.

SALib.analyze.fast.analyze(problem, Y, M=4, num_resamples=100, conf_level=0.95, print_to_console=False, seed=None)[source]

Performs the extended Fourier Amplitude Sensitivity Test (eFAST) on model outputs.

Returns a dictionary with keys ‘S1’ and ‘ST’, where each entry is a list of size D (the number of parameters) containing the indices in the same order as the parameter file.

fast_sampler

Parameters:	problem (dict) – The problem definition Y (numpy.array) – A NumPy array containing the model outputs M (int) – The interference parameter, i.e., the number of harmonics to sum in the Fourier series decomposition (default 4) print_to_console (bool) – Print results directly to console (default False)

References

[1]	Cukier, R. I., C. M. Fortuin, K. E. Shuler, A. G. Petschek, and J. H. Schaibly (1973). “Study of the sensitivity of coupled reaction systems to uncertainties in rate coefficients.” J. Chem. Phys., 59(8):3873-3878, doi:10.1063/1.1680571.

[2]	Saltelli, A., S. Tarantola, and K. P.-S. Chan (1999). “A Quantitative Model-Independent Method for Global Sensitivity Analysis of Model Output.” Technometrics, 41(1):39-56, doi:10.1080/00401706.1999.10485594.

[3]	Pujol, G. (2006) fast99 - R sensitivity package https://github.com/cran/sensitivity/blob/master/R/fast99.R

Examples

>>> X = fast_sampler.sample(problem, 1000)
>>> Y = Ishigami.evaluate(X)
>>> Si = fast.analyze(problem, Y, print_to_console=False)

RBD-FAST - Random Balance Designs Fourier Amplitude Sensitivity Test¶

SALib.sample.latin.sample(problem, N, seed=None)[source]

Generate model inputs using Latin hypercube sampling (LHS).

Returns a NumPy matrix containing the model inputs generated by Latin hypercube sampling. The resulting matrix contains N rows and D columns, where D is the number of parameters.

Parameters:	problem (dict) – The problem definition N (int) – The number of samples to generate

References

[1]	McKay, M.D., Beckman, R.J., Conover, W.J., 1979. A comparison of three methods for selecting values of input variables in the analysis of output from a computer code. Technometrics 21, 239–245. https://doi.org/10.2307/1268522

[2]	Iman, R.L., Helton, J.C., Campbell, J.E., 1981. An Approach to Sensitivity Analysis of Computer Models: Part I—Introduction, Input Variable Selection and Preliminary Variable Assessment. Journal of Quality Technology 13, 174–183. https://doi.org/10.1080/00224065.1981.11978748

SALib.analyze.rbd_fast.analyze(problem, X, Y, M=10, num_resamples=100, conf_level=0.95, print_to_console=False, seed=None)[source]

Performs the Random Balanced Design - Fourier Amplitude Sensitivity Test (RBD-FAST) on model outputs.

Returns a dictionary with keys ‘S1’, where each entry is a list of size D (the number of parameters) containing the indices in the same order as the parameter file.

all samplers

Parameters:	problem (dict) – The problem definition X (numpy.array) – A NumPy array containing the model inputs Y (numpy.array) – A NumPy array containing the model outputs M (int) – The interference parameter, i.e., the number of harmonics to sum in the Fourier series decomposition (default 10) print_to_console (bool) – Print results directly to console (default False)

References

[1]	S. Tarantola, D. Gatelli and T. Mara (2006) “Random Balance Designs for the Estimation of First Order Global Sensitivity Indices”, Reliability Engineering and System Safety, 91:6, 717-727

[2]	Elmar Plischke (2010) “An effective algorithm for computing global sensitivity indices (EASI) Reliability Engineering & System Safety”, 95:4, 354-360. doi:10.1016/j.ress.2009.11.005

[3]	Jean-Yves Tissot, Clémentine Prieur (2012) “Bias correction for the estimation of sensitivity indices based on random balance designs.”, Reliability Engineering and System Safety, Elsevier, 107, 205-213. doi:10.1016/j.ress.2012.06.010

[4]	Jeanne Goffart, Mickael Rabouille & Nathan Mendes (2015) “Uncertainty and sensitivity analysis applied to hygrothermal simulation of a brick building in a hot and humid climate”, Journal of Building Performance Simulation. doi:10.1080/19401493.2015.1112430

Examples

>>> X = latin.sample(problem, 1000)
>>> Y = Ishigami.evaluate(X)
>>> Si = rbd_fast.analyze(problem, X, Y, print_to_console=False)

Method of Morris¶

SALib.sample.morris.sample(problem: Dict[KT, VT], N: int, num_levels: int = 4, optimal_trajectories: int = None, local_optimization: bool = True, seed: int = None) → numpy.ndarray[source]

Generate model inputs using the Method of Morris

Returns a NumPy matrix containing the model inputs required for Method of Morris. The resulting matrix has \((G+1)*T\) rows and \(D\) columns, where \(D\) is the number of parameters, \(G\) is the number of groups (if no groups are selected, the number of parameters). \(T\) is the number of trajectories \(N\), or optimal_trajectories if selected. These model inputs are intended to be used with SALib.analyze.morris.analyze().

Parameters:	problem (dict) – The problem definition N (int) – The number of trajectories to generate num_levels (int, default=4) – The number of grid levels (should be even) optimal_trajectories (int) – The number of optimal trajectories to sample (between 2 and N) local_optimization (bool, default=True) – Flag whether to use local optimization according to Ruano et al. (2012) Speeds up the process tremendously for bigger N and num_levels. If set to `False` brute force method is used, unless `gurobipy` is available seed (int) – Seed to generate a random number
Returns:	sample_morris – Returns a numpy.ndarray containing the model inputs required for Method of Morris. The resulting matrix has \((G/D+1)*N/T\) rows and \(D\) columns, where \(D\) is the number of parameters.
Return type:	numpy.ndarray

References

[1]	Ruano, M.V., Ribes, J., Seco, A., Ferrer, J., 2012. An improved sampling strategy based on trajectory design for application of the Morris method to systems with many input factors. Environmental Modelling & Software 37, 103–109. https://doi.org/10.1016/j.envsoft.2012.03.008

[2]	Morris, M.D., 1991. Factorial Sampling Plans for Preliminary Computational Experiments. Technometrics 33, 161–174. https://doi.org/10.1080/00401706.1991.10484804

[3]

Campolongo, F., Cariboni, J., Saltelli, A., 2007. An effective screening design for sensitivity analysis of large models. Environmental Modelling & Software, Modelling, computer-assisted simulations, and mapping of dangerous phenomena for hazard assessment 22, 1509–1518. https://doi.org/10.1016/j.envsoft.2006.10.004

SALib.analyze.morris.analyze(problem: Dict[KT, VT], X: numpy.ndarray, Y: numpy.ndarray, num_resamples: int = 100, conf_level: float = 0.95, print_to_console: bool = False, num_levels: int = 4, seed=None) → numpy.ndarray[source]

Perform Morris Analysis on model outputs.

Returns a dictionary with keys ‘mu’, ‘mu_star’, ‘sigma’, and ‘mu_star_conf’, where each entry is a list of parameters containing the indices in the same order as the parameter file.

morris

Parameters:

problem (dict) – The problem definition
X (numpy.array) – The NumPy matrix containing the model inputs of dtype=float
Y (numpy.array) – The NumPy array containing the model outputs of dtype=float
num_resamples (int) – The number of resamples used to compute the confidence intervals (default 1000)
conf_level (float) – The confidence interval level (default 0.95)
print_to_console (bool) – Print results directly to console (default False)
num_levels (int) – The number of grid levels, must be identical to the value passed to SALib.sample.morris (default 4)
seed (int) – Seed to generate a random number

Returns:

Si – A dictionary of sensitivity indices containing the following entries.

mu - the mean elementary effect
mu_star - the absolute of the mean elementary effect
sigma - the standard deviation of the elementary effect
mu_star_conf - the bootstrapped confidence interval
names - the names of the parameters

Return type:

dict

References

[1]	Morris, M. (1991). “Factorial Sampling Plans for Preliminary Computational Experiments.” Technometrics, 33(2):161-174, doi:10.1080/00401706.1991.10484804.

[2]	Campolongo, F., J. Cariboni, and A. Saltelli (2007). “An effective screening design for sensitivity analysis of large models.” Environmental Modelling & Software, 22(10):1509-1518, doi:10.1016/j.envsoft.2006.10.004.

Examples

>>> X = morris.sample(problem, 1000, num_levels=4)
>>> Y = Ishigami.evaluate(X)
>>> Si = morris.analyze(problem, X, Y, conf_level=0.95,
>>>                     print_to_console=True, num_levels=4)

Sobol Sensitivity Analysis¶

SALib.sample.saltelli.sample(problem: Dict[KT, VT], N: int, calc_second_order: bool = True, skip_values: int = 1024)[source]

Generates model inputs using Saltelli’s extension of the Sobol’ sequence.

Returns a NumPy matrix containing the model inputs using Saltelli’s sampling scheme. Saltelli’s scheme extends the Sobol’ sequence in a way to reduce the error rates in the resulting sensitivity index calculations. If calc_second_order is False, the resulting matrix has N * (D + 2) rows, where D is the number of parameters. If calc_second_order is True, the resulting matrix has N * (2D + 2) rows. These model inputs are intended to be used with SALib.analyze.sobol.analyze().

Raises a UserWarning in cases where sample sizes may be sub-optimal. The convergence properties of the Sobol’ sequence requires N < skip_values and that both N and skip_values are base 2 (e.g., N = 2^n).

Parameters:	problem (dict) – The problem definition N (int) – The number of samples to generate. Must be an exponent of 2 and < skip_values. calc_second_order (bool) – Calculate second-order sensitivities (default True) skip_values (int) – Number of points in Sobol’ sequence to skip (must be an exponent of 2).

References

[1]	Saltelli, A., 2002. Making best use of model evaluations to compute sensitivity indices. Computer Physics Communications 145, 280–297. https://doi.org/10.1016/S0010-4655(02)00280-1

[2]	Sobol’, I.M., 2001. Global sensitivity indices for nonlinear mathematical models and their Monte Carlo estimates. Mathematics and Computers in Simulation, The Second IMACS Seminar on Monte Carlo Methods 55, 271–280. https://doi.org/10.1016/S0378-4754(00)00270-6

[3]	Owen, A. B., 2020. On dropping the first Sobol’ point. arXiv:2008.08051 [cs, math, stat]. Available at: http://arxiv.org/abs/2008.08051 (Accessed: 20 April 2021).

[4]	Discussion: https://github.com/scipy/scipy/pull/10844

SALib.analyze.sobol.analyze(problem, Y, calc_second_order=True, num_resamples=100, conf_level=0.95, print_to_console=False, parallel=False, n_processors=None, seed=None)[source]

Perform Sobol Analysis on model outputs.

Returns a dictionary with keys ‘S1’, ‘S1_conf’, ‘ST’, and ‘ST_conf’, where each entry is a list of size D (the number of parameters) containing the indices in the same order as the parameter file. If calc_second_order is True, the dictionary also contains keys ‘S2’ and ‘S2_conf’.

saltelli

Parameters:

problem (dict) – The problem definition
Y (numpy.array) – A NumPy array containing the model outputs
calc_second_order (bool) – Calculate second-order sensitivities (default True)
num_resamples (int) – The number of resamples (default 100)
conf_level (float) – The confidence interval level (default 0.95)
print_to_console (bool) – Print results directly to console (default False)

References

[1]	Sobol, I. M. (2001). “Global sensitivity indices for nonlinear mathematical models and their Monte Carlo estimates.” Mathematics and Computers in Simulation, 55(1-3):271-280, doi:10.1016/S0378-4754(00)00270-6.

[2]	Saltelli, A. (2002). “Making best use of model evaluations to compute sensitivity indices.” Computer Physics Communications, 145(2):280-297, doi:10.1016/S0010-4655(02)00280-1.

[3]	Saltelli, A., P. Annoni, I. Azzini, F. Campolongo, M. Ratto, and S. Tarantola (2010). “Variance based sensitivity analysis of model output. Design and estimator for the total sensitivity index.” Computer Physics Communications, 181(2):259-270, doi:10.1016/j.cpc.2009.09.018.

Examples

>>> X = saltelli.sample(problem, 512)
>>> Y = Ishigami.evaluate(X)
>>> Si = sobol.analyze(problem, Y, print_to_console=True)

Delta Moment-Independent Measure¶

SALib.sample.latin.sample(problem, N, seed=None)[source]

Generate model inputs using Latin hypercube sampling (LHS).

Returns a NumPy matrix containing the model inputs generated by Latin hypercube sampling. The resulting matrix contains N rows and D columns, where D is the number of parameters.

Parameters:	problem (dict) – The problem definition N (int) – The number of samples to generate

References

[1]	McKay, M.D., Beckman, R.J., Conover, W.J., 1979. A comparison of three methods for selecting values of input variables in the analysis of output from a computer code. Technometrics 21, 239–245. https://doi.org/10.2307/1268522

[2]	Iman, R.L., Helton, J.C., Campbell, J.E., 1981. An Approach to Sensitivity Analysis of Computer Models: Part I—Introduction, Input Variable Selection and Preliminary Variable Assessment. Journal of Quality Technology 13, 174–183. https://doi.org/10.1080/00224065.1981.11978748

SALib.analyze.delta.analyze(problem: Dict[KT, VT], X: numpy.array, Y: numpy.array, num_resamples: int = 100, conf_level: float = 0.95, print_to_console: bool = False, seed: int = None) → Dict[KT, VT][source]

Perform Delta Moment-Independent Analysis on model outputs.

Returns a dictionary with keys ‘delta’, ‘delta_conf’, ‘S1’, and ‘S1_conf’, where each entry is a list of size D (the number of parameters) containing the indices in the same order as the parameter file.

all samplers

Parameters:

problem (dict) – The problem definition
X (numpy.matrix) – A NumPy matrix containing the model inputs
Y (numpy.array) – A NumPy array containing the model outputs
num_resamples (int) – The number of resamples when computing confidence intervals (default 10)
conf_level (float) – The confidence interval level (default 0.95)
print_to_console (bool) – Print results directly to console (default False)

References

[1]	Borgonovo, E. (2007). “A new uncertainty importance measure.” Reliability Engineering & System Safety, 92(6):771-784, doi:10.1016/j.ress.2006.04.015.

[2]	Plischke, E., E. Borgonovo, and C. L. Smith (2013). “Global sensitivity measures from given data.” European Journal of Operational Research, 226(3):536-550, doi:10.1016/j.ejor.2012.11.047.

Examples

>>> X = latin.sample(problem, 1000)
>>> Y = Ishigami.evaluate(X)
>>> Si = delta.analyze(problem, X, Y, print_to_console=True)

Derivative-based Global Sensitivity Measure (DGSM)¶

SALib.analyze.dgsm.analyze(problem, X, Y, num_resamples=100, conf_level=0.95, print_to_console=False, seed=None)[source]

Calculates Derivative-based Global Sensitivity Measure on model outputs.

Returns a dictionary with keys ‘vi’, ‘vi_std’, ‘dgsm’, and ‘dgsm_conf’, where each entry is a list of size D (the number of parameters) containing the indices in the same order as the parameter file.

finite_diff

Parameters:

problem (dict) – The problem definition
X (numpy.matrix) – The NumPy matrix containing the model inputs
Y (numpy.array) – The NumPy array containing the model outputs
num_resamples (int) – The number of resamples used to compute the confidence intervals (default 1000)
conf_level (float) – The confidence interval level (default 0.95)
print_to_console (bool) – Print results directly to console (default False)

References

[1]	Sobol, I. M. and S. Kucherenko (2009). “Derivative based global sensitivity measures and their link with global sensitivity indices.” Mathematics and Computers in Simulation, 79(10):3009-3017, doi:10.1016/j.matcom.2009.01.023.

Fractional Factorial¶

SALib.sample.ff.sample(problem, seed=None)[source]

Generates model inputs using a fractional factorial sample

Returns a NumPy matrix containing the model inputs required for a fractional factorial analysis. The resulting matrix has D columns, where D is smallest power of 2 that is greater than the number of parameters. These model inputs are intended to be used with SALib.analyze.ff.analyze().

The problem file is padded with a number of dummy variables called dummy_0 required for this procedure. These dummy variables can be used as a check for errors in the analyze procedure.

This algorithm is an implementation of that contained in Saltelli et al [Saltelli et al. 2008]

Parameters:	problem (dict) – The problem definition
Returns:	sample
Return type:	`numpy.array`

References

[1]	Saltelli, A., Ratto, M., Andres, T., Campolongo, F., Cariboni, J., Gatelli, D., Saisana, M., Tarantola, S., 2008. Global Sensitivity Analysis: The Primer. Wiley, West Sussex, U.K. https://dx.doi.org/10.1002/9780470725184

SALib.analyze.ff.analyze(problem, X, Y, second_order=False, print_to_console=False, seed=None)[source]

Perform a fractional factorial analysis

Returns a dictionary with keys ‘ME’ (main effect) and ‘IE’ (interaction effect). The techniques bulks out the number of parameters with dummy parameters to the nearest 2**n. Any results involving dummy parameters could indicate a problem with the model runs.

ff

Parameters:	problem (dict) – The problem definition X (numpy.matrix) – The NumPy matrix containing the model inputs Y (numpy.array) – The NumPy array containing the model outputs second_order (bool, default=False) – Include interaction effects print_to_console (bool, default=False) – Print results directly to console
Returns:	Si – A dictionary of sensitivity indices, including main effects `ME`, and interaction effects `IE` (if `second_order` is True)
Return type:	dict

References

[1]	Saltelli, A., Ratto, M., Andres, T., Campolongo, F., Cariboni, J., Gatelli, D., Saisana, M., Tarantola, S., 2008. Global Sensitivity Analysis: The Primer. Wiley, West Sussex, U.K. https://dx.doi.org/10.1002/9780470725184

Examples

>>> X = sample(problem)
>>> Y = X[:, 0] + (0.1 * X[:, 1]) + ((1.2 * X[:, 2]) * (0.2 + X[:, 0]))
>>> analyze(problem, X, Y, second_order=True, print_to_console=True)

High-Dimensional Model Representation¶

SALib.sample.latin.sample(problem, N, seed=None)[source]

Generate model inputs using Latin hypercube sampling (LHS).

Returns a NumPy matrix containing the model inputs generated by Latin hypercube sampling. The resulting matrix contains N rows and D columns, where D is the number of parameters.

Parameters:	problem (dict) – The problem definition N (int) – The number of samples to generate

References

[1]	McKay, M.D., Beckman, R.J., Conover, W.J., 1979. A comparison of three methods for selecting values of input variables in the analysis of output from a computer code. Technometrics 21, 239–245. https://doi.org/10.2307/1268522

[2]	Iman, R.L., Helton, J.C., Campbell, J.E., 1981. An Approach to Sensitivity Analysis of Computer Models: Part I—Introduction, Input Variable Selection and Preliminary Variable Assessment. Journal of Quality Technology 13, 174–183. https://doi.org/10.1080/00224065.1981.11978748

License¶

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Developers¶

Jon Herman <jdherman8@gmail.com>
Will Usher <william.usher@ouce.ox.ac.uk>
Chris Mutel
Bernardo Trindade
Dave Hadka
Matt Woodruff
Fernando Rios
Dan Hyams
xantares
Abdullah Sahin <sahina@uci.edu>
Takuya Iwanaga

SALib¶

SALib package¶

Subpackages¶

SALib.analyze package¶

Submodules¶

SALib.analyze.common_args module¶

SALib.analyze.common_args.create(cli_parser=None)[source]¶

SALib.analyze.common_args.run_cli(cli_parser, run_analysis, known_args=None)[source]¶

SALib.analyze.common_args.setup(parser)[source]¶

SALib.analyze.delta module¶

SALib.analyze.delta.analyze(problem: Dict[KT, VT], X: numpy.array, Y: numpy.array, num_resamples: int = 100, conf_level: float = 0.95, print_to_console: bool = False, seed: int = None) → Dict[KT, VT][source]¶

Perform Delta Moment-Independent Analysis on model outputs.

Returns a dictionary with keys ‘delta’, ‘delta_conf’, ‘S1’, and ‘S1_conf’, where each entry is a list of size D (the number of parameters) containing the indices in the same order as the parameter file.

all samplers

Parameters:

problem (dict) – The problem definition
X (numpy.matrix) – A NumPy matrix containing the model inputs
Y (numpy.array) – A NumPy array containing the model outputs
num_resamples (int) – The number of resamples when computing confidence intervals (default 10)
conf_level (float) – The confidence interval level (default 0.95)
print_to_console (bool) – Print results directly to console (default False)

References

[1]	Borgonovo, E. (2007). “A new uncertainty importance measure.” Reliability Engineering & System Safety, 92(6):771-784, doi:10.1016/j.ress.2006.04.015.

[2]	Plischke, E., E. Borgonovo, and C. L. Smith (2013). “Global sensitivity measures from given data.” European Journal of Operational Research, 226(3):536-550, doi:10.1016/j.ejor.2012.11.047.

Examples

>>> X = latin.sample(problem, 1000)
>>> Y = Ishigami.evaluate(X)
>>> Si = delta.analyze(problem, X, Y, print_to_console=True)

SALib.analyze.delta.bias_reduced_delta(Y, Ygrid, X, m, num_resamples, conf_level)[source]¶: Plischke et al. 2013 bias reduction technique (eqn 30)

SALib.analyze.delta.calc_delta(Y, Ygrid, X, m)[source]¶: Plischke et al. (2013) delta index estimator (eqn 26) for d_hat.

SALib.analyze.delta.cli_action(args)[source]¶

SALib.analyze.delta.cli_parse(parser)[source]¶

SALib.analyze.delta.sobol_first(Y, X, m)[source]¶

SALib.analyze.delta.sobol_first_conf(Y, X, m, num_resamples, conf_level)[source]¶

SALib.analyze.dgsm module¶

SALib.analyze.dgsm.analyze(problem, X, Y, num_resamples=100, conf_level=0.95, print_to_console=False, seed=None)[source]¶

Calculates Derivative-based Global Sensitivity Measure on model outputs.

Returns a dictionary with keys ‘vi’, ‘vi_std’, ‘dgsm’, and ‘dgsm_conf’, where each entry is a list of size D (the number of parameters) containing the indices in the same order as the parameter file.

finite_diff

Parameters:

problem (dict) – The problem definition
X (numpy.matrix) – The NumPy matrix containing the model inputs
Y (numpy.array) – The NumPy array containing the model outputs
num_resamples (int) – The number of resamples used to compute the confidence intervals (default 1000)
conf_level (float) – The confidence interval level (default 0.95)
print_to_console (bool) – Print results directly to console (default False)

References

[1]	Sobol, I. M. and S. Kucherenko (2009). “Derivative based global sensitivity measures and their link with global sensitivity indices.” Mathematics and Computers in Simulation, 79(10):3009-3017, doi:10.1016/j.matcom.2009.01.023.

SALib.analyze.dgsm.calc_dgsm(base, perturbed, x_delta, bounds, num_resamples, conf_level)[source]¶: v_i sensitivity measure following Sobol and Kucherenko (2009). For comparison, total order S_tot <= dgsm

SALib.analyze.dgsm.calc_vi_mean(base, perturbed, x_delta)[source]¶

Calculate v_i mean.

Same as calc_vi_stats but only returns the mean.

SALib.analyze.dgsm.calc_vi_stats(base, perturbed, x_delta)[source]¶

Calculate v_i mean and std.

v_i sensitivity measure following Sobol and Kucherenko (2009) For comparison, Morris mu* < sqrt(v_i)

Same as calc_vi_mean but returns standard deviation as well.

SALib.analyze.dgsm.cli_action(args)[source]¶

SALib.analyze.dgsm.cli_parse(parser)[source]¶

SALib.analyze.fast module¶

SALib.analyze.fast.analyze(problem, Y, M=4, num_resamples=100, conf_level=0.95, print_to_console=False, seed=None)[source]¶

Performs the extended Fourier Amplitude Sensitivity Test (eFAST) on model outputs.

Returns a dictionary with keys ‘S1’ and ‘ST’, where each entry is a list of size D (the number of parameters) containing the indices in the same order as the parameter file.

fast_sampler

Parameters:	problem (dict) – The problem definition Y (numpy.array) – A NumPy array containing the model outputs M (int) – The interference parameter, i.e., the number of harmonics to sum in the Fourier series decomposition (default 4) print_to_console (bool) – Print results directly to console (default False)

References

[1]	Cukier, R. I., C. M. Fortuin, K. E. Shuler, A. G. Petschek, and J. H. Schaibly (1973). “Study of the sensitivity of coupled reaction systems to uncertainties in rate coefficients.” J. Chem. Phys., 59(8):3873-3878, doi:10.1063/1.1680571.

[2]	Saltelli, A., S. Tarantola, and K. P.-S. Chan (1999). “A Quantitative Model-Independent Method for Global Sensitivity Analysis of Model Output.” Technometrics, 41(1):39-56, doi:10.1080/00401706.1999.10485594.

[3]	Pujol, G. (2006) fast99 - R sensitivity package https://github.com/cran/sensitivity/blob/master/R/fast99.R

Examples

>>> X = fast_sampler.sample(problem, 1000)
>>> Y = Ishigami.evaluate(X)
>>> Si = fast.analyze(problem, Y, print_to_console=False)

SALib.analyze.fast.bootstrap(Y, N, M, omega_0, resamples, conf_level)[source]¶

SALib.analyze.fast.cli_action(args)[source]¶

SALib.analyze.fast.cli_parse(parser)[source]¶

Add method specific options to CLI parser.

Parameters:	parser (argparse object) –
Returns:
Return type:	Updated argparse object

SALib.analyze.fast.compute_orders(outputs, N, M, omega)[source]¶

SALib.analyze.ff module¶

Created on 30 Jun 2015

@author: will2

SALib.analyze.ff.analyze(problem, X, Y, second_order=False, print_to_console=False, seed=None)[source]¶

Perform a fractional factorial analysis

Returns a dictionary with keys ‘ME’ (main effect) and ‘IE’ (interaction effect). The techniques bulks out the number of parameters with dummy parameters to the nearest 2**n. Any results involving dummy parameters could indicate a problem with the model runs.

ff

Parameters:	problem (dict) – The problem definition X (numpy.matrix) – The NumPy matrix containing the model inputs Y (numpy.array) – The NumPy array containing the model outputs second_order (bool, default=False) – Include interaction effects print_to_console (bool, default=False) – Print results directly to console
Returns:	Si – A dictionary of sensitivity indices, including main effects `ME`, and interaction effects `IE` (if `second_order` is True)
Return type:	dict

References

[1]	Saltelli, A., Ratto, M., Andres, T., Campolongo, F., Cariboni, J., Gatelli, D., Saisana, M., Tarantola, S., 2008. Global Sensitivity Analysis: The Primer. Wiley, West Sussex, U.K. https://dx.doi.org/10.1002/9780470725184

Examples

>>> X = sample(problem)
>>> Y = X[:, 0] + (0.1 * X[:, 1]) + ((1.2 * X[:, 2]) * (0.2 + X[:, 0]))
>>> analyze(problem, X, Y, second_order=True, print_to_console=True)

SALib.analyze.ff.cli_action(args)[source]¶

SALib.analyze.ff.cli_parse(parser)[source]¶

SALib.analyze.ff.interactions(problem, Y)[source]¶

Computes the second order effects

Computes the second order effects (interactions) between all combinations of pairs of input factors

Parameters:

problem (dict) – The problem definition
Y (numpy.array) – The NumPy array containing the model outputs

Returns:

ie_names (list) – The names of the interaction pairs
IE (list) – The sensitivity indices for the pairwise interactions

SALib.analyze.ff.to_df(self)[source]¶

Conversion method to Pandas DataFrame. To be attached to ResultDict.

Returns:	main_effect, inter_effect – A tuple of DataFrames for main effects and interaction effects. The second element (for interactions) will be None if not available.
Return type:	tuple

SALib.analyze.hdmr module¶

SALib.analyze.hdmr.analyze(problem: Dict[KT, VT], X: numpy.ndarray, Y: numpy.ndarray, maxorder: int = 2, maxiter: int = 100, m: int = 2, K: int = 20, R: int = None, alpha: float = 0.95, lambdax: float = 0.01, print_to_console: bool = True, seed: int = None) → Dict[KT, VT][source]¶

High-Dimensional Model Representation (HDMR) using B-spline functions.

HDMR is used for variance-based global sensitivity analysis (GSA) with correlated and uncorrelated inputs. This function uses as input

a N x d matrix of N different d-vectors of model inputs (factors/parameters)
a N x 1 vector of corresponding model outputs

Returns to the user: - each factor’s first, second, and third order sensitivity coefficient

(separated in total, structural and correlative contributions),

an estimate of their 95% confidence intervals (from bootstrap method)
the coefficients of the significant B-spline basis functions that govern output,
Y (determined by an F-test of the error residuals of the HDMR model (emulator) with/without a given first, second and/or third order B-spline). These coefficients define an emulator that can be used to predict the output, Y, of the original (CPU-intensive) model for any d-vector of model inputs. For uncorrelated model inputs (columns of X are independent), the HDMR sensitivity indices reduce to a single index (= structural contribution), consistent with their values derived from commonly used variance-based GSA methods.

all samplers

Parameters:

problem (dict) – The problem definition
X (numpy.matrix) – The NumPy matrix containing the model inputs, N rows by d columns
Y (numpy.array) – The NumPy array containing the model outputs for each row of X
maxorder (int (1-3, default: 2)) – Maximum HDMR expansion order
maxiter (int (1-1000, default: 100)) – Max iterations backfitting
m (int (2-10, default: 2)) – Number of B-spline intervals
K (int (1-100, default: 20)) – Number of bootstrap iterations
R (int (100-N/2, default: N/2)) – Number of bootstrap samples. Will be set to length of Y if K is set to 1.
alpha (float (0.5-1)) – Confidence interval F-test
lambdax (float (0-10, default: 0.01)) – Regularization term
print_to_console (bool) – Print results directly to console (default False)
seed (bool) – Set a seed value

Returns:

Si – Sa: Uncorrelated contribution Sa_conf: Confidence interval of Sa Sb: Correlated contribution Sb_conf: Confidence interval of Sb S: Total contribution of a particular term S_conf: Confidence interval of S ST: Total contribution of a particular dimension/parameter ST_conf: Confidence interval of ST Sa: Uncorrelated contribution select: Number of selection (F-Test) Em: Result set

C1: First order coefficient C2: Second order coefficient C3: Third Order coefficient

Return type:

ResultDict,

References

[1]	Genyuan Li, H. Rabitz, P.E. Yelvington, O.O. Oluwole, F. Bacon, C.E. Kolb, and J. Schoendorf, “Global Sensitivity Analysis for Systems with Independent and/or Correlated Inputs”, Journal of Physical Chemistry A, Vol. 114 (19), pp. 6022 - 6032, 2010, https://doi.org/10.1021/jp9096919

Examples

>>> X = saltelli.sample(problem, 512)
>>> Y = Ishigami.evaluate(X)
>>> Si = hdmr.analyze(problem, X, Y, **options)

@sahin-abdullah (sahina@uci.edu)

SALib.analyze.hdmr.cli_parse(parser)[source]¶

SALib.analyze.hdmr.cli_action(args)[source]¶

SALib.analyze.morris module¶

SALib.analyze.morris.analyze(problem: Dict[KT, VT], X: numpy.ndarray, Y: numpy.ndarray, num_resamples: int = 100, conf_level: float = 0.95, print_to_console: bool = False, num_levels: int = 4, seed=None) → numpy.ndarray[source]¶

Perform Morris Analysis on model outputs.

Returns a dictionary with keys ‘mu’, ‘mu_star’, ‘sigma’, and ‘mu_star_conf’, where each entry is a list of parameters containing the indices in the same order as the parameter file.

morris

Parameters:

problem (dict) – The problem definition
X (numpy.array) – The NumPy matrix containing the model inputs of dtype=float
Y (numpy.array) – The NumPy array containing the model outputs of dtype=float
num_resamples (int) – The number of resamples used to compute the confidence intervals (default 1000)
conf_level (float) – The confidence interval level (default 0.95)
print_to_console (bool) – Print results directly to console (default False)
num_levels (int) – The number of grid levels, must be identical to the value passed to SALib.sample.morris (default 4)
seed (int) – Seed to generate a random number

Returns:

Si – A dictionary of sensitivity indices containing the following entries.

mu - the mean elementary effect
mu_star - the absolute of the mean elementary effect
sigma - the standard deviation of the elementary effect
mu_star_conf - the bootstrapped confidence interval
names - the names of the parameters

Return type:

dict

References

[1]	Morris, M. (1991). “Factorial Sampling Plans for Preliminary Computational Experiments.” Technometrics, 33(2):161-174, doi:10.1080/00401706.1991.10484804.

[2]	Campolongo, F., J. Cariboni, and A. Saltelli (2007). “An effective screening design for sensitivity analysis of large models.” Environmental Modelling & Software, 22(10):1509-1518, doi:10.1016/j.envsoft.2006.10.004.

Examples

>>> X = morris.sample(problem, 1000, num_levels=4)
>>> Y = Ishigami.evaluate(X)
>>> Si = morris.analyze(problem, X, Y, conf_level=0.95,
>>>                     print_to_console=True, num_levels=4)

SALib.analyze.morris.cli_action(args)[source]¶

SALib.analyze.morris.cli_parse(parser)[source]¶

SALib.analyze.pawn module¶

SALib.analyze.pawn.analyze(problem: Dict[KT, VT], X: numpy.ndarray, Y: numpy.ndarray, S: int = 10, print_to_console: bool = False, seed: int = None)[source]¶

Performs PAWN sensitivity analysis.

Calculates the min, mean, median, max, and coefficient of variation (CV).

CV is (standard deviation / mean), and so lower values indicate little change over the slides, and larger values indicate large variations across the slides.

all samplers

Parameters:	problem (dict) – The problem definition X (numpy.array) – A NumPy array containing the model inputs Y (numpy.array) – A NumPy array containing the model outputs S (int) – Number of slides (default 10) print_to_console (bool) – Print results directly to console (default False) seed (int) – Seed value to ensure deterministic results

References

[1]	Pianosi, F., Wagener, T., 2015. A simple and efficient method for global sensitivity analysis based on cumulative distribution functions. Environmental Modelling & Software 67, 1–11. https://doi.org/10.1016/j.envsoft.2015.01.004

[2]	Baroni, G., Francke, T., 2020. An effective strategy for combining variance- and distribution-based global sensitivity analysis. Environmental Modelling & Software, 134, 104851. https://doi.org/10.1016/j.envsoft.2020.104851

[3]	Baroni, G., Francke, T., 2020. GSA-cvd Combining variance- and distribution-based global sensitivity analysis https://github.com/baronig/GSA-cvd

Examples

>>> X = latin.sample(problem, 1000)
>>> Y = Ishigami.evaluate(X)
>>> Si = pawn.analyze(problem, X, Y, S=10, print_to_console=False)

SALib.analyze.pawn.cli_action(args)[source]¶

SALib.analyze.pawn.cli_parse(parser)[source]¶

SALib.analyze.rbd_fast module¶

SALib.analyze.rbd_fast.analyze(problem, X, Y, M=10, num_resamples=100, conf_level=0.95, print_to_console=False, seed=None)[source]¶

Performs the Random Balanced Design - Fourier Amplitude Sensitivity Test (RBD-FAST) on model outputs.

Returns a dictionary with keys ‘S1’, where each entry is a list of size D (the number of parameters) containing the indices in the same order as the parameter file.

all samplers

Parameters:	problem (dict) – The problem definition X (numpy.array) – A NumPy array containing the model inputs Y (numpy.array) – A NumPy array containing the model outputs M (int) – The interference parameter, i.e., the number of harmonics to sum in the Fourier series decomposition (default 10) print_to_console (bool) – Print results directly to console (default False)

References

[1]	S. Tarantola, D. Gatelli and T. Mara (2006) “Random Balance Designs for the Estimation of First Order Global Sensitivity Indices”, Reliability Engineering and System Safety, 91:6, 717-727

[2]	Elmar Plischke (2010) “An effective algorithm for computing global sensitivity indices (EASI) Reliability Engineering & System Safety”, 95:4, 354-360. doi:10.1016/j.ress.2009.11.005

[3]	Jean-Yves Tissot, Clémentine Prieur (2012) “Bias correction for the estimation of sensitivity indices based on random balance designs.”, Reliability Engineering and System Safety, Elsevier, 107, 205-213. doi:10.1016/j.ress.2012.06.010

[4]	Jeanne Goffart, Mickael Rabouille & Nathan Mendes (2015) “Uncertainty and sensitivity analysis applied to hygrothermal simulation of a brick building in a hot and humid climate”, Journal of Building Performance Simulation. doi:10.1080/19401493.2015.1112430

Examples

>>> X = latin.sample(problem, 1000)
>>> Y = Ishigami.evaluate(X)
>>> Si = rbd_fast.analyze(problem, X, Y, print_to_console=False)

SALib.analyze.rbd_fast.bootstrap(X_d, Y, M, resamples, conf_level)[source]¶

SALib.analyze.rbd_fast.cli_action(args)[source]¶

SALib.analyze.rbd_fast.cli_parse(parser)[source]¶

SALib.analyze.rbd_fast.compute_first_order(permuted_outputs, M)[source]¶

SALib.analyze.rbd_fast.permute_outputs(X, Y)[source]¶

Permute the output according to one of the inputs as in [_2]

References

[2]	Elmar Plischke (2010) “An effective algorithm for computing global sensitivity indices (EASI) Reliability Engineering & System Safety”, 95:4, 354-360. doi:10.1016/j.ress.2009.11.005

SALib.analyze.rbd_fast.unskew_S1(S1, M, N)[source]¶: Unskew the sensivity indice (Jean-Yves Tissot, Clémentine Prieur (2012) “Bias correction for the estimation of sensitivity indices based on random balance designs.”, Reliability Engineering and System Safety, Elsevier, 107, 205-213. doi:10.1016/j.ress.2012.06.010)

SALib.analyze.sobol module¶

SALib.analyze.sobol.Si_list_to_dict(S_list, D, calc_second_order)[source]¶: Convert the parallel output into the regular dict format for printing/returning

SALib.analyze.sobol.Si_to_pandas_dict(S_dict)[source]¶

Convert Si information into Pandas DataFrame compatible dict.

Parameters:	S_dict (ResultDict) – Sobol sensitivity indices

SALib.plotting package¶

Submodules¶

SALib.plotting.bar module¶

SALib.plotting.bar.plot(Si_df, ax=None)[source]¶

Create bar chart of results.

Parameters:	Si_df (*) –
Returns:	* ax
Return type:	matplotlib axes object

Examples

>>> from SALib.plotting.bar import plot as barplot
>>> from SALib.test_functions import Ishigami
>>>
>>> # See README for example problem specification
>>>
>>> X = saltelli.sample(problem, 512)
>>> Y = Ishigami.evaluate(X)
>>> Si = sobol.analyze(problem, Y, print_to_console=False)
>>> total, first, second = Si.to_df()
>>> barplot(total)

SALib.plotting.hdmr module¶

Created on Dec 20, 2019

@author: @sahin-abdullah

This submodule produces two diffent figures: (1) emulator vs simulator, (2) regression lines of first order component functions

SALib.plotting.hdmr.plot(Si)[source]¶

SALib.plotting.morris module¶

Created on 29 Jun 2015

@author: @willu47

This module provides the basic infrastructure for plotting charts for the Method of Morris results

The procedures should build upon and return an axes instance:

import matplotlib.pyplot as plt
Si = morris.analyze(problem, param_values, Y, conf_level=0.95,
                    print_to_console=False, num_levels=10)

# set plot style etc.
fig, ax = plt.subplots(1)
p = SALib.plotting.morris.horizontal_bar_plot(ax, Si, {'marker':'x'})
p.show()

SALib.plotting.morris.covariance_plot(ax, Si, opts=None, unit='')[source]¶: Plots mu* against sigma or the 95% confidence interval

SALib.plotting.morris.horizontal_bar_plot(ax, Si, opts=None, sortby='mu_star', unit='')[source]¶: Updates a matplotlib axes instance with a horizontal bar plot of mu_star, with error bars representing mu_star_conf.

SALib.plotting.morris.sample_histograms(fig, input_sample, problem, opts=None)[source]¶: Plots a set of subplots of histograms of the input sample

Module contents¶

SALib.sample package¶

Subpackages¶

SALib.sample.morris package¶

Submodules¶

SALib.sample.morris.brute module¶

class SALib.sample.morris.brute.BruteForce[source]¶

Bases: SALib.sample.morris.strategy.Strategy

Implements the brute force optimisation strategy

brute_force_most_distant(input_sample: numpy.ndarray, num_samples: int, num_params: int, k_choices: int, num_groups: int = None) → List[T][source]¶

Use brute force method to find most distant trajectories

Parameters:	input_sample (numpy.ndarray) – num_samples (int) – The number of samples to generate num_params (int) – The number of parameters k_choices (int) – The number of optimal trajectories num_groups (int, default=None) – The number of groups
Returns:
Return type:	list

find_maximum(scores, N, k_choices)[source]¶

Finds the k_choices maximum scores from scores

Parameters:	scores (numpy.ndarray) – N (int) – k_choices (int) –
Returns:
Return type:	list

find_most_distant(input_sample: numpy.ndarray, num_samples: int, num_params: int, k_choices: int, num_groups: int = None) → numpy.ndarray[source]¶

Finds the ‘k_choices’ most distant choices from the ‘num_samples’ trajectories contained in ‘input_sample’

Parameters:	input_sample (numpy.ndarray) – num_samples (int) – The number of samples to generate num_params (int) – The number of parameters k_choices (int) – The number of optimal trajectories num_groups (int, default=None) – The number of groups
Returns:
Return type:	numpy.ndarray

static grouper(n, iterable)[source]¶

static mappable(combos, pairwise, distance_matrix)[source]¶

Obtains scores from the distance_matrix for each pairwise combination held in the combos array

Parameters:	combos (numpy.ndarray) – pairwise (numpy.ndarray) – distance_matrix (numpy.ndarray) –

static nth(iterable, n, default=None)[source]¶

Returns the nth item or a default value

Parameters:	iterable (iterable) – n (int) – default (default=None) – The default value to return

SALib.sample.morris.local module¶

class SALib.sample.morris.local.LocalOptimisation[source]¶

Bases: SALib.sample.morris.strategy.Strategy

Implements the local optimisation algorithm using the Strategy interface

add_indices(indices: Tuple, distance_matrix: numpy.ndarray) → List[T][source]¶

Adds extra indices for the combinatorial problem.

Parameters:	indices (tuple) – distance_matrix (numpy.ndarray (M,M)) –

Example

>>> add_indices((1,2), numpy.array((5,5)))
[(1, 2, 3), (1, 2, 4), (1, 2, 5)]

find_local_maximum(input_sample: numpy.ndarray, N: int, num_params: int, k_choices: int, num_groups: int = None) → List[T][source]¶

Find the most different trajectories in the input sample using a local approach

An alternative by Ruano et al. (2012) for the brute force approach as originally proposed by Campolongo et al. (2007). The method should improve the speed with which an optimal set of trajectories is found tremendously for larger sample sizes.

Parameters:	input_sample (np.ndarray) – N (int) – The number of trajectories num_params (int) – The number of factors k_choices (int) – The number of optimal trajectories to return num_groups (int, default=None) – The number of groups
Returns:
Return type:	list

get_max_sum_ind(indices_list: List[Tuple], distances: numpy.ndarray, i: Union[str, int], m: Union[str, int]) → Tuple[source]¶

Get the indices that belong to the maximum distance in distances

Parameters:	indices_list (list) – list of tuples distances (numpy.ndarray) – size M i (int) – m (int) –
Returns:
Return type:	list

sum_distances(indices: Tuple, distance_matrix: numpy.ndarray) → numpy.ndarray[source]¶

Calculate combinatorial distance between a select group of trajectories, indicated by indices

Parameters:	indices (tuple) – distance_matrix (numpy.ndarray (M,M)) –
Returns:
Return type:	numpy.ndarray

Notes

This function can perhaps be quickened by calculating the sum of the distances. The calculated distances, as they are right now, are only used in a relative way. Purely summing distances would lead to the same result, at a perhaps quicker rate.

SALib.sample.morris.morris module¶

Generate a sample using the Method of Morris

Three variants of Morris’ sampling for elementary effects is supported:

Vanilla Morris
Optimised trajectories when optimal_trajectories=True (using

Campolongo’s enhancements from 2007 and optionally Ruano’s enhancement from 2012; local_optimization=True)
Groups with optimised trajectories when optimal_trajectories=True and

the problem definition specifies groups (note that local_optimization must be False)

At present, optimised trajectories is implemented using either a brute-force approach, which can be very slow, especially if you require more than four trajectories, or a local method based which is much faster. Both methods now implement working with groups of factors.

Note that the number of factors makes little difference, but the ratio between number of optimal trajectories and the sample size results in an exponentially increasing number of scores that must be computed to find the optimal combination of trajectories. We suggest going no higher than 4 from a pool of 100 samples with the brute force approach. With local_optimization = True (which is default), it is possible to go higher than the previously suggested 4 from 100.

SALib.sample.morris.morris.sample(problem: Dict[KT, VT], N: int, num_levels: int = 4, optimal_trajectories: int = None, local_optimization: bool = True, seed: int = None) → numpy.ndarray[source]¶

Generate model inputs using the Method of Morris

Returns a NumPy matrix containing the model inputs required for Method of Morris. The resulting matrix has \((G+1)*T\) rows and \(D\) columns, where \(D\) is the number of parameters, \(G\) is the number of groups (if no groups are selected, the number of parameters). \(T\) is the number of trajectories \(N\), or optimal_trajectories if selected. These model inputs are intended to be used with SALib.analyze.morris.analyze().

Parameters:	problem (dict) – The problem definition N (int) – The number of trajectories to generate num_levels (int, default=4) – The number of grid levels (should be even) optimal_trajectories (int) – The number of optimal trajectories to sample (between 2 and N) local_optimization (bool, default=True) – Flag whether to use local optimization according to Ruano et al. (2012) Speeds up the process tremendously for bigger N and num_levels. If set to `False` brute force method is used, unless `gurobipy` is available seed (int) – Seed to generate a random number
Returns:	sample_morris – Returns a numpy.ndarray containing the model inputs required for Method of Morris. The resulting matrix has \((G/D+1)*N/T\) rows and \(D\) columns, where \(D\) is the number of parameters.
Return type:	numpy.ndarray

References

[1]	Ruano, M.V., Ribes, J., Seco, A., Ferrer, J., 2012. An improved sampling strategy based on trajectory design for application of the Morris method to systems with many input factors. Environmental Modelling & Software 37, 103–109. https://doi.org/10.1016/j.envsoft.2012.03.008

[2]	Morris, M.D., 1991. Factorial Sampling Plans for Preliminary Computational Experiments. Technometrics 33, 161–174. https://doi.org/10.1080/00401706.1991.10484804

[3]

Campolongo, F., Cariboni, J., Saltelli, A., 2007. An effective screening design for sensitivity analysis of large models. Environmental Modelling & Software, Modelling, computer-assisted simulations, and mapping of dangerous phenomena for hazard assessment 22, 1509–1518. https://doi.org/10.1016/j.envsoft.2006.10.004

SALib.sample.morris.strategy module¶

Defines a family of algorithms for generating samples

The sample a for use with SALib.analyze.morris.analyze, encapsulate each one, and makes them interchangeable.

Example

>>> localoptimisation = LocalOptimisation()
>>> context = SampleMorris(localoptimisation)
>>> context.sample(input_sample, num_samples, num_params, k_choices, groups)

class SALib.sample.morris.strategy.SampleMorris(strategy)[source]¶

Bases: object

Computes the optimum k_choices of trajectories from the input_sample.

Parameters:	strategy (`Strategy`) –

sample(input_sample, num_samples, num_params, k_choices, num_groups)[source]¶

Computes the optimum k_choices of trajectories from the input_sample.

Parameters:	input_sample (numpy.ndarray) – num_samples (int) – The number of samples to generate num_params (int) – The number of parameters k_choices (int) – The number of optimal trajectories num_groups (int) – The number of groups
Returns:	An array of optimal trajectories
Return type:	numpy.ndarray

class SALib.sample.morris.strategy.Strategy[source]¶

Bases: object

Declare an interface common to all supported algorithms. SampleMorris uses this interface to call the algorithm defined by a ConcreteStrategy.

static check_input_sample(input_sample, num_params, num_samples)[source]¶

Check the input_sample is valid

Checks input sample is:

the correct size
values between 0 and 1

Parameters:	input_sample (numpy.ndarray) – num_params (int) – num_samples (int) –

compile_output(input_sample, num_samples, num_params, maximum_combo, num_groups=None)[source]¶

Picks the trajectories from the input

Parameters:	input_sample (numpy.ndarray) – num_samples (int) – num_params (int) – maximum_combo (list) – num_groups (int) –

static compute_distance(m, l)[source]¶

Compute distance between two trajectories

Parameters:	m (np.ndarray) – l (np.ndarray) –
Returns:
Return type:	numpy.ndarray

compute_distance_matrix(input_sample, num_samples, num_params, num_groups=None, local_optimization=False)[source]¶

Computes the distance between each and every trajectory

Each entry in the matrix represents the sum of the geometric distances between all the pairs of points of the two trajectories

If the groups argument is filled, then the distances are still calculated for each trajectory,

Parameters:	input_sample (numpy.ndarray) – The input sample of trajectories for which to compute the distance matrix num_samples (int) – The number of trajectories num_params (int) – The number of factors num_groups (int, default=None) – The number of groups local_optimization (bool, default=False) – If True, fills the lower triangle of the distance matrix
Returns:	distance_matrix
Return type:	numpy.ndarray

static run_checks(number_samples, k_choices)[source]¶: Runs checks on k_choices

sample(input_sample, num_samples, num_params, k_choices, num_groups=None)[source]¶

Computes the optimum k_choices of trajectories from the input_sample.

Parameters:	input_sample (numpy.ndarray) – num_samples (int) – The number of samples to generate num_params (int) – The number of parameters k_choices (int) – The number of optimal trajectories num_groups (int, default=None) – The number of groups
Returns:
Return type:	numpy.ndarray

Module contents¶

Submodules¶

SALib.sample.common_args module¶

SALib.sample.common_args.create(cli_parser=None)[source]¶

Create CLI parser object.

Parameters:	cli_parser (function [optional]) – Function to add method specific arguments to parser
Returns:
Return type:	argparse object

SALib.sample.common_args.run_cli(cli_parser, run_sample, known_args=None)[source]¶

Run sampling with CLI arguments.

Parameters:	cli_parser (function) – Function to add method specific arguments to parser run_sample (function) – Method specific function that runs the sampling known_args (list [optional]) – Additional arguments to parse
Returns:
Return type:	argparse object

SALib.sample.common_args.setup(parser)[source]¶

Add common sampling options to CLI parser.

Parameters:	parser (argparse object) –
Returns:
Return type:	Updated argparse object

SALib.sample.directions module¶

SALib.sample.fast_sampler module¶

SALib.sample.fast_sampler.cli_action(args)[source]¶

Run sampling method

Parameters:	args (argparse namespace) –

SALib.sample.fast_sampler.cli_parse(parser)[source]¶

Add method specific options to CLI parser.

Parameters:	parser (argparse object) –
Returns:
Return type:	Updated argparse object

SALib.sample.fast_sampler.sample(problem, N, M=4, seed=None)[source]¶

Generate model inputs for the extended Fourier Amplitude Sensitivity Test (eFAST).

Returns a NumPy matrix containing the model inputs required by the extended Fourier Amplitude sensitivity test. The resulting matrix contains N * D rows and D columns, where D is the number of parameters. The samples generated are intended to be used by SALib.analyze.fast.analyze().

Parameters:	problem (dict) – The problem definition N (int) – The number of samples to generate M (int) – The interference parameter, i.e., the number of harmonics to sum in the Fourier series decomposition (default 4)

References

[1]	Cukier, R.I., Fortuin, C.M., Shuler, K.E., Petschek, A.G., Schaibly, J.H., 1973. Study of the sensitivity of coupled reaction systems to uncertainties in rate coefficients. I theory. Journal of Chemical Physics 59, 3873–3878. https://doi.org/10.1063/1.1680571

[2]	Saltelli, A., S. Tarantola, and K. P.-S. Chan (1999). “A Quantitative Model-Independent Method for Global Sensitivity Analysis of Model Output.” Technometrics, 41(1):39-56, doi:10.1080/00401706.1999.10485594.

SALib.sample.ff module¶

The sampling implementation of fractional factorial method

This implementation is based on the formulation put forward in [Saltelli et al. 2008]

SALib.sample.ff.cli_action(args)[source]¶

Run sampling method

Parameters:	args (argparse namespace) –

SALib.sample.ff.extend_bounds(problem)[source]¶

Extends the problem bounds to the nearest power of two

Parameters:	problem (dict) – The problem definition

SALib.sample.ff.find_smallest(num_vars)[source]¶

Find the smallest exponent of two that is greater than the number of variables

Parameters:	num_vars (int) – Number of variables
Returns:	x – Smallest exponent of two greater than num_vars
Return type:	int

SALib.sample.ff.generate_contrast(problem)[source]¶

Generates the raw sample from the problem file

Parameters:	problem (dict) – The problem definition

SALib.sample.ff.sample(problem, seed=None)[source]¶

Generates model inputs using a fractional factorial sample

Returns a NumPy matrix containing the model inputs required for a fractional factorial analysis. The resulting matrix has D columns, where D is smallest power of 2 that is greater than the number of parameters. These model inputs are intended to be used with SALib.analyze.ff.analyze().

The problem file is padded with a number of dummy variables called dummy_0 required for this procedure. These dummy variables can be used as a check for errors in the analyze procedure.

This algorithm is an implementation of that contained in Saltelli et al [Saltelli et al. 2008]

Parameters:	problem (dict) – The problem definition
Returns:	sample
Return type:	`numpy.array`

References

[1]	Saltelli, A., Ratto, M., Andres, T., Campolongo, F., Cariboni, J., Gatelli, D., Saisana, M., Tarantola, S., 2008. Global Sensitivity Analysis: The Primer. Wiley, West Sussex, U.K. https://dx.doi.org/10.1002/9780470725184

SALib.sample.finite_diff module¶

SALib.sample.finite_diff.cli_action(args)[source]¶

Run sampling method

Parameters:	args (argparse namespace) –

SALib.sample.finite_diff.cli_parse(parser)[source]¶

Add method specific options to CLI parser.

Parameters:	parser (argparse object) –
Returns:
Return type:	Updated argparse object

SALib.sample.finite_diff.sample(problem: Dict[KT, VT], N: int, delta: float = 0.01, seed: int = None, skip_values: int = 1024) → numpy.ndarray[source]¶

Generate matrix of samples for derivative-based global sensitivity measure (dgsm). Start from a QMC (Sobol’) sequence and finite difference with delta % steps

Parameters:	problem (dict) – SALib problem specification N (int) – Number of samples delta (float) – Finite difference step size (percent) seed (int or None) – Random seed value skip_values (int) – How many values of the Sobol sequence to skip
Returns:	np.array
Return type:	DGSM sequence

References

[1]	Sobol’, I.M., Kucherenko, S., 2009. Derivative based global sensitivity measures and their link with global sensitivity indices. Mathematics and Computers in Simulation 79, 3009–3017. https://doi.org/10.1016/j.matcom.2009.01.023

[2]	Sobol’, I.M., Kucherenko, S., 2010. Derivative based global sensitivity measures. Procedia - Social and Behavioral Sciences 2, 7745–7746. https://doi.org/10.1016/j.sbspro.2010.05.208

SALib.sample.latin module¶

SALib.sample.latin.cli_action(args)[source]¶

Run sampling method

Parameters:	args (argparse namespace) –

SALib.sample.latin.sample(problem, N, seed=None)[source]¶

Generate model inputs using Latin hypercube sampling (LHS).

Returns a NumPy matrix containing the model inputs generated by Latin hypercube sampling. The resulting matrix contains N rows and D columns, where D is the number of parameters.

Parameters:	problem (dict) – The problem definition N (int) – The number of samples to generate

References

[1]	McKay, M.D., Beckman, R.J., Conover, W.J., 1979. A comparison of three methods for selecting values of input variables in the analysis of output from a computer code. Technometrics 21, 239–245. https://doi.org/10.2307/1268522

[2]	Iman, R.L., Helton, J.C., Campbell, J.E., 1981. An Approach to Sensitivity Analysis of Computer Models: Part I—Introduction, Input Variable Selection and Preliminary Variable Assessment. Journal of Quality Technology 13, 174–183. https://doi.org/10.1080/00224065.1981.11978748

SALib.sample.saltelli module¶

SALib.sample.saltelli.cli_action(args)[source]¶

Run sampling method

Parameters:	args (argparse namespace) –

SALib.sample.saltelli.cli_parse(parser)[source]¶

Add method specific options to CLI parser.

Parameters:	parser (argparse object) –
Returns:
Return type:	Updated argparse object

SALib.sample.saltelli.sample(problem: Dict[KT, VT], N: int, calc_second_order: bool = True, skip_values: int = 1024)[source]¶

Generates model inputs using Saltelli’s extension of the Sobol’ sequence.

Returns a NumPy matrix containing the model inputs using Saltelli’s sampling scheme. Saltelli’s scheme extends the Sobol’ sequence in a way to reduce the error rates in the resulting sensitivity index calculations. If calc_second_order is False, the resulting matrix has N * (D + 2) rows, where D is the number of parameters. If calc_second_order is True, the resulting matrix has N * (2D + 2) rows. These model inputs are intended to be used with SALib.analyze.sobol.analyze().

Raises a UserWarning in cases where sample sizes may be sub-optimal. The convergence properties of the Sobol’ sequence requires N < skip_values and that both N and skip_values are base 2 (e.g., N = 2^n).

Parameters:	problem (dict) – The problem definition N (int) – The number of samples to generate. Must be an exponent of 2 and < skip_values. calc_second_order (bool) – Calculate second-order sensitivities (default True) skip_values (int) – Number of points in Sobol’ sequence to skip (must be an exponent of 2).

References

[1]	Saltelli, A., 2002. Making best use of model evaluations to compute sensitivity indices. Computer Physics Communications 145, 280–297. https://doi.org/10.1016/S0010-4655(02)00280-1

[2]	Sobol’, I.M., 2001. Global sensitivity indices for nonlinear mathematical models and their Monte Carlo estimates. Mathematics and Computers in Simulation, The Second IMACS Seminar on Monte Carlo Methods 55, 271–280. https://doi.org/10.1016/S0378-4754(00)00270-6

[3]	Owen, A. B., 2020. On dropping the first Sobol’ point. arXiv:2008.08051 [cs, math, stat]. Available at: http://arxiv.org/abs/2008.08051 (Accessed: 20 April 2021).

[4]	Discussion: https://github.com/scipy/scipy/pull/10844

SALib.sample.sobol_sequence module¶

SALib.sample.sobol_sequence.index_of_least_significant_zero_bit(value)[source]¶

SALib.sample.sobol_sequence.sample(N, D)[source]¶: Generate (N x D) numpy array of Sobol sequence samples

Module contents¶

SALib.scripts package¶

Submodules¶

SALib.scripts.salib module¶

Command-line utility for SALib

SALib.scripts.salib.main()[source]¶

SALib.scripts.salib.parse_subargs(module, parser, method, opts)[source]¶

Attach argument parser for action specific options.

Parameters:	module (module) – name of module to extract action from parser (argparser) – argparser object to attach additional arguments to method (str) – name of method (morris, sobol, etc). Must match one of the available submodules opts (list) – A list of argument options to parse
Returns:	subargs
Return type:	argparser namespace object

Module contents¶

SALib.test_functions package¶

Submodules¶

SALib.test_functions.Ishigami module¶

SALib.test_functions.Ishigami.evaluate(X: numpy.ndarray, A: float = 7.0, B: float = 0.1) → numpy.ndarray[source]¶

Non-monotonic Ishigami-Homma three parameter test function:

f(x) = sin(x_{1}) + A sin(x_{2})^2 + Bx^{4}_{3}sin(x_{1})

This test function is commonly used to benchmark global sensitivity methods as variance-based sensitivities of this function can be analytically determined.

See listed references below.

In [2], the expected first-order indices are:

x1: 0.3139 x2: 0.4424 x3: 0.0

when A = 7, B = 0.1 when conducting Sobol’ analysis with the Saltelli sampling method with a sample size of 1000.

Parameters:	X (np.ndarray) – An ND array holding values for each parameter, where N is the number of samples and D is the number of parameters (in this case, three). A (float) – Constant A parameter B (float*) – Constant B parameter
Returns:	Y
Return type:	np.ndarray

References

[1]	Ishigami, T., Homma, T., 1990. An importance quantification technique in uncertainty analysis for computer models. Proceedings. First International Symposium on Uncertainty Modeling and Analysis. https://doi.org/10.1109/ISUMA.1990.151285

[2]	Saltelli, A., Ratto, M., Andres, T., Campolongo, F., Cariboni, J., Gatelli, D., Saisana, M., Tarantola, S., 2008. Global Sensitivity Analysis: The Primer. Wiley, West Sussex, U.K. https://dx.doi.org/10.1002/9780470725184

SALib.test_functions.Sobol_G module¶

SALib.test_functions.Sobol_G.evaluate(values, a=None, delta=None, alpha=None)[source]¶

Modified Sobol G-function.

Reverts to original Sobol G-function if delta and alpha are not given.

[1]	Saltelli, A., Annoni, P., Azzini, I., Campolongo, F., Ratto, M., Tarantola, S., 2010. Variance based sensitivity analysis of model output. Design and estimator for the total sensitivity index. Computer Physics Communications 181, 259–270. https://doi.org/10.1016/j.cpc.2009.09.018

Parameters:	values (numpy.ndarray) – input variables a (numpy.ndarray) – parameter values delta (numpy.ndarray) – shift parameters alpha (numpy.ndarray) – curvature parameters
Returns:	Y
Return type:	Result of G-function

SALib.test_functions.Sobol_G.sensitivity_index(a, alpha=None)[source]¶

SALib.test_functions.Sobol_G.total_sensitivity_index(a, alpha=None)[source]¶

SALib.test_functions.lake_problem module¶

SALib.test_functions.lake_problem.evaluate(values: numpy.ndarray, nvars: int = 100)[source]¶

Evaluate the Lake Problem with an array of parameter values.

Parameters:	values (np.ndarray,) – model inputs in the (column) order of a, q, b, mean, stdev, delta, alpha nvars (int,) – number of decision variables to simulate (default: 100)
Returns:	np.ndarray
Return type:	max_P, utility, inertia, reliability

SALib.test_functions.lake_problem.evaluate_lake(values: numpy.ndarray) → numpy.ndarray[source]¶

Evaluate the Lake Problem with an array of parameter values.

[1]	Hadka, D., Herman, J., Reed, P., Keller, K., (2015). “An open source framework for many-objective robust decision making.” Environmental Modelling & Software 74, 114–129. doi:10.1016/j.envsoft.2015.07.014

[2]	Singh, R., Reed, P., Keller, K., (2015). “Many-objective robust decision making for managing an ecosystem with a deeply uncertain threshold response.” Ecology and Society 20. doi:10.5751/ES-07687-200312

Parameters:

values (np.ndarray,) –

model inputs in the (column) order of a, q, b, mean, stdev

where * a is rate of anthropogenic pollution * q is exponent controlling recycling rate * b is decay rate for phosphorus * mean and * stdev set the log normal distribution of eps, see [2]

Returns:

Return type: np.ndarray, of Phosphorus pollution over time t

SALib.test_functions.lake_problem.lake_problem(X: Union[float, numpy.array], a: Union[float, numpy.array] = 0.1, q: Union[float, numpy.array] = 2.0, b: Union[float, numpy.array] = 0.42, eps: Union[float, numpy.array] = 0.02) → float[source]¶

Lake Problem as given in [1] and [2] modified for use as a test function.

The mean and stdev parameters control the log normal distribution of natural inflows (epsilon in [1] and [2]).

[1]	Hadka, D., Herman, J., Reed, P., Keller, K., (2015). “An open source framework for many-objective robust decision making.” Environmental Modelling & Software 74, 114–129. doi:10.1016/j.envsoft.2015.07.014

[2]	Kwakkel, J.H, (2017). “The Exploratory Modeling Workbench: An open source toolkit for exploratory modeling, scenario discovery, and (multi-objective) robust decision making.” Environmental Modelling & Software 96, 239–250. doi:10.1016/j.envsoft.2017.06.054

[3]	Singh, R., Reed, P., Keller, K., (2015). “Many-objective robust decision making for managing an ecosystem with a deeply uncertain threshold response.” Ecology and Society 20. doi:10.5751/ES-07687-200312

Parameters:	X (float or np.ndarray) – normalized concentration of Phosphorus at point in time a (float or np.ndarray) – rate of anthropogenic pollution (0.0 to 0.1) q (float or np.ndarray) – exponent controlling recycling rate (2.0 to 4.5). b (float or np.ndarray) – decay rate for phosphorus (0.1 to 0.45, where default 0.42 is irreversible, as described in [1]) eps (float or np.ndarray) – natural inflows of phosphorus (pollution), see [3]
Returns:
Return type:	* float, phosphorus pollution for a point in time

SALib.test_functions.linear_model_1 module¶

SALib.test_functions.linear_model_1.evaluate(values)[source]¶

Linear model (#1) used in Li et al., (2010).

y = x1 + x2 + x3 + x4 + x5

Parameters:	values (np.array) –

References

[1]	Genyuan Li, H. Rabitz, P.E. Yelvington, O.O. Oluwole, F. Bacon, C.E. Kolb, and J. Schoendorf, “Global Sensitivity Analysis for Systems with Independent and/or Correlated Inputs”, Journal of Physical Chemistry A, Vol. 114 (19), pp. 6022 - 6032, 2010, https://doi.org/10.1021/jp9096919

SALib.test_functions.linear_model_2 module¶

SALib.test_functions.linear_model_2.evaluate(values)[source]¶

Linear model (#2) used in Li et al., (2010).

y = 5x1 + 4x2 + 3x3 + 2x4 + x5

Parameters:	values (np.array) –

References

[1]	Genyuan Li, H. Rabitz, P.E. Yelvington, O.O. Oluwole, F. Bacon, C.E. Kolb, and J. Schoendorf, “Global Sensitivity Analysis for Systems with Independent and/or Correlated Inputs”, Journal of Physical Chemistry A, Vol. 114 (19), pp. 6022 - 6032, 2010, https://doi.org/10.1021/jp9096919

Module contents¶

SALib.util package¶

Submodules¶

SALib.util.problem module¶

class SALib.util.problem.ProblemSpec(*args, **kwargs)[source]¶

Bases: dict

Dictionary-like object representing an SALib Problem specification.

analysis¶

analyze(func, *args, **kwargs)[source]¶

Analyze sampled results using given function.

Parameters:	func (function,) – Analysis method to use. The provided function must accept the problem specification as the first parameter, X values if needed, Y values, and return a numpy array. args (list,) – Additional arguments to be passed to func kwargs (dict*,) – Additional keyword arguments passed to func
Returns:	self
Return type:	ProblemSpec object

evaluate(func, *args, **kwargs)[source]¶

Evaluate a given model.

Parameters:	func (function,) – Model, or function that wraps a model, to be run/evaluated. The provided function is required to accept a numpy array of inputs as its first parameter and must return a numpy array of results. args (list,) – Additional arguments to be passed to func kwargs (dict*,) – Additional keyword arguments passed to func
Returns:	self
Return type:	ProblemSpec object

evaluate_distributed(func, *args, nprocs=1, servers=None, verbose=False, **kwargs)[source]¶

Distribute model evaluation across a cluster.

Usage Conditions: * The provided function needs to accept a numpy array of inputs as

its first parameter

The provided function must return a numpy array of results

Parameters:	func (function,) – Model, or function that wraps a model, to be run in parallel nprocs (int,) – Number of processors to use for each node. Defaults to 1. servers (list[str] or None,) – IP addresses or alias for each server/node to use. verbose (bool,) – Display job execution statistics. Defaults to False. args (list,) – Additional arguments to be passed to func kwargs (dict*,) – Additional keyword arguments passed to func
Returns:	self
Return type:	ProblemSpec object

evaluate_parallel(func, *args, nprocs=None, **kwargs)[source]¶

Evaluate model locally in parallel.

All detected processors will be used if nprocs is not specified.

Parameters:	func (function,) – Model, or function that wraps a model, to be run in parallel. The provided function needs to accept a numpy array of inputs as its first parameter and must return a numpy array of results. nprocs (int,) – Number of processors to use. Uses all available if not specified. args (list,) – Additional arguments to be passed to func kwargs (dict*,) – Additional keyword arguments passed to func
Returns:	self
Return type:	ProblemSpec object

plot()[source]¶

Plot results.

Returns:	axes
Return type:	matplotlib axes object

results¶

sample(func, *args, **kwargs)[source]¶

Create sample using given function.

Parameters:	func (function,) – Sampling method to use. The given function must accept the SALib problem specification as the first parameter and return a numpy array. args (list,) – Additional arguments to be passed to func kwargs (dict*,) – Additional keyword arguments passed to func
Returns:	self
Return type:	ProblemSpec object

samples¶

set_results(results)[source]¶: Set previously available model results.

set_samples(samples)[source]¶: Set previous samples used.

to_df()[source]¶: Convert results to Pandas DataFrame.

SALib.util.results module¶

class SALib.util.results.ResultDict(*args, **kwargs)[source]¶

Bases: dict

Dictionary holding analysis results.

Conversion methods (e.g. to Pandas DataFrames) to be attached as necessary by each implementing method

plot(ax=None)[source]¶: Create bar chart of results

to_df()[source]¶: Convert dict structure into Pandas DataFrame.

SALib.util.util_funcs module¶

SALib.util.util_funcs.avail_approaches(pkg)[source]¶

Create list of available modules.

Parameters:	pkg (module) – module to inspect
Returns:	method – A list of available submodules
Return type:	list

SALib.util.util_funcs.read_param_file(filename, delimiter=None)[source]¶

Unpacks a parameter file into a dictionary

Reads a parameter file of format:

Param1,0,1,Group1,dist1
Param2,0,1,Group2,dist2
Param3,0,1,Group3,dist3

(Group and Dist columns are optional)

Returns a dictionary containing:

names - the names of the parameters
bounds - a list of lists of lower and upper bounds
num_vars - a scalar indicating the number of variables

(the length of names)
groups - a list of group names (strings) for each variable
dists - a list of distributions for the problem,

None if not specified or all uniform

Parameters:	filename (str) – The path to the parameter file delimiter (str, default=None) – The delimiter used in the file to distinguish between columns

Module contents¶

A set of utility functions

SALib.util.scale_samples(params: numpy.ndarray, problem: Dict[KT, VT])[source]¶

Scale samples based on specified distribution (defaulting to uniform).

Adds an entry to the problem specification to indicate samples have been scaled to maintain backwards compatibility (sample_scaled).

Parameters:	params (np.ndarray,) – numpy array of dimensions num_params-by-\(N\), where \(N\) is the number of samples problem (dictionary,) – SALib problem specification
Returns:
Return type:	np.ndarray, scaled samples

SALib.util.read_param_file(filename, delimiter=None)[source]¶

Unpacks a parameter file into a dictionary

Reads a parameter file of format:

Param1,0,1,Group1,dist1
Param2,0,1,Group2,dist2
Param3,0,1,Group3,dist3

(Group and Dist columns are optional)

Returns a dictionary containing:

names - the names of the parameters
bounds - a list of lists of lower and upper bounds
num_vars - a scalar indicating the number of variables

(the length of names)
groups - a list of group names (strings) for each variable
dists - a list of distributions for the problem,

None if not specified or all uniform

Parameters:	filename (str) – The path to the parameter file delimiter (str, default=None) – The delimiter used in the file to distinguish between columns

class SALib.util.ResultDict(*args, **kwargs)[source]¶

Bases: dict

Dictionary holding analysis results.

Conversion methods (e.g. to Pandas DataFrames) to be attached as necessary by each implementing method

plot(ax=None)[source]¶: Create bar chart of results

to_df()[source]¶: Convert dict structure into Pandas DataFrame.

SALib.util.avail_approaches(pkg)[source]¶

Create list of available modules.

Parameters:	pkg (module) – module to inspect
Returns:	method – A list of available submodules
Return type:	list

Returns:	tuple – Total and first order are dicts. Second order sensitivities contain a tuple of parameter name combinations for use as the DataFrame index and second order sensitivities. If no second order indices found, then returns tuple of (None, None)
Return type:	of total, first, and second order sensitivities.

Returns:	List
Return type:	of Pandas DataFrames in order of Total, First, Second

SALib - Sensitivity Analysis Library in Python¶

Supported Methods¶

Getting Started¶

Installing SALib¶

Installing Prerequisite Software¶

Testing Installation¶

Basics¶

What is Sensitivity Analysis?¶

What is SALib?¶

An Example¶

Importing SALib¶

Defining the Model Inputs¶

Generate Samples¶

Run Model¶

Perform Analysis¶

Basic Plotting¶

Another Example¶

Advanced Examples¶

Group sampling (Sobol and Morris methods only)¶

Generating alternate distributions¶

Concise API Reference¶

FAST - Fourier Amplitude Sensitivity Test¶

RBD-FAST - Random Balance Designs Fourier Amplitude Sensitivity Test¶

Method of Morris¶

Sobol Sensitivity Analysis¶

Delta Moment-Independent Measure¶

Derivative-based Global Sensitivity Measure (DGSM)¶

Fractional Factorial¶

High-Dimensional Model Representation¶

License¶

Developers¶

SALib¶

SALib package¶

Subpackages¶

SALib.analyze package¶

SALib.plotting package¶

SALib.sample package¶

SALib.scripts package¶

SALib.test_functions package¶

SALib.util package¶

Module contents¶

Indices and tables¶