FAST

class FAST(*args)

Fourier Amplitude Sensitivity Testing (FAST).

Refer to Sensitivity analysis by Fourier decomposition.

Parameters:
modelFunction

Definition of the model to analyse.

distributionDistribution

Contains the distributions of each model’s input. Its dimension must be equal to the number of inputs.

Nint, N > Nr

Size of the sample from which the Fourier series are calculated. It represents the length of the discretization of the s-space.

Nrint, Nr \geq 1, optional

Number of resamplings. The extended FAST method involves a part of randomness in the computation of the indices. So it can be asked to realize the procedure Nr times and then to calculate the arithmetic means of the results over the Nr estimates.

Mint, 0 < M < N, optional

Interference factor usually equal to 4 or higher. It corresponds to the truncation level of the Fourier series, i.e. the number of harmonics that are retained in the decomposition.

Notes

FAST is a sensitivity analysis method which is based upon the ANOVA decomposition of the variance of the model response y = f(\vect{X}), the latter being represented by its Fourier expansion. \vect{X}=\{X^1,\dots,X^{n_X}\} is an input random vector of n_X independent components.

OpenTURNS implements the extended FAST method consisting in computing alternately the first order and the total-effect indices of each input. This approach, widely described in the paper by [saltelli1999], relies upon a Fourier decomposition of the model response. Its key idea is to recast this representation as a function of a scalar parameter s, by defining parametric curves s \mapsto x_i(s), i=1, \dots, n_X exploring the support of the input random vector \vect{X}.

Then the Fourier expansion of the model response is:

f(s) = \sum_{k \in \Zset^N} A_k cos(ks) + B_k sin(ks)

where A_k and B_k are Fourier coefficients whose estimates are:

\hat{A}_k &= \frac{1}{N} \sum_{j=1}^N f(x_j^1,\dots,x_j^{N_X}) cos\left(\frac{2k\pi (j-1)}{N} \right) \quad , \quad -\frac{N}{2} \leq k \leq \frac{N}{2} \\
\hat{B}_k &= \frac{1}{N} \sum_{j=1}^N f(x_j^1,\dots,x_j^{N_X}) sin\left(\frac{2k\pi (j-1)}{N} \right) \quad , \quad -\frac{N}{2} \leq k \leq \frac{N}{2}

The first order indices are estimated by:

\hat{S}_i = \frac{\hat{D}_i}{\hat{D}}
          = \frac{\sum_{p=1}^M(\hat{A}_{p\omega_i}^2 + \hat{B}_{p\omega_i}^2)^2}
                  {\sum_{n=1}^{(N-1)/2}(\hat{A}_n^2 + \hat{B}_n^2)^2}

and the total order indices by:

\hat{T}_i = 1 - \frac{\hat{D}_{-i}}{\hat{D}}
          = 1 - \frac{\sum_{k=1}^{\omega_i/2}(\hat{A}_k^2 + \hat{B}_k^2)^2}
                      {\sum_{n=1}^{(N-1)/2}(\hat{A}_n^2 + \hat{B}_n^2)^2}

where \hat{D} is the total variance, \hat{D}_i the portion of D arising from the uncertainty of the i^{th} input and \hat{D}_{-i} is the part of the variance due to all the inputs except the i^{th} input.

N is the size of the sample using to compute the Fourier series and M is the interference factor. Saltelli et al. (1999) recommended to set M to a value in the range [4, 6]. \{\omega_i\}, \forall i=1, \dots, n_X is a set of integer frequencies assigned to each input X^i. The frequency associated with the input for which the sensitivity indices are computed, is set to the maximum admissible frequency satisfying the Nyquist criterion (which ensures to avoid aliasing effects):

\omega_i = \frac{N - 1}{2M}

In the paper by Saltelli et al. (1999), for high sample size, it is suggested that 16 \leq \omega_i/N_r \leq 64.

Examples

>>> import openturns as ot
>>> ot.RandomGenerator.SetSeed(0)
>>> formula = ['sin(pi_*X1)+7*sin(pi_*X2)^2+0.1*(pi_*X3)^4*sin(pi_*X1)']
>>> model = ot.SymbolicFunction(['X1', 'X2', 'X3'], formula)
>>> distribution = ot.JointDistribution([ot.Uniform(-1.0, 1.0)] * 3)
>>> sensitivityAnalysis = ot.FAST(model, distribution, 101)
>>> print(sensitivityAnalysis.getFirstOrderIndices())
[0.311097,0.441786,0.000396837]

Methods

getBlockSize()

Get the block size.

getFFTAlgorithm()

Accessor to the FFT algorithm implementation.

getFirstOrderIndices([marginalIndex])

Accessor to the first order indices.

getTotalOrderIndices([marginalIndex])

Accessor to the total order indices.

setBlockSize(blockSize)

Set the block size.

setFFTAlgorithm(fft)

Accessor to the FFT algorithm implementation.

__init__(*args)
getBlockSize()

Get the block size.

Returns:
kpositive int

Size of each block the sample is split into, this allows one to save space while allowing multithreading, when available we recommend to use the number of available CPUs, set by default to 1.

getFFTAlgorithm()

Accessor to the FFT algorithm implementation.

Returns:
ffta FFT

A FFT algorithm.

getFirstOrderIndices(marginalIndex=0)

Accessor to the first order indices.

Parameters:
marginalIndexint, 0 \leq i < n, optional

Index of the model’s marginal used to estimate the indices. By default, marginalIndex is equal to 0.

Returns:
indicesPoint

List of the first order indices of all the inputs.

getTotalOrderIndices(marginalIndex=0)

Accessor to the total order indices.

Parameters:
marginalIndexint, 0 \leq i < n, optional

Index of the model’s marginal used to estimate the indices. By default, marginalIndex is equal to 0.

Returns:
indicesPoint

List of the total-effect order indices of all the inputs.

setBlockSize(blockSize)

Set the block size.

Parameters:
kpositive int

Size of each block the sample is split into, this allows one to save space while allowing multithreading, when available we recommend to use the number of available CPUs, set by default to 1.

setFFTAlgorithm(fft)

Accessor to the FFT algorithm implementation.

Parameters:
ffta FFT

A FFT algorithm.

Examples using the class

FAST sensitivity indices

FAST sensitivity indices