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 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)[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
- 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=1000, 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=10, 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=1000, 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)