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 Fourier Amplitude Sensitivity Test (FAST).
Returns a NumPy matrix containing the model inputs required by the 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)
-
SALib.analyze.fast.
analyze
(problem, Y, M=4, print_to_console=False, seed=None)[source] Performs the Fourier Amplitude Sensitivity Test (FAST) 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.
- 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.
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
-
SALib.analyze.rbd_fast.
analyze
(problem, X, Y, M=10, 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.
- 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, N, num_levels=4, optimal_trajectories=None, local_optimization=True, seed=None)[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, unlessgurobipy
is available
- Returns
sample – 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
-
SALib.analyze.morris.
analyze
(problem, X, Y, num_resamples=100, conf_level=0.95, print_to_console=False, num_levels=4, seed=None)[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.
- Parameters
problem (dict) – The problem definition
X (numpy.matrix) – 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)
- 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, N, calc_second_order=True, seed=None)[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()
.- Parameters
problem (dict) – The problem definition
N (int) – The number of samples to generate
calc_second_order (bool) – Calculate second-order sensitivities (default True)
-
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’.
- 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, 1000) >>> 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
-
SALib.analyze.delta.
analyze
(problem, X, Y, num_resamples=100, conf_level=0.95, print_to_console=False, seed=None)[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.
- 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.
- 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. 2008]
- Parameters
problem (dict) – The problem definition
- Returns
sample
- Return type
numpy.array
-
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.
- 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 effectsIE
(ifsecond_order
is True)- Return type
dict
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)