SALib.sample package¶
Subpackages¶
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.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, whereD
is the number of parameters. If calc_second_order is True, the resulting matrix hasN * (2D + 2)
rows. These model inputs are intended to be used withSALib.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