gemseo / uncertainty / distributions

composed module

Abstract classes defining the concept of joint probability distribution.

Overview

The abstract ComposedDistribution class implements the concept of joint probability distribution, which is a mathematical function giving the probabilities of occurrence of different possible outcomes of several random variables for an experiment. In the style of OpenTURNS, a ComposedDistribution is defined from a list of Distribution instances defining the marginals of the random variables and a copula defining the dependence structure between them.

Note

A copula is a mathematical function used to define the dependence between random variables from their cumulative density functions. See more.

By definition, a joint probability distribution is a probability distribution Therefore, ComposedDistribution inherits from the abstract class Distribution.

Construction

The ComposedDistribution of a list of given uncertain variables is built from a list of Distribution objects implementing the probability distributions of these variables and from a copula name.

Capabilities

Because ComposedDistribution inherits from Distribution, we can easily get statistics, such as ComposedDistribution.mean, ComposedDistribution.standard_deviation. We can also get the numerical ComposedDistribution.range and mathematical ComposedDistribution.support.

Note

We call mathematical support the set of values that the random variable can take in theory, e.g. \(]-\infty,+\infty[\) for a Gaussian variable, and numerical range the set of values that it can can take in practice, taking into account the values rounded to zero double precision. Both support and range are described in terms of lower and upper bounds

We can also evaluate the cumulative density function (ComposedDistribution.compute_cdf()) for the different marginals of the random variable, as well as the inverse cumulative density function (ComposedDistribution.compute_inverse_cdf()). We can plot them, either for a given marginal (ComposedDistribution.plot()) or for all marginals (ComposedDistribution.plot_all()).

Lastly, we can compute realizations of the random variable by means of the ComposedDistribution.compute_samples() method.

Classes:

ComposedDistribution(distributions[, copula])

Composed distribution.

class gemseo.uncertainty.distributions.composed.ComposedDistribution(distributions, copula='independent_copula')

Bases: gemseo.uncertainty.distributions.distribution.Distribution

Composed distribution.

Parameters

• distributions (Sequence[Distribution]) – The distributions.

• copula (str) –

  A name of copula.

  By default it is set to independent_copula.

Return type

None

Attributes:

AVAILABLE_COPULA_MODELS
mean	The analytical mean of the random variable.
range	The numerical range.
standard_deviation	The analytical standard deviation of the random variable.
support	The mathematical support.

Methods:

compute_cdf(vector)	Evaluate the cumulative density function (CDF).
compute_inverse_cdf(vector)	Evaluate the inverse of the cumulative density function (ICDF).
compute_samples([n_samples])	Sample the random variable.
plot([index, show, save, file_path, ...])	Plot both probability and cumulative density functions for a given component.
plot_all([show, save, file_path, ...])	Plot both probability and cumulative density functions for all components.

AVAILABLE_COPULA_MODELS = ['independent_copula']

compute_cdf(vector)

Evaluate the cumulative density function (CDF).

Evaluate the CDF of the components of the random variable for a given realization of this random variable.

Parameters

vector (Iterable[float]) – A realization of the random variable.

Returns

The CDF values of the components of the random variable.

Return type

numpy.ndarray

compute_inverse_cdf(vector)

Evaluate the inverse of the cumulative density function (ICDF).

Parameters

vector (Iterable[float]) – A vector of values comprised between 0 and 1 whose length is equal to the dimension of the random variable.

Returns

The ICDF values of the components of the random variable.

Return type

numpy.ndarray

compute_samples(n_samples=1)

Sample the random variable.

Parameters

n_samples (int) –

The number of samples.

By default it is set to 1.

Returns

The samples of the random variable,

The number of columns is equal to the dimension of the variable and the number of lines is equal to the number of samples.

Return type

numpy.ndarray

property mean

The analytical mean of the random variable.

plot(index=0, show=True, save=False, file_path=None, directory_path=None, file_name=None, file_extension=None)

Plot both probability and cumulative density functions for a given component.

Parameters

• index (int) –

  The index of a component of the random variable.

  By default it is set to 0.

• save (bool) –

  If True, save the figure.

  By default it is set to False.

• show (bool) –

  If True, display the figure.

  By default it is set to True.

• file_path (Optional[Union[str, pathlib.Path]]) –

  The path of the file to save the figures. If the extension is missing, use file_extension. If None, create a file path from directory_path, file_name and file_extension.

  By default it is set to None.

• directory_path (Optional[Union[str, pathlib.Path]]) –

  The path of the directory to save the figures. If None, use the current working directory.

  By default it is set to None.

• file_name (Optional[str]) –

  The name of the file to save the figures. If None, use a default one generated by the post-processing.

  By default it is set to None.

• file_extension (Optional[str]) –

  A file extension, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.

  By default it is set to None.

Returns

The figure.

Return type

matplotlib.figure.Figure

plot_all(show=True, save=False, file_path=None, directory_path=None, file_name=None, file_extension=None)

Plot both probability and cumulative density functions for all components.

Parameters

• save (bool) –

  If True, save the figure.

  By default it is set to False.

• show (bool) –

  If True, display the figure.

  By default it is set to True.

• file_path (Optional[Union[str, pathlib.Path]]) –

  The path of the file to save the figures. If the extension is missing, use file_extension. If None, create a file path from directory_path, file_name and file_extension.

  By default it is set to None.

• directory_path (Optional[Union[str, pathlib.Path]]) –

  The path of the directory to save the figures. If None, use the current working directory.

  By default it is set to None.

• file_name (Optional[str]) –

  The name of the file to save the figures. If None, use a default one generated by the post-processing.

  By default it is set to None.

• file_extension (Optional[str]) –

  A file extension, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.

  By default it is set to None.

Returns

The figures.

Return type

List[matplotlib.figure.Figure]

property range

The numerical range.

The numerical range is the interval defined by the lower and upper bounds numerically reachable by the random variable.

Here, the numerical range of the random variable is defined by one array for each component of the random variable, whose first element is the lower bound of this component while the second one is its upper bound.

property standard_deviation

The analytical standard deviation of the random variable.

property support

The mathematical support.

The mathematical support is the interval defined by the theoretical lower and upper bounds of the random variable.

Here, the mathematical range of the random variable is defined by one array for each component of the random variable, whose first element is the lower bound of this component while the second one is its upper bound.