Skip to main content
`Ctrl`+`K`

# 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

    |            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

- logunif: logarithmic uniform with 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

- truncnorm: truncated normal distribution with lower and upper bounds, 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']
    }