SobolIndicesExperiment¶

class SobolIndicesExperiment(*args)¶

Experiment to computeSobol’ indices.

Available constructors:

SobolIndicesExperiment(distribution, size, computeSecondOrder=False)

SobolIndicesExperiment(experiment, computeSecondOrder=False)

Parameters:

distributionDistribution: Distribution $\mu$ with an independent copula used to generate the set of input data.
sizepositive int: Size $N$ of each of the two independent initial samples. For the total size of the experiment see notes below.
experimentWeightedExperiment: Design of experiment used to sample the distribution.
computeSecondOrderbool, defaults to False: Whether to add points to compute second order indices

See also

SobolIndicesAlgorithm

Notes

Sensitivity algorithms rely on the definition of specific designs.

The generate() method of this class produces a Sample to be supplied to the constructor of one of the SobolIndicesAlgorithm implementations:

The chosen SobolIndicesAlgorithm implementation then uses the sample as input design, which means it represents (but is not a realization of) a random vector $\vect{X} = \left( X^1, \ldots, X^{n_X} \right)$ .

Either the Distribution of $\vect{X}$ or a WeightedExperiment that represents it must be supplied to the class constructor.

If a WeightedExperiment is supplied, the class uses it directly.

If the distribution of $\vect{X}$ is supplied, the class generates a WeightedExperiment. To do this, it duplicates the distribution: every marginal is repeated once to produce a $2 n_X$ -dimensional distribution. This trick makes it possible to choose a WeightedExperiment with non-iid samples (that is a LHSExperiment or a LowDiscrepancyExperiment) to represent the original $n_X$ -dimensional distribution.

The type of WeightedExperiment depends on the value of 'SobolIndicesExperiment-SamplingMethod' in the ResourceMap:

'MonteCarlo' for a MonteCarloExperiment.

'LHS' for an LHSExperiment with alwaysShuffle and randomShift set to True.

'QMC' for a LowDiscrepancyExperiment (with randomize flag set to False) built from a SobolSequence.

'MonteCarlo' is the default choice because it allows the chosen SobolIndicesAlgorithm implementation to use the asymptotic distribution of the estimators of the Sobol’ indices.

Note that 'QMC' is only possible if $2 n_X \leqslant$ SobolSequence.MaximumDimension. If 'QMC' is specified but $2 n_X >$ SobolSequence.MaximumDimension, the class falls back to 'LHS'.

>>> from openturns import SobolSequence
>>> print(SobolSequence.MaximumDimension)
1111

Regardless of the type of WeightedExperiment, the class splits it into two samples with the same size $N$ : $\mat{A}$ and $\mat{B}$ . Their columns are mixed in order to produce a very large sample: the inputDesign argument taken by one of the constructors of every SobolIndicesAlgorithm implementation.

If computeSecondOrder is set to False, the input design is of size $N(2+n_X)$ . The first $N$ rows contain the sample $\mat{A}$ and the next $N$ rows the sample $\mat{B}$ . The last $N n_X$ rows contain $n_X$ copies of $\mat{A}$ , each with a different column replaced by the corresponding column from $\mat{B}$ (they are the matrices $\mat{E}^i$ from the documentation page of SobolIndicesAlgorithm).

If computeSecondOrder is set to True and $n_X = 2$ , the input design is the same as in the case where computeSecondOrder is False (see [saltelli2002]).

If computeSecondOrder is set to True and $n_X \neq 2$ , the input design size is $N(2+2 n_X)$ . The first $N(2+n_X)$ rows are the same as when computeSecondOrder is False. The last $N n_X$ rows contain $n_X$ copies of $\mat{B}$ , each with a different column replaced by the corresponding column from $\mat{A}$ (they are the matrices $\mat{C}^i$ from the documentation page of SobolIndicesAlgorithm).

Examples

Create a sample suitable to 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)
>>> size = 10
>>> experiment = ot.SobolIndicesExperiment(distribution, size)
>>> sample = experiment.generate()

Create a sample suitable to estimate first, total order 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)
>>> size = 10
>>> computeSecondOrder = True
>>> experiment = ot.SobolIndicesExperiment(distribution, size, computeSecondOrder)
>>> sample = experiment.generate()

Methods

`generate`()	Generate points according to the type of the experiment.
`generateWithWeights`(weights)	Generate points and their associated weight according to the type of the experiment.
`getClassName`()	Accessor to the object's name.
`getDistribution`()	Accessor to the distribution.
`getId`()	Accessor to the object's id.
`getName`()	Accessor to the object's name.
`getShadowedId`()	Accessor to the object's shadowed id.
`getSize`()	Accessor to the size of the generated sample.
`getVisibility`()	Accessor to the object's visibility state.
`hasName`()	Test if the object is named.
`hasUniformWeights`()	Ask whether the experiment has uniform weights.
`hasVisibleName`()	Test if the object has a distinguishable name.
`setDistribution`(distribution)	Accessor to the distribution.
`setName`(name)	Accessor to the object's name.
`setShadowedId`(id)	Accessor to the object's shadowed id.
`setSize`(size)	Accessor to the size of the generated sample.
`setVisibility`(visible)	Accessor to the object's visibility state.

getWeightedExperiment

__init__(*args)¶

generate()¶

Generate points according to the type of the experiment.

Returns:

sampleSample: Points $(\Xi_i)_{i \in I}$ which constitute the design of experiments with $card I = size$ . The sampling method is defined by the nature of the weighted experiment.

Examples

>>> import openturns as ot
>>> ot.RandomGenerator.SetSeed(0)
>>> myExperiment = ot.MonteCarloExperiment(ot.Normal(2), 5)
>>> sample = myExperiment.generate()
>>> print(sample)
    [ X0        X1        ]
0 : [  0.608202 -1.26617  ]
1 : [ -0.438266  1.20548  ]
2 : [ -2.18139   0.350042 ]
3 : [ -0.355007  1.43725  ]
4 : [  0.810668  0.793156 ]

generateWithWeights(weights)¶

Generate points and their associated weight according to the type of the experiment.

Returns:

sampleSample: The points which constitute the design of experiments. The sampling method is defined by the nature of the experiment.
weightsPoint of size $cardI$: Weights $(\omega_i)_{i \in I}$ associated with the points. By default, all the weights are equal to $1/cardI$ .

Examples

>>> import openturns as ot
>>> ot.RandomGenerator.SetSeed(0)
>>> myExperiment = ot.MonteCarloExperiment(ot.Normal(2), 5)
>>> sample, weights = myExperiment.generateWithWeights()
>>> print(sample)
    [ X0        X1        ]
0 : [  0.608202 -1.26617  ]
1 : [ -0.438266  1.20548  ]
2 : [ -2.18139   0.350042 ]
3 : [ -0.355007  1.43725  ]
4 : [  0.810668  0.793156 ]
>>> print(weights)
[0.2,0.2,0.2,0.2,0.2]

getClassName()¶

Accessor to the object’s name.

Returns:

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

getDistribution()¶

Accessor to the distribution.

Returns:

distributionDistribution: Distribution used to generate the set of input data.

getId()¶

Accessor to the object’s id.

Returns:

idint: Internal unique identifier.

getName()¶

Accessor to the object’s name.

Returns:

namestr: The name of the object.

getShadowedId()¶

Accessor to the object’s shadowed id.

Returns:

idint: Internal unique identifier.

getSize()¶

Accessor to the size of the generated sample.

Returns:

sizepositive int: Number $cardI$ of points constituting the design of experiments.

getVisibility()¶

Accessor to the object’s visibility state.

Returns:

visiblebool: Visibility flag.

hasName()¶

Test if the object is named.

Returns:

hasNamebool: True if the name is not empty.

hasUniformWeights()¶

Ask whether the experiment has uniform weights.

Returns:

hasUniformWeightsbool: Whether the experiment has uniform weights.

hasVisibleName()¶

Test if the object has a distinguishable name.

Returns:

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

setDistribution(distribution)¶

Accessor to the distribution.

Parameters:

distributionDistribution: Distribution used to generate the set of input data.

setName(name)¶

Accessor to the object’s name.

Parameters:

namestr: The name of the object.

setShadowedId(id)¶

Accessor to the object’s shadowed id.

Parameters:

idint: Internal unique identifier.

setSize(size)¶

Accessor to the size of the generated sample.

Parameters:

sizepositive int: Number $cardI$ of points constituting the design of experiments.

setVisibility(visible)¶

Accessor to the object’s visibility state.

Parameters:

visiblebool: Visibility flag.

Examples using the class¶

Estimate correlation coefficients

Estimate Sobol’ indices for a function with multivariate output

Estimate Sobol' indices for a function with multivariate output

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

Example of sensitivity analyses on the wing weight model

OpenTURNS

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

Table of Contents

Previous topic

Next topic

This Page

SobolIndicesExperiment¶

Examples using the class¶