3. Sensitivity Analysis#

3.1. What is Sensitivity Analysis#

Sensitivity Analysis is widely used to determine how different input variables influence the output of a model. It helps identify which inputs have the most significant impact on the results, providing valuable insights for model optimization, uncertainty quantification, and decision-making.

By systematically varying inputs and observing changes in the output, the behavior of complex systems can be better understood.

3.2. Overview of `UQPyL.sensibility`#

The sensibility module of UQPyL provides several sensitivity analysis methods:

Abbreviation	Full Name	References
Sobol’		Sobol (2010), Saltelli (2002)
DT	Delta Test	Eirola et al. (2008)
FAST	Fourier Amplitude Sensitivity Test	Cukier et al. (1973), Saltelli et al. (1999)
RBD-FAST	Random Balance Designs Fourier Amplitude Sensitivity Test	Tarantola et al. (2006), Tissot & Prieur (2012)
MARS-SA	Multivariate Adaptive Regression Splines for Sensitivity Analysis	Friedman (1991)
Morris		Morris (1991)
RSA	Regional Sensitivity Analysis	Hornberger & Spear (1981), Pianosi (2016)

All the methods above inherit from the saABC class in UQPyL.sensibility. The sample() and analyze() functions are predefined and fixed for these methods.

In addition, UQPyL provides a Result class to integrate all useful information during analysis.

Below is the API overview.

3.3. Class `saABC`#

The saABC class is the base class of methods in UQPyL.sensibility, which defines two fixed methods: sample() and analyze().

3.3.1. Constructor#

__init__(...)

3.3.1.1. Description#

Initializes a new instance of a sensitivity analysis (SA) method.

The hyper-parameters are categorized into two parts:

Fixed parameters (valid for all SA methods)
Method-specific parameters (vary by method)

3.3.1.2. Fixed parameters#

scalers (tuple(Scaler, Scaler))

A Python tuple specifying the scalers to be used for normalization. If provided, the method will normalize the input X and output Y during analysis. Each Scaler should be an instance of a class from UQPyL.utility. scalers[0] is used for normalizing X, and scalers[1] is used for normalizing Y.

verboseFlag (bool)

If True, the method outputs detailed logs or progress messages during execution. Useful for debugging or tracking the analysis process. Default: True.

saveFlag (bool)

If True, the analysis result is saved to ./Result/Data. Default: False.

logFlag (bool)

If True, the verbose output is saved to ./Result/Log. Default: False.

3.3.1.3. Other hyper-parameters#

Other parameters vary between different SA methods. For example, FAST defines parameter M, the number of harmonics to sum in the Fourier series decomposition (default: 4).

3.3.2. Methods#

3.3.2.1. `sample`#

3.3.2.1.1. Description#

Generate samples from the decision space.

This is similar to the sample() function in DoE, but is designed for SA methods that require specific sampling schemes.

3.3.2.1.2. Parameters#

problem (Problem)

A Problem instance. This must be specified.

other parameters

Vary between SA methods. Please refer to each specific method.

3.3.2.1.3. Returns#

ndarray (2D)

A 2D NumPy array of generated samples.

3.3.2.2. `analyze`#

3.3.2.2.1. Description#

Perform sensitivity analysis based on input X and output Y for a given problem.

3.3.2.2.2. Parameters#

problem (Problem)

A Problem instance. This must be specified.

X (ndarray)

2D NumPy array of decisions.

Y (ndarray, optional)

2D NumPy array of model outputs. If not provided, it will be evaluated using the problem (e.g. problem.objFunc or problem.evaluate).

3.3.2.2.3. Returns#

res (Result)

A Result instance containing analysis information.

3.4. Class `Result`#

The Result class stores and manages the results of sensitivity analysis.

3.4.1. Attributes#

Si (dict)
    A dictionary storing analysis results with fixed keys:
        'S1' : first-order sensitivity indices
        'S2' : second-order sensitivity indices
        'ST' : total-order sensitivity indices

labels (list)
    List of variable names.

firstOrder (bool)
    True if 'S1' is available in Si.

secondOrder (bool)
    True if 'S2' is available in Si.

totalOrder (bool)
    True if 'ST' is available in Si.

3.5. How to perform sensitivity analysis#

Take the Ishigami function as an example.

Theoretical sensitivity indices:

First-order: \(S_1 = 0.314\), \(S_2 = 0.442\), \(S_3 = 0.000\)
Total-order: \(ST_1 = 0.558\), \(ST_2 = 0.442\), \(ST_3 = 0.244\)

Example usage:

import numpy as np
from UQPyL.problems import Problem
from UQPyL.sensibility import FAST

# Step 1: Define problem
def objFunc(X):
    objs = (np.sin(X[:, 0])
            + 7 * np.sin(X[:, 1])**2
            + 0.1 * X[:, 2]**4 * np.sin(X[:, 0]))
    return objs[:, None]

Ishigami = Problem(
    nInput=3,
    nOutput=1,
    objFunc=objFunc,
    ub=np.pi,
    lb=-np.pi,
    varType=[0, 0, 0],
    name="Ishigami"
)

# Step 2: Create an instance of a SA method
fast = FAST(
    verboseFlag=True,  # Display analysis process in terminal
    saveFlag=True,     # Save results to Result/Data
    logFlag=True       # Save verbose content to Result/Log
)

# Step 3: Generate samples
X = fast.sample(problem=Ishigami, N=500)

# Optional: if Y is not given, fast.analyze will call Ishigami.objFunc internally
Y = Ishigami.objFunc(X)

res = fast.analyze(problem=Ishigami, X=X, Y=Y)

print(res)

3.6. Checking saved sensitivity analysis results (`.hdf`)#

When creating a sensitivity analysis method instance, setting saveFlag or logFlag to True automatically saves outputs to:

Result/Data (for data)
Result/Log (for logs)

The output file containing analysis results is named with the pattern:

A_B_I.hdf

where:

A – name of the SA method (e.g. FAST)
B – name of the problem (e.g. Ishigami)
I – index indicating the run/repetition number

For example, a file named FAST_Ishigami_3.hdf refers to the third execution of the FAST method on the Ishigami problem.