RandomVariable

class probnum.random_variables.RandomVariable(shape: Union[numbers.Integral, Iterable[numbers.Integral]], dtype: Union[numpy.dtype, str], random_state: Union[None, int, numpy.random.mtrand.RandomState, numpy.random._generator.Generator] = None, parameters: Optional[Dict[str, Any]] = None, sample: Optional[Callable[Tuple[int, ...], ValueType]] = None, in_support: Optional[Callable[ValueType, bool]] = None, cdf: Optional[Callable[ValueType, numpy.float64]] = None, logcdf: Optional[Callable[ValueType, numpy.float64]] = None, quantile: Optional[Callable[numbers.Real, ValueType]] = None, mode: Optional[Callable[ValueType]] = None, median: Optional[Callable[ValueType]] = None, mean: Optional[Callable[ValueType]] = None, cov: Optional[Callable[ValueType]] = None, var: Optional[Callable[ValueType]] = None, std: Optional[Callable[ValueType]] = None, entropy: Optional[Callable[numpy.float64]] = None, as_value_type: Optional[Callable[Any, ValueType]] = None)

Bases: typing.Generic

Random variables are the main objects used by probabilistic numerical methods.

Every probabilistic numerical method takes a random variable encoding the prior distribution as input and outputs a random variable whose distribution encodes the uncertainty arising from finite computation. The generic signature of a probabilistic numerical method is:

output_rv = probnum_method(input_rv, method_params)

In practice, most random variables used by methods in ProbNum have Dirac or Gaussian measure.

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

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.

Parameters:

• shape – Shape of realizations of this random variable.
• dtype – Data type of realizations of this random variable. If object will be converted to numpy.dtype.
• as_value_type –

  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 np.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.

Examples

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
mean	Mean \(\mathbb{E}(X)\) of the distribution.
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
parameters	Parameters of the probability distribution.
random_state	Random state of the random variable.
shape	Shape of realizations of the random variable.
size
std	Standard deviation of the distribution.
var	Variance \(\operatorname{Var}(X) = \mathbb{E}((X-\mathbb{E}(X))^2)\) of the distribution.

Methods Summary

cdf(x)	Cumulative distribution function.
in_support(x)
infer_median_dtype(value_dtype, str])
infer_moment_dtype(value_dtype, str])
logcdf(x)	Log-cumulative distribution function.
quantile(p)	Quantile function.
reshape(newshape, Iterable[numbers.Integral]])	Give a new shape to a random variable.
sample(size, Iterable[numbers.Integral]] = ())	Draw realizations from a random variable.
transpose(*axes)	Transpose the random variable.

Attributes Documentation

T

Transpose the random variable.

Parameters:axes (None, tuple of ints, or n ints) – See documentation of numpy.ndarray.transpose. Returns:transposed_rv Return type:The transposed random variable.

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.

Returns:cov – The kernels of the random variable. Return type:array-like

dtype

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

entropy

mean

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

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

Returns:mean – The mean of the distribution. Return type:array-like

median

Median of the random variable.

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

Returns:median – The median of the distribution. Return type:float

median_dtype

The dtype of the median. It will be set to the dtype arising from the multiplication of values with dtypes dtype and np.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\).

mode

Mode of the random variable.

Returns:mode – The mode of the random variable. Return type:float

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 np.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 np.float_ and dtype, respectively.

ndim

parameters

Parameters of the probability distribution.

The parameters of the distribution such as mean, variance, et cetera stored in a dict.

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.

shape

Shape of realizations of the random variable.

size

std

Standard deviation of the distribution.

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

Returns:std – The standard deviation of the distribution. Return type:array-like

var

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

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

Returns:var – The variance of the distribution. Return type:array-like

Methods Documentation

cdf(x: ValueType) → numpy.float64

Cumulative distribution function.

Parameters:x (array-like) – 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. Returns:q – Value of the cumulative density function at the given points. Return type:array-like

in_support(x: ValueType) → bool

static infer_median_dtype(value_dtype: Union[numpy.dtype, str]) → numpy.dtype

static infer_moment_dtype(value_dtype: Union[numpy.dtype, str]) → numpy.dtype

logcdf(x: ValueType) → numpy.float64

Log-cumulative distribution function.

Parameters:x (array-like) – 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. Returns:q – Value of the log-cumulative density function at the given points. Return type:array-like

quantile(p: numbers.Real) → ValueType

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.

reshape(newshape: Union[numbers.Integral, Iterable[numbers.Integral]]) → probnum.random_variables.RandomVariable

Give a new shape to a random variable.

Parameters:newshape (int or tuple of ints) – New shape for the random variable. It must be compatible with the original shape. Returns:reshaped_rv Return type:self with the new dimensions of shape.

sample(size: Union[numbers.Integral, Iterable[numbers.Integral]] = ()) → ValueType

Draw realizations from a random variable.

Parameters:size (tuple) – Size of the drawn sample of realizations. Returns:sample – Sample of realizations with the given size and the inherent shape. Return type:array-like

transpose(*axes) → probnum.random_variables.RandomVariable

Transpose the random variable.

Parameters:axes (None, tuple of ints, or n ints) – See documentation of numpy.ndarray.transpose. Returns:transposed_rv Return type:The transposed random variable.