gemseo.uncertainty package#

Uncertainty quantification and management.

The package uncertainty provides several functionalities to quantify and manage uncertainties. Most of them can be used from the high-level functions provided by this module.

The sub-package distributions offers an abstract level for probability distributions, as well as interfaces to the OpenTURNS and SciPy ones. It is also possible to fit a probability distribution from data or select the most likely one from a list of candidates. These distributions can be used to define random variables in a ParameterSpace before propagating these uncertainties through a system of Discipline, by means of a DOEScenario.

See also

OTDistribution SPDistribution OTDistributionFitter

The sub-package sensitivity offers an abstract level for sensitivity analysis, as well as concrete features. These sensitivity analyses compute indices by means of various methods: correlation measures, Morris technique and Sobol' variance decomposition. This sub-package is based in particular on OpenTURNS.

See also

CorrelationAnalysis MorrisAnalysis SobolAnalysis HSICAnalysis

The sub-package statistics offers an abstract level for statistics, as well as parametric and empirical versions. Empirical statistics are estimated from a Dataset while parametric statistics are analytical properties of a BaseDistribution fitted from a Dataset.

See also

EmpiricalStatistics ParametricStatistics

create_distribution(distribution_name, **options)[source]#

Create a distribution.

Parameters:

  • distribution_name (str) -- The name of a class implementing a probability distribution, e.g. 'OTUniformDistribution' or 'SPDistribution'.

  • **options -- The distribution options.

Return type:

BaseDistribution

Examples

>>> from gemseo.uncertainty import create_distribution
>>>
>>> distribution = create_distribution("OTNormalDistribution", mu=1, sigma=2)
>>> print(distribution)
Normal(mu=1, sigma=2)
>>> print(distribution.mean, distribution.standard_deviation)
1.0 2.0
>>> samples = distribution.compute_samples(10)
>>> print(samples.shape)
(10,)
create_sensitivity_analysis(analysis, samples='')[source]#

Create the sensitivity analysis.

Parameters:

  • analysis (str) -- The name of a sensitivity analysis class.

  • samples (IODataset | str | Path) --

    The samples for the estimation of the sensitivity indices, either as an IODataset or as a pickle file path generated from the IODataset.to_pickle method. If empty, use compute_samples().

    By default it is set to "".

Returns:

The sensitivity analysis.

Return type:

BaseSensitivityAnalysis

create_statistics(dataset, variable_names=(), tested_distributions=(), fitting_criterion='BIC', selection_criterion='best', level=0.05, name='')[source]#

Create a statistics toolbox, either parametric or empirical.

If parametric, the toolbox selects a distribution from candidates, based on a fitting criterion and on a selection strategy.

Parameters:

  • dataset (Dataset) -- A dataset.

  • variable_names (Iterable[str]) --

    The variables of interest. If empty, consider all the variables from dataset.

    By default it is set to ().

  • tested_distributions (Sequence[str]) --

    The names of the tested distributions.

    By default it is set to ().

  • fitting_criterion (str) --

    The name of a goodness-of-fit criterion, measuring how the distribution fits the data. Use ParametricStatistics.get_criteria() to get the available criteria.

    By default it is set to "BIC".

  • selection_criterion (str) --

    The name of a selection criterion to select a distribution from candidates. Either 'first' or 'best'.

    By default it is set to "best".

  • level (float) --

    A test level, i.e. the risk of committing a Type 1 error, that is an incorrect rejection of a true null hypothesis, for criteria based on a test hypothesis.

    By default it is set to 0.05.

  • name (str) --

    A name for the statistics toolbox instance. If empty, use the concatenation of class and dataset names.

    By default it is set to "".

Returns:

A statistics toolbox.

Return type:

BaseStatistics

Examples

>>> from gemseo import (
...     create_discipline,
...     create_parameter_space,
...     create_scenario,
... )
>>> from gemseo.uncertainty import create_statistics
>>>
>>> expressions = {"y1": "x1+2*x2", "y2": "x1-3*x2"}
>>> discipline = create_discipline(
...     "AnalyticDiscipline", expressions=expressions
... )
>>>
>>> parameter_space = create_parameter_space()
>>> parameter_space.add_random_variable(
...     "x1", "OTUniformDistribution", minimum=-1, maximum=1
... )
>>> parameter_space.add_random_variable(
...     "x2", "OTNormalDistribution", mu=0.5, sigma=2
... )
>>>
>>> scenario = create_scenario(
...     [discipline],
...     "y1",
...     parameter_space,
...     formulation_name="DisciplinaryOpt",
...     scenario_type="DOE",
... )
>>> scenario.execute(algo_name="OT_MONTE_CARLO", n_samples=100)
>>>
>>> dataset = scenario.to_dataset(opt_naming=False)
>>>
>>> statistics = create_statistics(dataset)
>>> mean = statistics.compute_mean()
get_available_distributions(base_class_name='BaseDistribution')[source]#

Get the available probability distributions.

Parameters:

base_class_name (str) --

The name of the base class of the probability distributions, e.g. "BaseDistribution", "OTDistribution" or "SPDistribution".

By default it is set to "BaseDistribution".

Returns:

The names of the available probability distributions.

Return type:

list[str]

get_available_sensitivity_analyses()[source]#

Get the available sensitivity analyses.

Return type:

list[str]

load_sensitivity_analysis(file_path)[source]#

Load a sensitivity analysis from the disk.

Parameters:

file_path (str | Path) -- The path to the file.

Returns:

The sensitivity analysis.

Return type:

BaseSensitivityAnalysis

Subpackages#