MartinezSensitivityAlgorithm¶

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

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.

See also

SobolIndicesAlgorithm

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.

OpenTURNS

An Open source initiative for the Treatment of Uncertainties, Risks'N Statistics

Previous topic

Next topic

This Page

MartinezSensitivityAlgorithm¶