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

See also

Si_list_to_dict()

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.

Examples

>>> X = saltelli.sample(problem, 512)
>>> Y = Ishigami.evaluate(X)
>>> Si = sobol.analyze(problem, Y, print_to_console=True)
>>> T_Si, first_Si, (idx, second_Si) = sobol.Si_to_pandas_dict(Si, problem)
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)
SALib.analyze.sobol.cli_action(args)[source]
SALib.analyze.sobol.cli_parse(parser)[source]
SALib.analyze.sobol.create_Si_dict(D, calc_second_order)[source]

initialize empty dict to store sensitivity indices

SALib.analyze.sobol.create_task_list(D, calc_second_order, n_processors)[source]

Create list with one entry (key, parameter 1, parameter 2) per sobol index (+conf.). This is used to supply parallel tasks to multiprocessing.Pool

SALib.analyze.sobol.first_order(A, AB, B)[source]

First order estimator following Saltelli et al. 2010 CPC, normalized by sample variance

SALib.analyze.sobol.second_order(A, ABj, ABk, BAj, B)[source]

Second order estimator following Saltelli 2002

SALib.analyze.sobol.separate_output_values(Y, D, N, calc_second_order)[source]
SALib.analyze.sobol.sobol_parallel(Z, A, AB, BA, B, r, tasks)[source]
SALib.analyze.sobol.to_df(self)[source]

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

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

Example

>>> Si = sobol.analyze(problem, Y, print_to_console=True)
>>> total_Si, first_Si, second_Si = Si.to_df()
SALib.analyze.sobol.total_order(A, AB, B)[source]

Total order estimator following Saltelli et al. 2010 CPC, normalized by sample variance

Module contents