SALib.sample package

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, N: int, delta: float = 0.01, seed: Optional[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, N: int, calc_second_order: bool = True, skip_values: int = 0)[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().

If skip_values is > 0, 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). See discussion in [4] for context and information.

If skipping values, one recommendation is that the largest possible n such that (2^n)-1 <= N is skipped (see [5]).

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, ideally a value of base 2 (default 0, see Owen [3] and Discussion [4])

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 https://github.com/scipy/scipy/pull/10844#issuecomment-673029539

5

Johnson, S. G. Sobol.jl: The Sobol module for Julia https://github.com/stevengj/Sobol.jl

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