MartinezSensitivityAlgorithm

(Source code, png, hires.png, pdf)

../../_images/MartinezSensitivityAlgorithm.png
class MartinezSensitivityAlgorithm(*args)

Sensitivity analysis using Martinez method.

Available constructors:

MartinezSensitivityAlgorithm(inputDesign, outputDesign, N)

MartinezSensitivityAlgorithm(distribution, N, model, computeSecondOrder)

MartinezSensitivityAlgorithm(experiment, model, computeSecondOrder)

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

distributionDistribution

Input probabilistic model. Should have independent copula

experimentWeightedExperiment

Experiment for the generation of two independent samples.

Nint

Size of samples to generate

computeSecondOrderbool

If True, design that will be generated contains elements for the evaluation of second order indices.

Notes

This class is concerned with analyzing the influence the random vector \vect{X} = \left( X^1, \ldots, X^{n_X} \right) has on a random variable Y^k which is being studied for uncertainty, by using the [martinez2011] method for the evaluation of both first and total order indices.

These last ones are respectively given as follows:

\begin{array}{ccc}
\hat{S_i} & = & \rho_n(G(B), G(E^i)) \\
\hat{ST_i} & = & 1 - \rho_n(G(A), G(E^i)) \\
\end{array}

where \rho_n is the empirical correlation defined by:

\rho_n(X, Y) = \frac{\Cov{X,Y}}{\sqrt{\Var{X} \Var{Y}}}

The variance of the estimator is computed using:

\begin{array}{ccc}
U_i = \left(\left(\textsuperscript{c}Y_i^B \textsuperscript{c}Y_i^E \right), \left(\textsuperscript{c}Y_i^B\right)^2, \left(\textsuperscript{c}Y_i^E \right)^2 \right)^T \\
\Psi_i(x, y, z) = \frac{x}{\sqrt{y\times z}}
\end{array}

\begin{array}{ccc}
U_{-i} = \left(\textsuperscript{c}Y_i^A \textsuperscript{c}Y_i^E, \left(\textsuperscript{c}Y_i^A\right)^2, \left(\textsuperscript{c}Y_i^E\right)^2 \right)^T \\
\Psi_{-i}(x, y, z) = 1 - \frac{x}{\sqrt{y\times z}}
\end{array}

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.ComposedDistribution([ot.Uniform(-1.0, 1.0)] * 3)
>>> # Define designs to pre-compute
>>> size = 100
>>> inputDesign = ot.SobolIndicesExperiment(distribution, size).generate()
>>> outputDesign = model(inputDesign)
>>> # sensitivity analysis algorithm
>>> sensitivityAnalysis = ot.MartinezSensitivityAlgorithm(inputDesign, outputDesign, size)
>>> print(sensitivityAnalysis.getFirstOrderIndices())
[0.30449,0.448506,-0.0711394]
>>> print(sensitivityAnalysis.getTotalOrderIndices())
[0.543004,0.29501,0.304615]

Estimate first, total and second 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.ComposedDistribution([ot.Uniform(-1.0, 1.0)] * 3)
>>> # Define designs to pre-compute
>>> size = 100
>>> computeSecondOrderIndices = True
>>> inputDesign = ot.SobolIndicesExperiment(distribution, size, computeSecondOrderIndices).generate()
>>> outputDesign = model(inputDesign)
>>> # sensitivity analysis algorithm
>>> sensitivityAnalysis = ot.MartinezSensitivityAlgorithm(inputDesign, outputDesign, size)
>>> print(sensitivityAnalysis.getFirstOrderIndices())
[0.30449,0.448506,-0.0711394]
>>> print(sensitivityAnalysis.getTotalOrderIndices())
[0.543004,0.29501,0.304615]
>>> print(sensitivityAnalysis.getSecondOrderIndices())
[[  0        -0.18008   0.169767 ]
 [ -0.18008   0        -0.198839 ]
 [  0.169767 -0.198839  0        ]]

Methods

DrawCorrelationCoefficients(\*args)

Draw the correlation coefficients.

DrawImportanceFactors(\*args)

Draw the importance factors.

DrawSobolIndices(inputDescription, …)

Draw the Sobol’ indices.

draw(self, \*args)

Draw sensitivity indices.

getAggregatedFirstOrderIndices(self)

Get the evaluation of aggregated first order Sobol indices.

getAggregatedTotalOrderIndices(self)

Get the evaluation of aggregated total order Sobol indices.

getBootstrapSize(self)

Get the number of bootstrap sampling size.

getClassName(self)

Accessor to the object’s name.

getConfidenceLevel(self)

Get the confidence interval level for confidence intervals.

getFirstOrderIndices(self[, marginalIndex])

Get first order Sobol indices.

getFirstOrderIndicesDistribution(self)

Get the distribution of the aggregated first order Sobol indices.

getFirstOrderIndicesInterval(self)

Get interval for the aggregated first order Sobol indices.

getId(self)

Accessor to the object’s id.

getName(self)

Accessor to the object’s name.

getSecondOrderIndices(self[, marginalIndex])

Get second order Sobol indices.

getShadowedId(self)

Accessor to the object’s shadowed id.

getTotalOrderIndices(self[, marginalIndex])

Get total order Sobol indices.

getTotalOrderIndicesDistribution(self)

Get the distribution of the aggregated total order Sobol indices.

getTotalOrderIndicesInterval(self)

Get interval for the aggregated total order Sobol indices.

getUseAsymptoticDistribution(self)

Select asymptotic or bootstrap confidence intervals.

getVisibility(self)

Accessor to the object’s visibility state.

hasName(self)

Test if the object is named.

hasVisibleName(self)

Test if the object has a distinguishable name.

setBootstrapSize(self, bootstrapSize)

Set the number of bootstrap sampling size.

setConfidenceLevel(self, confidenceLevel)

Set the confidence interval level for confidence intervals.

setDesign(self, inputDesign, outputDesign, size)

Sample accessor.

setName(self, name)

Accessor to the object’s name.

setShadowedId(self, id)

Accessor to the object’s shadowed id.

setUseAsymptoticDistribution(self, …)

Select asymptotic or bootstrap confidence intervals.

setVisibility(self, visible)

Accessor to the object’s visibility state.

__init__(self, \*args)

Initialize self. See help(type(self)) for accurate signature.

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(inputDescription, firstOrderIndices, secondOrderIndices)

Draw the Sobol’ indices.

Parameters
inputDescriptionsequence of str

Variable names

firstOrderIndicessequence of float

First order indices values

totalOrderIndicessequence of float

Total order indices values

Returns
GraphGraph

For each variable, draws first and total indices

draw(self, \*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(self)

Get the evaluation of aggregated first order Sobol indices.

Returns
indicesPoint

Sequence containing aggregated first order Sobol indices.

getAggregatedTotalOrderIndices(self)

Get the evaluation of aggregated total order Sobol indices.

Returns
indicesPoint

Sequence containing aggregated total order Sobol indices.

getBootstrapSize(self)

Get the number of bootstrap sampling size.

Returns
bootstrapSizeint

Number of bootsrap sampling

getClassName(self)

Accessor to the object’s name.

Returns
class_namestr

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

getConfidenceLevel(self)

Get the confidence interval level for confidence intervals.

Returns
confidenceLevelfloat

Confidence level for confidence intervals

getFirstOrderIndices(self, marginalIndex=0)

Get first order Sobol indices.

Parameters
iint, optional

Index of the marginal of the function, equals to 0 by default.

Returns
indicesPoint

Sequence containing first order Sobol indices.

getFirstOrderIndicesDistribution(self)

Get the distribution of the aggregated first order Sobol indices.

Returns
distributionDistribution

Distribution for first order Sobol indices for each component.

getFirstOrderIndicesInterval(self)

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).

getId(self)

Accessor to the object’s id.

Returns
idint

Internal unique identifier.

getName(self)

Accessor to the object’s name.

Returns
namestr

The name of the object.

getSecondOrderIndices(self, marginalIndex=0)

Get second order Sobol indices.

Parameters
iint, optional

Index of the marginal of the function, equals to 0 by default.

Returns
indicesSymmetricMatrix

Tensor containing second order Sobol indices.

getShadowedId(self)

Accessor to the object’s shadowed id.

Returns
idint

Internal unique identifier.

getTotalOrderIndices(self, marginalIndex=0)

Get total order Sobol indices.

Parameters
iint, optional

Index of the marginal of the function, equals to 0 by default.

Returns
indicesPoint

Sequence containing total order Sobol indices.

getTotalOrderIndicesDistribution(self)

Get the distribution of the aggregated total order Sobol indices.

Returns
distributionDistribution

Distribution for total order Sobol indices for each component.

getTotalOrderIndicesInterval(self)

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(self)

Select asymptotic or bootstrap confidence intervals.

Returns
useAsymptoticDistributionbool

Whether to use bootstrap or asymptotic intervals

getVisibility(self)

Accessor to the object’s visibility state.

Returns
visiblebool

Visibility flag.

hasName(self)

Test if the object is named.

Returns
hasNamebool

True if the name is not empty.

hasVisibleName(self)

Test if the object has a distinguishable name.

Returns
hasVisibleNamebool

True if the name is not empty and not the default one.

setBootstrapSize(self, bootstrapSize)

Set the number of bootstrap sampling size.

Default value is 0.

Parameters
bootstrapSizeint

Number of bootsrap sampling

setConfidenceLevel(self, confidenceLevel)

Set the confidence interval level for confidence intervals.

Parameters
confidenceLevelfloat

Confidence level for confidence intervals

setDesign(self, inputDesign, outputDesign, size)

Sample accessor.

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

Size of samples to generate

setName(self, name)

Accessor to the object’s name.

Parameters
namestr

The name of the object.

setShadowedId(self, id)

Accessor to the object’s shadowed id.

Parameters
idint

Internal unique identifier.

setUseAsymptoticDistribution(self, useAsymptoticDistribution)

Select asymptotic or bootstrap confidence intervals.

Default value is set by the SobolIndicesAlgorithm-DefaultUseAsymptoticDistribution key.

Parameters
useAsymptoticDistributionbool

Whether to use bootstrap or asymptotic intervals

setVisibility(self, visible)

Accessor to the object’s visibility state.

Parameters
visiblebool

Visibility flag.