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 contructor 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)¶: Initialize self. See help(type(self)) for accurate signature.

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.

OpenTURNS

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

Previous topic

Next topic

This Page

SobolIndicesExperiment¶