Advanced Examples#

Group sampling (Sobol and Morris methods only)#

It is sometimes useful to perform sensitivity analysis on groups of input variables to reduce the number of model runs required, when variables belong to the same component of a model, or there is some reason to believe that they should behave similarly.

Groups can be specified in two ways for the Sobol and Morris methods.

First, as a fourth column in the parameter file:

# name lower_bound upper_bound group_name
P1 0.0 1.0 Group_1
P2 0.0 5.0 Group_2
P3 0.0 5.0 Group_2
...etc.

Or in the problem dictionary:

problem = {
    'groups': ['Group_1', 'Group_2', 'Group_2'],
    'names': ['x1', 'x2', 'x3'],
    'num_vars': 3,
    'bounds': [[-3.14, 3.14], [-3.14, 3.14], [-3.14, 3.14]]
}

groups is a list of strings specifying the group name to which each variable belongs. The rest of the code stays the same:

param_values = saltelli.sample(problem, 1024)
Y = Ishigami.evaluate(param_values)
Si = sobol.analyze(problem, Y, print_to_console=True)

But the output is printed by group:

            ST   ST_conf
Group_1  0.555309  0.084058
Group_2  0.684332  0.057449
            S1   S1_conf
Group_1  0.316696  0.056797
Group_2  0.456497  0.079049
                        S2   S2_conf
(Group_1, Group_2)  0.238909  0.127195

The output can then be converted to a Pandas DataFrame for further analysis.

total_Si, first_Si, second_Si = Si.to_df()

Generating alternate distributions#

In Essential basic functionality, we generate a uniform sample of parameter space.

from SALib.sample import saltelli
from SALib.analyze import sobol
from SALib.test_functions import Ishigami
import numpy as np

problem = {
    'num_vars': 3,
    'names': ['x1', 'x2', 'x3'],
    'bounds': [[-3.14159265359, 3.14159265359],
               [-3.14159265359, 3.14159265359],
               [-3.14159265359, 3.14159265359]]
}

param_values = saltelli.sample(problem, 1024)

SALib is also capable of generating alternate sampling distributions by specifying a dists entry in the problem specification.

As implied in the basic example, a uniform distribution is the default.

When an entry for dists is not ‘unif’, the bounds entry does not indicate parameter bounds but sample-specific metadata.

bounds definitions for available distributions:

  • unif: uniform distribution

    e.g. [-np.pi, np.pi] defines the lower and upper bounds

  • triang: triangular with lower and upper bounds, as well as

    location of peak The location of peak is in percentage of width e.g. [1.0, 3.0, 0.5] indicates 1.0 to 3.0 with a peak at 2.0

    A soon-to-be deprecated two-value format assumes the lower bound to be 0 e.g. [3, 0.5] assumes 0 to 3, with a peak at 1.5

  • norm: normal distribution with mean and standard deviation

  • lognorm: lognormal with ln-space mean and standard deviation

An example specification is shown below:

problem = {
    'names': ['x1', 'x2', 'x3'],
    'num_vars': 3,
    'bounds': [[-np.pi, np.pi], [1.0, 0.2], [3, 0.5]],
    'groups': ['G1', 'G2', 'G1'],
    'dists': ['unif', 'lognorm', 'triang']
}