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 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.
- class gemseo.uncertainty.distributions.composed.ComposedDistribution(distributions, copula=CopulaModel.independent_copula, variable='')[source]¶
Bases:
Distribution
Composed distribution.
- Parameters:
distributions (Sequence[Distribution]) – The distributions.
copula (CopulaModel | str) –
A copula model.
By default it is set to independent_copula.
variable (str) –
The name of the variable, if any; otherwise, concatenate the names of the random variables defined by
distributions
.By default it is set to “”.
- class CopulaModel(value)[source]¶
Bases:
BaseEnum
A copula model.
- independent_copula = 'independent_copula'¶
- abstract 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.
- abstract compute_inverse_cdf(vector)¶
Evaluate the inverse of the cumulative density function (ICDF).
- 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 (str | Path | None) – The path of the file to save the figures. If the extension is missing, use
file_extension
. IfNone
, create a file path fromdirectory_path
,file_name
andfile_extension
.directory_path (str | Path | None) – The path of the directory to save the figures. If
None
, use the current working directory.file_name (str | None) – The name of the file to save the figures. If
None
, use a default one generated by the post-processing.file_extension (str | None) – A file extension, e.g.
'png'
,'pdf'
,'svg'
, … IfNone
, use a default file extension.
- Returns:
The figure.
- Return type:
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 (str | Path | None) – The path of the file to save the figures. If the extension is missing, use
file_extension
. IfNone
, create a file path fromdirectory_path
,file_name
andfile_extension
.directory_path (str | Path | None) – The path of the directory to save the figures. If
None
, use the current working directory.file_name (str | None) – The name of the file to save the figures. If
None
, use a default one generated by the post-processing.file_extension (str | None) – A file extension, e.g.
'png'
,'pdf'
,'svg'
, … IfNone
, use a default file extension.
- Returns:
The figures.
- Return type:
list[Figure]
- AVAILABLE_COPULA_MODELS: ClassVar[list[str]] = ['independent_copula']¶
The names of the models defining copulas.
- math_lower_bound: ndarray¶
The mathematical lower bound of the random variable.
- math_upper_bound: ndarray¶
The mathematical upper bound of the random variable.
- num_lower_bound: ndarray¶
The numerical lower bound of the random variable.
- num_upper_bound: ndarray¶
The numerical upper bound of the random variable.
- property range: list[numpy.ndarray]¶
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.
- standard_parameters: dict[str, str] | None¶
The standard representation of the parameters of the distribution, used for its string representation.
- property support: list[numpy.ndarray]¶
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.