SALib.sample package

Subpackages

• SALib.sample.morris package
  • Submodules
  • SALib.sample.morris.brute module
    • BruteForce
      • BruteForce.brute_force_most_distant()
      • BruteForce.find_maximum()
      • BruteForce.find_most_distant()
      • BruteForce.grouper()
      • BruteForce.mappable()
      • BruteForce.nth()
  • SALib.sample.morris.local module
    • LocalOptimisation
      • LocalOptimisation.add_indices()
      • LocalOptimisation.find_local_maximum()
      • LocalOptimisation.get_max_sum_ind()
      • LocalOptimisation.sum_distances()
  • SALib.sample.morris.morris module
    • sample()
  • SALib.sample.morris.strategy module
    • SampleMorris
      • SampleMorris.sample()
    • Strategy
      • Strategy.check_input_sample()
      • Strategy.compile_output()
      • Strategy.compute_distance()
      • Strategy.compute_distance_matrix()
      • Strategy.run_checks()
      • Strategy.sample()
  • Module contents

Submodules

SALib.sample.common_args module

SALib.sample.common_args.create(cli_parser=None)

Create CLI parser object.

Parameters:

cli_parser (function [optional]) – Function to add method specific arguments to parser

Return type:

argparse object

SALib.sample.common_args.run_cli(cli_parser, run_sample, known_args=None)

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

Return type:

argparse object

SALib.sample.common_args.setup(parser)

Add common sampling options to CLI parser.

Parameters:

parser (argparse object)

Return type:

Updated argparse object

SALib.sample.directions module

SALib.sample.fast_sampler module

SALib.sample.fast_sampler.cli_action(args)

Run sampling method

Parameters:

args (argparse namespace)

SALib.sample.fast_sampler.cli_parse(parser)

Add method specific options to CLI parser.

Parameters:

parser (argparse object)

Return type:

Updated argparse object

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

Generate model inputs for extended Fourier Amplitude Sensitivity Test.

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)

• seed (int) – Seed to generate a random number

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)

Run sampling method

Parameters:

args (argparse namespace)

SALib.sample.ff.extend_bounds(problem)

Extends the problem bounds to the nearest power of two.

Parameters:

problem (dict) – The problem definition

SALib.sample.ff.find_smallest(num_vars)

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)

Generates the raw sample from the problem file.

Parameters:

problem (dict) – The problem definition

SALib.sample.ff.sample(problem, seed=None)

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

• seed (int) – Seed to generate a random number

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. http://doi.org/10.1002/9780470725184

SALib.sample.finite_diff module

SALib.sample.finite_diff.cli_action(args)

Run sampling method

Parameters:

args (argparse namespace)

SALib.sample.finite_diff.cli_parse(parser)

Add method specific options to CLI parser.

Parameters:

parser (argparse object)

Return type:

Updated argparse object

SALib.sample.finite_diff.sample(problem: Dict, N: int, delta: float = 0.01, seed: int = None, skip_values: int = 1024) → ndarray

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)

Run sampling method

Parameters:

args (argparse namespace)

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

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

• seed (int) – Seed to generate a random number

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)

Run sampling method

Parameters:

args (argparse namespace)

SALib.sample.saltelli.cli_parse(parser)

Add method specific options to CLI parser.

Parameters:

parser (argparse object)

Return type:

Updated argparse object

SALib.sample.saltelli.sample(problem: Dict, N: int, calc_second_order: bool = True, skip_values: int = None)

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

The Sobol’ sequence is a popular quasi-random low-discrepancy sequence used to generate uniform samples of parameter space.

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().

Deprecated since version 1.4.6.

Notes

The initial points of the Sobol’ sequence has some repetition (see Table 2 in Campolongo [1]), which can be avoided by setting the skip_values parameter. Skipping values reportedly improves the uniformity of samples. It has been shown that naively skipping values may reduce accuracy, increasing the number of samples needed to achieve convergence (see Owen [2]).

A recommendation adopted here is that both skip_values and N be a power of 2, where N is the desired number of samples (see [2] and discussion in [5] for further context). It is also suggested therein that skip_values >= N.

The method now defaults to setting skip_values to a power of two that is >= N. If skip_values is provided, the method now raises a UserWarning in cases where sample sizes may be sub-optimal according to the recommendation above.

Parameters:

• problem (dict) – The problem definition

• N (int) – The number of samples to generate. Ideally a power of 2 and <= skip_values.

• calc_second_order (bool) – Calculate second-order sensitivities (default True)

• skip_values (int or None) – Number of points in Sobol’ sequence to skip, ideally a value of base 2 (default: a power of 2 >= N, or 16; whichever is greater)

References

1. Campolongo, F., Saltelli, A., Cariboni, J., 2011.

   From screening to quantitative sensitivity analysis. A unified approach. Computer Physics Communications 182, 978-988. https://doi.org/10.1016/j.cpc.2010.12.039

2. 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).

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

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

5. Discussion: scipy/scipy#10844

   scipy/scipy#10844 scipy/scipy#10844

SALib.sample.sobol module

SALib.sample.sobol.cli_action(args)

Run sampling method

Parameters:

args (argparse namespace)

SALib.sample.sobol.cli_parse(parser)

Add method specific options to CLI parser.

Parameters:

parser (argparse object)

Return type:

Updated argparse object

SALib.sample.sobol.sample(problem: Dict, N: int, *, calc_second_order: bool = True, scramble: bool = True, skip_values: int = 0, seed: int | Generator | None = None)

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

The Sobol’ sequence is a popular quasi-random low-discrepancy sequence used to generate uniform samples of parameter space. The general approach is described in [1].

Returns a NumPy matrix containing the model inputs using Saltelli’s sampling scheme.

Saltelli’s scheme reduces the number of required model runs from N(2D+1) to N(D+1) (see [2]).

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().

Notes

The initial points of the Sobol’ sequence has some repetition (see Table 2 in Campolongo [3]__), which can be avoided by scrambling the sequence.

Another option, not recommended and available for educational purposes, is to use the skip_values parameter. Skipping values reportedly improves the uniformity of samples. But, it has been shown that naively skipping values may reduce accuracy, increasing the number of samples needed to achieve convergence (see Owen [4]__).

Parameters:

• problem (dict,) – The problem definition.

• N (int) – The number of samples to generate. Ideally a power of 2 and <= skip_values.

• calc_second_order (bool, optional) – Calculate second-order sensitivities. Default is True.

• scramble (bool, optional) – If True, use LMS+shift scrambling. Otherwise, no scrambling is done. Default is True.

• skip_values (int, optional) – Number of points in Sobol’ sequence to skip, ideally a value of base 2. It’s recommended not to change this value and use scramble instead. scramble and skip_values can be used together. Default is 0.

• seed ({None, int, numpy.random.Generator}, optional) – If seed is None the numpy.random.Generator generator is used. If seed is an int, a new Generator instance is used, seeded with seed. If seed is already a Generator instance then that instance is used. Default is None.

References

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

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

3. Campolongo, F., Saltelli, A., Cariboni, J., 2011. From screening to quantitative sensitivity analysis. A unified approach. Computer Physics Communications 182, 978-988. https://doi.org/10.1016/j.cpc.2010.12.039

4. 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).

SALib.sample.sobol_sequence module

SALib.sample.sobol_sequence.index_of_least_significant_zero_bit(value)

SALib.sample.sobol_sequence.sample(N, D)

Generate (N x D) numpy array of Sobol sequence samples

Module contents