RandomVariable¶

class probnum.randvars.RandomVariable(shape, dtype, random_state=None, parameters=None, sample=None, in_support=None, cdf=None, logcdf=None, quantile=None, mode=None, median=None, mean=None, cov=None, var=None, std=None, entropy=None, as_value_type=None)¶

Bases: Generic[typing.ValueType]

Random variables represent uncertainty about a value.

Random variables generalize multi-dimensional arrays by encoding uncertainty about the (numerical) quantity in question. Despite their name, they do not necessarily represent stochastic objects. Random variables are also the primary in- and outputs of probabilistic numerical methods.

Instances of RandomVariable can be added, multiplied, etc. with arrays and linear operators. This may change their distribution and therefore not necessarily all previously available methods are retained.

Parameters

shape (Union[Integral, Iterable[Integral]]) – Shape of realizations of this random variable.
dtype (Union[dtype, str]) – Data type of realizations of this random variable. If of type object the argument will be converted to numpy.dtype.
random_state (Union[None, int, RandomState, Generator]) – Random state of the random variable. If None (or np.random), the global numpy.random state is used. If integer, it is used to seed the local RandomState instance.
parameters (Optional[Dict[str, Any]]) – Parameters of the distribution of the random variable.
sample (Optional[Callable[[Tuple[int, …]], ~ValueType]]) – Callable implementing sampling from the random variable.
in_support (Optional[Callable[[~ValueType], bool]]) – Callable checking whether the random variable takes value x with non-zero probability, i.e. if x is in the support of its distribution.
cdf (Optional[Callable[[~ValueType], float64]]) – Cumulative distribution function of the random variable.
logcdf (Optional[Callable[[~ValueType], float64]]) – Log-transformed cumulative distribution function of the random variable.
quantile (Optional[Callable[[Real], ~ValueType]]) – Quantile function of the random variable.
mode (Optional[Callable[[], ~ValueType]]) – Mode of the random variable. Value of the random variable at which its probability density function or probability mass function takes its maximal value.
mean (Optional[Callable[[], ~ValueType]]) – Expected value of the random variable.
cov (Optional[Callable[[], ~ValueType]]) – Covariance of the random variable.
var (Optional[Callable[[], ~ValueType]]) – (Element-wise) variance of the random variable.
std (Optional[Callable[[], ~ValueType]]) – (Element-wise) standard deviation of the random variable.
entropy (Optional[Callable[[], float64]]) – Information-theoretic entropy \(H(X)\) of the random variable.
as_value_type (Optional[Callable[[Any], ~ValueType]]) –
Function which can be used to transform user-supplied arguments, interpreted as realizations of this random variable, to an easy-to-process, normalized format. Will be called internally to transform the argument of functions like in_support(), cdf() and logcdf(), pmf() and logpmf() (in DiscreteRandomVariable), pdf() and logpdf() (in ContinuousRandomVariable), and potentially by similar functions in subclasses.

For instance, this method is useful if (log) cdf() and (log) pdf() both only work on numpy.float_ arguments, but we still want the user to be able to pass Python float. Then as_value_type() should be set to something like lambda x: np.float64(x).

See also

asrandvar: Transform into a RandomVariable.
DiscreteRandomVariable: A random variable with countable range.
ContinuousRandomVariable: A random variable with uncountably infinite range.

Notes

The internals of RandomVariable objects are assumed to be constant over their whole lifecycle. This is due to the caches used to make certain computations more efficient. As a consequence, altering the internal state of a RandomVariable (e.g. its mean, cov, sampling function, etc.) will result in undefined behavior. In particular, this should be kept in mind when subclassing RandomVariable or any of its descendants.

Sampling from random variables with fixed seed is not stable with respect to the order of operations (such as slicing, masking, etc.). This means sampling from a random variable and then slicing the resulting array does not necessarily return the same result as slicing the random variable and sampling from the result. However, the random seed ensures that each sequence of operations will always result in the same output.

Attributes Summary

`T`	Transpose the random variable.
`cov`	Covariance \(\operatorname{Cov}(X) = \mathbb{E}((X-\mathbb{E}(X))(X-\mathbb{E}(X))^\top)\) of the random variable.
`dtype`	Data type of (elements of) a realization of this random variable.
`entropy`	Information-theoretic entropy \(H(X)\) of the random variable.
`mean`	Mean \(\mathbb{E}(X)\) of the random variable.
`median`	Median of the random variable.
`median_dtype`	The dtype of the `median`.
`mode`	Mode of the random variable.
`moment_dtype`	The dtype of any (function of a) moment of the random variable, e.g.
`ndim`	Number of dimensions of realizations of the random variable.
`parameters`	Parameters of the associated probability distribution.
`random_state`	Random state of the random variable.
`shape`	Shape of realizations of the random variable.
`size`	Size of realizations of the random variable, defined as the product over all components of `shape()`.
`std`	Standard deviation of the random variable.
`var`	Variance \(\operatorname{Var}(X) = \mathbb{E}((X-\mathbb{E}(X))^2)\) of the random variable.

Methods Summary

`cdf`(x)	Cumulative distribution function.
`in_support`(x)	Check whether the random variable takes value `x` with non-zero probability, i.e. if `x` is in the support of its distribution.
`infer_median_dtype`(value_dtype)	Infer the dtype of the median.
`infer_moment_dtype`(value_dtype)	Infer the dtype of any moment.
`logcdf`(x)	Log-cumulative distribution function.
`quantile`(p)	Quantile function.
`reshape`(newshape)	Give a new shape to a random variable.
`sample`([size])	Draw realizations from a random variable.
`transpose`(*axes)	Transpose the random variable.

Attributes Documentation

T¶

Transpose the random variable.

Parameters: axes (int) – See documentation of numpy.ndarray.transpose().
Return type: RandomVariable

cov¶

Covariance \(\operatorname{Cov}(X) = \mathbb{E}((X-\mathbb{E}(X))(X-\mathbb{E}(X))^\top)\) of the random variable.

To learn about the dtype of the covariance, see moment_dtype.

dtype¶

Data type of (elements of) a realization of this random variable.

Return type: dtype

entropy¶: Information-theoretic entropy \(H(X)\) of the random variable.

mean¶

Mean \(\mathbb{E}(X)\) of the random variable.

To learn about the dtype of the mean, see moment_dtype.

median¶

Median of the random variable.

To learn about the dtype of the median, see median_dtype.

median_dtype¶

The dtype of the median.

It will be set to the dtype arising from the multiplication of values with dtypes dtype and numpy.float_. This is motivated by the fact that, even for discrete random variables, e.g. integer-valued random variables, the median might lie in between two values in which case these values are averaged. For example, a uniform random variable on \(\{ 1, 2, 3, 4 \}\) will have a median of \(2.5\).

Return type: dtype

mode¶: Mode of the random variable.

moment_dtype¶

The dtype of any (function of a) moment of the random variable, e.g. its mean, cov, var, or std. It will be set to the dtype arising from the multiplication of values with dtypes dtype and numpy.float_. This is motivated by the mathematical definition of a moment as a sum or an integral over products of probabilities and values of the random variable, which are represented as using the dtypes numpy.float_ and dtype, respectively.

Return type: dtype

ndim¶: Number of dimensions of realizations of the random variable.

parameters¶

Parameters of the associated probability distribution.

The parameters of the probability distribution of the random variable, e.g. mean, variance, scale, rate, etc. stored in a dict.

Return type: Dict[str, Any]

random_state¶

Random state of the random variable.

This attribute defines the RandomState object to use for drawing realizations from this random variable. If None (or np.random), the global np.random state is used. If integer, it is used to seed the local RandomState instance.

Return type: Union[RandomState, Generator]

shape¶

Shape of realizations of the random variable.

Return type: Tuple[int, …]

size¶: Size of realizations of the random variable, defined as the product over all components of shape().

std¶

Standard deviation of the random variable.

To learn about the dtype of the standard deviation, see moment_dtype.

var¶

Variance \(\operatorname{Var}(X) = \mathbb{E}((X-\mathbb{E}(X))^2)\) of the random variable.

To learn about the dtype of the variance, see moment_dtype.

Methods Documentation

cdf(x)[source]¶

Cumulative distribution function.

Parameters: x (~ValueType) – Evaluation points of the cumulative distribution function. The shape of this argument should be (..., S1, ..., SN), where (S1, ..., SN) is the shape of the random variable. The cdf evaluation will be broadcast over all additional dimensions.
Return type: float64

in_support(x)[source]¶

Check whether the random variable takes value x with non-zero probability, i.e. if x is in the support of its distribution.

Parameters: x (~ValueType) – Input value.
Return type: bool

static infer_median_dtype(value_dtype)[source]¶

Infer the dtype of the median.

Set the dtype to the dtype arising from the multiplication of values with dtypes dtype and numpy.float_. This is motivated by the fact that, even for discrete random variables, e.g. integer-valued random variables, the median might lie in between two values in which case these values are averaged. For example, a uniform random variable on \(\{ 1, 2, 3, 4 \}\) will have a median of \(2.5\).

Parameters: value_dtype (Union[dtype, str]) – Dtype of a value.
Return type: dtype

static infer_moment_dtype(value_dtype)[source]¶

Infer the dtype of any moment.

Infers the dtype of any (function of a) moment of the random variable, e.g. its mean, cov, var, or std. Returns the dtype arising from the multiplication of values with dtypes dtype and numpy.float_. This is motivated by the mathematical definition of a moment as a sum or an integral over products of probabilities and values of the random variable, which are represented as using the dtypes numpy.float_ and dtype, respectively.

Parameters: value_dtype (Union[dtype, str]) – Dtype of a value.
Return type: dtype

logcdf(x)[source]¶

Log-cumulative distribution function.

Parameters: x (~ValueType) – Evaluation points of the cumulative distribution function. The shape of this argument should be (..., S1, ..., SN), where (S1, ..., SN) is the shape of the random variable. The logcdf evaluation will be broadcast over all additional dimensions.
Return type: float64

quantile(p)[source]¶

Quantile function.

The quantile function \(Q \colon [0, 1] \to \mathbb{R}\) of a random variable \(X\) is defined as \(Q(p) = \inf\{ x \in \mathbb{R} \colon p \le F_X(x) \}\), where \(F_X \colon \mathbb{R} \to [0, 1]\) is the cdf() of the random variable. From the definition it follows that the quantile function always returns values of the same dtype as the random variable. For instance, for a discrete distribution over the integers, the returned quantiles will also be integers. This means that, in general, \(Q(0.5)\) is not equal to the median as it is defined in this class. See https://en.wikipedia.org/wiki/Quantile_function for more details and examples.

Return type: ~ValueType

reshape(newshape)[source]¶

Give a new shape to a random variable.

Parameters: newshape (Union[Integral, Iterable[Integral]]) – New shape for the random variable. It must be compatible with the original shape.
Return type: RandomVariable

sample(size=())[source]¶

Draw realizations from a random variable.

Parameters: size (Union[Integral, Iterable[Integral]]) – Size of the drawn sample of realizations.
Return type: ~ValueType

transpose(*axes)[source]¶

Transpose the random variable.

Parameters: axes (int) – See documentation of numpy.ndarray.transpose().
Return type: RandomVariable