RankSobolSensitivityAlgorithm¶

class RankSobolSensitivityAlgorithm(*args)¶

Sensitivity analysis using rank-based method.

Parameters:

inputDesignSample: The input sample used for the Sobol’ sensitivity analysis
outputDesignSample: The output sample used for the Sobol’ sensitivity analysis

Notes

This method allows one to compute the first order Sobol’ indices given some input / output samples [gamboa2022]. It is not yet extended to higher order indices as well as total order indices.

Considering the input random vector $\vect{X} = (X_1,\dots,X_{n_X})$ and let $\vect{Y} = (Y_1,\dots,Y_{n_Y})$ be the output of the physical model:

$\vect{Y} = g(X_1,\dots,X_{n_X})$

In the following description Y is considered as scalar, without loss of generality.

Main assumptions:

$X_1,\dots,X_{n_X}$ are independent and scalar
$\mathbb{E}[\parallel Y \parallel^2] < \infty$

We want to estimate the first order Sobol’ index $S_k$ with respect to $X_k$ for $k\in\{1,\dots,{n_X}\}$

$S_k = \frac{\mathbb{V}(\mathbb{E}[Y|X_k])}{\mathbb{V}(Y)}$

Let’s consider a i.i.d. N-sample of the input/output pair $(X_k,Y)$ given by:

$(X_{k,1},Y_1),(X_{k,2},Y_2),\dots,(X_{k,N},Y_N)$

The pairs $(X_{k,(1)},Y_{(k,1)}),(X_{k,(2)},Y_{(k,2)}),\dots,(X_{k,(N)},Y_{(k,N)})$ are ranked (noted using lower scripts under brackets) in such a way that: $X_{k,(1)} \leq X_{k,(2)} \leq \dots \leq X_{k,(N)}.$

The first order Sobol’ indices estimated based on ranks are given by:

$S_{k_{N,rank}} = \frac{\frac{1}{N}\sum_{i=1}^{N} Y_{(k,i)}Y_{(k,i+1)}-\left(\frac{1}{N}\sum_{i=1}^N Y_i\right)^2}{\frac{1}{N}\sum_{i=1}^N Y_i^2-\left(\frac{1}{N}\sum_{i=1}^N Y_i\right)^2}$

where the permutation is defined such that $Y_{(k,N+1)} = Y_{(k,1)}$ .

Confidence intervals are obtained via bootstrap without replacement.

The ratio of the bootstrap’s sample size with respect to the total size of the input sample is fixed in the RankSobolSensitivityAlgorithm-DefaultBootstrapSampleRatio ResourceMap key.

Examples

>>> import openturns as ot
>>> import openturns.experimental as otexp
>>> from openturns.usecases import ishigami_function
>>> im = ishigami_function.IshigamiModel()
>>> x = im.distributionX.getSample(100)
>>> y = im.model(x)
>>> algo = otexp.RankSobolSensitivityAlgorithm(x, y)
>>> indices = algo.getFirstOrderIndices()

Methods

`DrawCorrelationCoefficients`(*args)	Draw the correlation coefficients.
`DrawImportanceFactors`(*args)	Draw the importance factors.
`DrawSobolIndices`(*args)	Draw the Sobol' indices.
`draw`()	Draw sensitivity indices.
`getAggregatedFirstOrderIndices`()	Get the evaluation of aggregated first order Sobol indices.
`getAggregatedTotalOrderIndices`()	Method not yet implemented.
`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])	Method not yet implemented.
`getTotalOrderIndices`([marginalIndex])	Method not yet implemented.
`getTotalOrderIndicesDistribution`()	Method not yet implemented.
`getTotalOrderIndicesInterval`()	Method not yet implemented.
`getUseAsymptoticDistribution`()	Method not yet implemented.
`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`(arg2)	Method not yet implemented.

__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()¶

Draw sensitivity indices.

Usage:: draw()

Draw the aggregated first order Sobol’ indices.

Returns:

graphGraph: A graph containing the aggregated first and total order indices.

Notes

If number of bootstrap sampling is greater than 1, the graph includes confidence interval plots in the first usage. This is defined in the SobolIndicesAlgorithm-DefaultBootstrapSize ResourceMap key.

getAggregatedFirstOrderIndices()¶

Get the evaluation of aggregated first order Sobol indices.

Returns:

indicesPoint: Sequence containing aggregated first order Sobol indices.

getAggregatedTotalOrderIndices()¶: Method not yet implemented.

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)¶: Method not yet implemented.

getTotalOrderIndices(marginalIndex=0)¶: Method not yet implemented.

getTotalOrderIndicesDistribution()¶: Method not yet implemented.

getTotalOrderIndicesInterval()¶: Method not yet implemented.

getUseAsymptoticDistribution()¶: Method not yet implemented.

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