One-Dimensional Marginal Distribution

One-Dimensional Marginal Distribution#

Module with an implementation of Marginal class.

This module provides the Marginal class, which models a single random variable through a parametric probability distribution. It is intended as the building block for probabilistic input models, where each input dimension is described by one marginal distribution.

The class offers a consistent interface for:

  • Validating the chosen distribution and its parameters

  • Evaluating the probability density function (PDF)

  • Evaluating the cumulative distribution function (CDF)

  • Computing the inverse CDF (ICDF)

  • Generating random samples

  • Transforming samples between marginal distributions

For numerical purposes, each distribution is associated with finite lower and upper bounds. These bounds are used when evaluating PDFs, CDFs, and inverse CDFs through the helper functions imported from utils.

class uqtestfuns.core.prob_input.marginal.Marginal(distribution: str, parameters: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], name: str | None = None, description: str | None = None)#

A random variable represented by a univariate probability distribution.

The class represents a single random variable defined by its distribution type and parameters. Within a probabilistic input model, each univariate distribution serves as a marginal of the joint distribution.

Parameters:

  • distribution (str) – The type of probability distribution.

  • parameters (array_like) – The parameters of the chosen probability distribution.

  • name (str, optional) – The name of the random variable.

  • description (str, optional) – A short text description of the random variable.

cdf(xx: float | ndarray) → ndarray#

Compute the cumulative distribution function on input values.

Parameters:

xx (Union[float, np.ndarray]) – The input values in the support of the distribution.

Returns:

The cumulative distribution function (CDF) values at the input values. The output is an array of at least one dimension.

Return type:

np.ndarray

property description: str | None#

A short text description of the random variable.

Returns:

A short text description of the random variable.

Return type:

str, optional

property distribution: str#

The type of the probability distribution.

Returns:

The type of the one-dimensional marginal distribution.

Return type:

str

get_sample(sample_size: int = 1, rng: Generator | int | None = None) → ndarray#

Get a random sample from the distribution.

Parameters:

  • sample_size (int, optional) – The number of sample points. Default is 1.

  • rng (Union[np.random.Generator, int], optional) – The random number generator or the seed for the default NumPy random number generator. If not specified, the default random number generator with the operating system entropy is used.

Returns:

A one-dimensional array of length sample_size containing the sample points.

Return type:

np.ndarray

icdf(xx: float | ndarray) → ndarray#

Compute the inverse CDF on input values.

Parameters:

xx (Union[float, np.ndarray]) – The input values in the [0,1] domain.

Returns:

The inverse cumulative distribution function (ICDF) values at the input points. These are points in the distribution’s support. The output is an array of at least one dimension.

Return type:

np.ndarray

Notes

  • If the input values are outside the [0, 1] domain, NaN values are returned.

property lower: float#

The lower bound of the distribution.

Returns:

The lower bound of the distribution.

Return type:

float

Notes

  • While the support of many continuous probability density functions is unbounded, numerically they are always bounded. Below the lower bound, the density values are always zero.

property name: str | None#

The name of the random variable.

Returns:

The name of the random variable.

Return type:

str, optional

property parameters: ndarray#

The parameters of the chosen probability distribution.

Returns:

The parameters of the chosen probability distribution.

Return type:

np.ndarray

pdf(xx: float | ndarray) → ndarray#

Compute the probability density function of the distribution.

Parameters:

xx (Union[float, np.ndarray]) – The input values in the support of the distribution.

Returns:

The probability density function (PDF) values at the input values. The output is an array of at least one dimension.

Return type:

np.ndarray

transform_to(xx: float | ndarray, target: Marginal) → ndarray#

Transform a sample from this distribution to another.

Parameters:

  • xx (Union[float, np.ndarray]) – The sample points to be transformed.

  • target (Marginal) – The target distribution to which the sample should be transformed.

Returns:

The transformed sample points in the target distribution. The output is an array of at least one dimension.

Return type:

np.ndarray

property upper: float#

The upper bound of the distribution.

Returns:

The upper bound of the distribution.

Return type:

float

Notes

  • While the support of many continuous probability density functions is unbounded, numerically they are always bounded. Above the upper bound, the density values are always zero.