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

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