SaltelliSensitivityAlgorithm¶

(Source code, png)

class SaltelliSensitivityAlgorithm(*args)¶

Sensitivity analysis using Saltelli method.

Available constructors:

SaltelliSensitivityAlgorithm(inputDesign, outputDesign, N)

SaltelliSensitivityAlgorithm(distribution, N, model, computeSecondOrder)

SaltelliSensitivityAlgorithm(experiment, model, computeSecondOrder)

Parameters:

inputDesignSample: Design for the evaluation of sensitivity indices, obtained with the SobolIndicesExperiment.generate() method
outputDesignSample: Design for the evaluation of sensitivity indices, obtained as the evaluation of a Function (model) on the previous inputDesign
distributionDistribution: Input probabilistic model. Should have independent copula
experimentWeightedExperiment: Experiment for the generation of two independent samples.
Nint: Size of samples to generate
modelFunction: Model to evaluate input samples.
computeSecondOrderbool: If True, design that will be generated contains elements for the evaluation of second order indices.

Methods

`DrawCorrelationCoefficients`(*args)	Draw the correlation coefficients.
`DrawImportanceFactors`(*args)	Draw the importance factors.
`DrawSobolIndices`(*args)	Draw the Sobol' indices.
`draw`(*args)	Draw sensitivity indices.
`getAggregatedFirstOrderIndices`()	Get the evaluation of aggregated first order Sobol indices.
`getAggregatedTotalOrderIndices`()	Get the evaluation of aggregated total order Sobol indices.
`getBootstrapSize`()	Get the number of bootstrap sampling size.
`getClassName`()	Accessor to the object's name.
`getConfidenceLevel`()	Get the confidence interval level for confidence intervals.
`getFirstOrderIndices`([marginalIndex])	Get first order Sobol indices.
`getFirstOrderIndicesDistribution`()	Get the distribution of the aggregated first order Sobol indices.
`getFirstOrderIndicesInterval`()	Get interval for the aggregated first order Sobol indices.
`getName`()	Accessor to the object's name.
`getSecondOrderIndices`([marginalIndex])	Get second order Sobol indices.
`getTotalOrderIndices`([marginalIndex])	Get total order Sobol indices.
`getTotalOrderIndicesDistribution`()	Get the distribution of the aggregated total order Sobol indices.
`getTotalOrderIndicesInterval`()	Get interval for the aggregated total order Sobol indices.
`getUseAsymptoticDistribution`()	Select asymptotic or bootstrap confidence intervals.
`hasName`()	Test if the object is named.
`setBootstrapSize`(bootstrapSize)	Set the number of bootstrap sampling size.
`setConfidenceLevel`(confidenceLevel)	Set the confidence interval level for confidence intervals.
`setDesign`(inputDesign, outputDesign, size)	Sample accessor.
`setName`(name)	Accessor to the object's name.
`setUseAsymptoticDistribution`(...)	Select asymptotic or bootstrap confidence intervals.

See also

SobolIndicesAlgorithm

Notes

This class analyzes the influence of each component of a random vector $\vect{X} = \left( X_1, \ldots, X_{n_X} \right)$ on a random vector $\vect{Y} = \left( Y_1, \ldots, Y_{n_Y} \right)$ by computing Sobol’ indices (see also [sobol1993]). The [saltelli2002] method is used to estimate both first and total order indices. Notations are defined in the documentation page of the SobolIndicesAlgorithm class. The estimators of $V_i$ and $V_{-i}$ used by this class are respectively:

$\widehat{V}_i & = \frac{1}{N-1}\sum_{k=1}^{N} \tilde{\vect{g}}(\vect{B}_k) \tilde{\vect{g}}(\vect{E}_k) - \left(\frac{1}{N} \sum_{k=1}^{N} \tilde{\vect{g}}(\vect{A}_k)\right) \left(\frac{1}{N} \sum_{k=1}^{N} \tilde{\vect{g}}(\vect{B}_k)\right) \\ \widehat{V}_{-i} & = \frac{1}{N-1}\sum_{k=1}^{N} \tilde{\vect{g}}(\vect{A}_k) \tilde{\vect{g}}(\vect{E}_k) - \left(\frac{1}{N} \sum_{k=1}^{N} \tilde{\vect{g}}(\vect{A}_k)\right) \left(\frac{1}{N} \sum_{k=1}^{N} \tilde{\vect{g}}(\vect{B}_k)\right)$

where $\tilde{\vect{g}}$ is the centered model based on the sample.

The class constructor SaltelliSensitivityAlgorithm(inputDesign, outputDesign, N) requires a specific structure for the outputDesign, and therefore for the inputDesign . The latter should be generated using SobolIndicesExperiment (see example below). Otherwise, results will be worthless.

Examples

Estimate first and total order Sobol’ indices:

>>> 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)
>>> # Define designs to pre-compute
>>> size = 10000
>>> inputDesign = ot.SobolIndicesExperiment(distribution, size).generate()
>>> outputDesign = model(inputDesign)
>>> # sensitivity analysis algorithm
>>> sensitivityAnalysis = ot.SaltelliSensitivityAlgorithm(inputDesign, outputDesign, size)
>>> print(sensitivityAnalysis.getFirstOrderIndices())
[0.302745,0.460846,0.0066916]
>>> print(sensitivityAnalysis.getTotalOrderIndices())
[0.574996,0.427126,0.256689]

__init__(*args)¶

static DrawCorrelationCoefficients(*args)¶

Draw the correlation coefficients.

As correlation coefficients are considered, values might be positive or negative.

Available usages:

DrawCorrelationCoefficients(correlationCoefficients, title=’Correlation coefficients’)

DrawCorrelationCoefficients(values, names, title=’Correlation coefficients’)

Parameters:

correlationCoefficientsPointWithDescription: Sequence containing the correlation coefficients with a description for each component. The descriptions are used to build labels for the created graph. If they are not mentioned, default labels will be used.
valuessequence of float: Correlation coefficients.
namessequence of str: Variables’ names used to build labels for the created the graph.
titlestr: Title of the graph.

Returns:

graphGraph: A graph containing a Cloud and a Text of the correlation coefficients.

static DrawImportanceFactors(*args)¶

Draw the importance factors.

Available usages:

DrawImportanceFactors(importanceFactors, title=’Importance Factors’)

DrawImportanceFactors(values, names, title=’Importance Factors’)

Parameters:

importanceFactorsPointWithDescription: Sequence containing the importance factors with a description for each component. The descriptions are used to build labels for the created Pie. If they are not mentioned, default labels will be used.
valuessequence of float: Importance factors.
namessequence of str: Variables’ names used to build labels for the created Pie.
titlestr: Title of the graph.

Returns:

graphGraph: A graph containing a Pie of the importance factors of the variables.

static DrawSobolIndices(*args)¶

Draw the Sobol’ indices.

Parameters:

inputDescriptionsequence of str: Variable names
firstOrderIndicessequence of float: First order indices values
totalOrderIndicessequence of float: Total order indices values
fo_ciInterval, optional: First order indices confidence interval
to_ciInterval, optional: Total order indices confidence interval

Returns:

graphGraph: For each variable, draws first and total indices

draw(*args)¶

Draw sensitivity indices.

Usage:

draw()

draw(marginalIndex)

With the first usage, draw the aggregated first and total order indices. With the second usage, draw the first and total order indices of a specific marginal in case of vectorial output

Parameters:

marginalIndex: int: marginal of interest (case of second usage)

Returns:

graphGraph: A graph containing the aggregated first and total order indices.

Notes

If number of bootstrap sampling is not 0, and confidence level associated > 0, the graph includes confidence interval plots in the first usage.

getAggregatedFirstOrderIndices()¶

Get the evaluation of aggregated first order Sobol indices.

Returns:

indicesPoint: Sequence containing aggregated first order Sobol indices.

getAggregatedTotalOrderIndices()¶

Get the evaluation of aggregated total order Sobol indices.

Returns:

indicesPoint: Sequence containing aggregated total order Sobol indices.

getBootstrapSize()¶

Get the number of bootstrap sampling size.

Returns:

bootstrapSizeint: Number of bootstrap sampling

getClassName()¶

Accessor to the object’s name.

Returns:

class_namestr: The object class name (object.__class__.__name__).

getConfidenceLevel()¶

Get the confidence interval level for confidence intervals.

Returns:

confidenceLevelfloat: Confidence level for confidence intervals

getFirstOrderIndices(marginalIndex=0)¶

Get first order Sobol indices.

Parameters:

marginalIndexint, optional: Index of the output marginal of the function, equal to $0$ by default.

Returns:

indicesPoint: Sequence containing first order Sobol indices.

getFirstOrderIndicesDistribution()¶

Get the distribution of the aggregated first order Sobol indices.

Returns:

distributionDistribution: Distribution for first order Sobol indices for each component.

getFirstOrderIndicesInterval()¶

Get interval for the aggregated first order Sobol indices.

Returns:

intervalInterval: Interval for first order Sobol indices for each component. Computed marginal by marginal (not from the joint distribution).

getName()¶

Accessor to the object’s name.

Returns:

namestr: The name of the object.

getSecondOrderIndices(marginalIndex=0)¶

Get second order Sobol indices.

Parameters:

marginalIndexint, optional: Index of the output marginal of the function, equals to $0$ by default.

Returns:

indicesSymmetricMatrix: Tensor containing second order Sobol indices.

Notes

Let $n_X \in \Nset$ be the input dimension of the random vector. For any pair of indices $i, j \in \{1, ..., n_x\}$ such that $i \neq j$ , this method computes the Sobol’ interaction index between $i$ and $j$ :

$S_{\{i, j\}} = \frac{V_{\{i,j\}}}{\Var{Y}}$

The second order Sobol’ index $S_{i,j}$ measures the part of the variance of $Y$ explained by the interaction of $X_i$ and $X_j$ . Hence, the closed Sobol’ index of the group $\{i, j\}$ is:

$S_{\{i, j\}}^{\operatorname{cl}} = S_i + S_j + S_{\{i, j\}}.$

Conversely, if the closed Sobol’ index $S_{\{i, j\}}^{\operatorname{cl}}$ is known, then the interaction Sobol’ index can be computed from the equation:

$S_{\{i, j\}} = S_{\{i, j\}}^{\operatorname{cl}} - S_i - S_j.$

getTotalOrderIndices(marginalIndex=0)¶

Get total order Sobol indices.

Parameters:

marginalIndexint, optional: Index of the output marginal of the function, equal to $0$ by default.

Returns:

indicesPoint: Sequence containing total order Sobol indices.

getTotalOrderIndicesDistribution()¶

Get the distribution of the aggregated total order Sobol indices.

Returns:

distributionDistribution: Distribution for total order Sobol indices for each component.

getTotalOrderIndicesInterval()¶

Get interval for the aggregated total order Sobol indices.

Returns:

intervalInterval: Interval for total order Sobol indices for each component. Computed marginal by marginal (not from the joint distribution).

getUseAsymptoticDistribution()¶

Select asymptotic or bootstrap confidence intervals.

Returns:

useAsymptoticDistributionbool: Whether to use bootstrap or asymptotic intervals

hasName()¶

Test if the object is named.

Returns:

hasNamebool: True if the name is not empty.

setBootstrapSize(bootstrapSize)¶

Set the number of bootstrap sampling size.

Default value is 0.

Parameters:

bootstrapSizeint: Number of bootstrap sampling

setConfidenceLevel(confidenceLevel)¶

Set the confidence interval level for confidence intervals.

Parameters:

confidenceLevelfloat: Confidence level for confidence intervals

setDesign(inputDesign, outputDesign, size)¶

Sample accessor.

Allows one to estimate indices from a predefined Sobol design.

Parameters:

inputDesignSample: Design for the evaluation of sensitivity indices, obtained thanks to the SobolIndicesAlgorithmImplementation.Generate method
outputDesignSample: Design for the evaluation of sensitivity indices, obtained as the evaluation of a Function (model) on the previous inputDesign
Nint: Base size of the Sobol design