MartinezSensitivityAlgorithm¶

(Source code, 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 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.

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 [martinez2011] 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 the first and total order Sobol’ indices used by this class are respectively:

$\hat{S}_i & = \tilde{\rho}_n\left(\tilde{\vect{g}}(\mat{B}), \tilde{\vect{g}}(\mat{E}^i)\right) \\ \widehat{S}_i^T & = 1 - \tilde{\rho}_n\left(\tilde{\vect{g}}(\mat{A}), \tilde{\vect{g}}(\mat{E}^i)\right) \\$

where $\tilde{\rho}_n$ is the modified sample correlation (under the assumption that the sample has a zero mean) defined, for any pair of vectors $(\vect{z}, \vect{z}') \in \Rset^N \times \Rset^N$ , by:

$\tilde{\rho}_n \left(\vect{z}, \vect{z}'\right) = \frac{\sum_{k=1}^N z_k z_k'} {\sqrt{\sum_{k=1}^N z_k^2} \sqrt{\sum_{k=1}^N \left( z_k' \right)^2}}$

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

The class constructor MartinezSensitivityAlgorithm(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.MartinezSensitivityAlgorithm(inputDesign, outputDesign, size)
>>> print(sensitivityAnalysis.getFirstOrderIndices())
[0.308902,0.459187,0.00683867]
>>> print(sensitivityAnalysis.getTotalOrderIndices())
[0.567786,0.430754,0.244293]

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.

__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

setName(name)¶

Accessor to the object’s name.

Parameters:

namestr: The name of the object.

setUseAsymptoticDistribution(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

Examples using the class¶

Estimate Sobol’ indices for the Ishigami function by a sampling method: a quick start guide to sensitivity analysis

Estimate Sobol' indices for the Ishigami function by a sampling method: a quick start guide to sensitivity analysis

OpenTURNS

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

Table of Contents

Previous topic

Next topic

This Page

MartinezSensitivityAlgorithm¶

Examples using the class¶