DiscreteRandomVariable¶

class
probnum.randvars.
DiscreteRandomVariable
(shape, dtype, random_state=None, parameters=None, sample=None, in_support=None, pmf=None, logpmf=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:
probnum.randvars.RandomVariable
Random variable with countable range.
Discrete random variables map to a countable set. Typical examples are the natural numbers or integers.
 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. Ifobject
will be converted tonumpy.dtype
.random_state (
Union
[RandomState
,Generator
,None
]) – Random state of the random variable. If None (or np.random), the globalnumpy.random
state is used. If integer, it is used to seed the localRandomState
instance.parameters (
Optional
[Dict
[str
,Any
]]) – Parameters of the distribution of the random variable.sample (
Optional
[Callable
[[Union
[Integral
,Iterable
[Integral
]]], ~ValueType]]) – Callable implementing sampling from the random variable.in_support (
Optional
[Callable
[[~ValueType],bool
]]) – Callable checking whether the random variable takes valuex
with nonzero probability, i.e. ifx
is in the support of its distribution.pmf (
Optional
[Callable
[[~ValueType],float64
]]) – Probability mass function of the random variable.logpmf (
Optional
[Callable
[[~ValueType],float64
]]) – Logtransformed probability mass function of the random variable.cdf (
Optional
[Callable
[[~ValueType],float64
]]) – Cumulative distribution function of the random variable.logcdf (
Optional
[Callable
[[~ValueType],float64
]]) – Logtransformed 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 whichpmf()
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]]) – (Elementwise) variance of the random variable.std (
Optional
[Callable
[[], ~ValueType]]) – (Elementwise) standard deviation of the random variable.entropy (
Optional
[Callable
[[],float64
]]) – Shannon entropy \(H(X)\) of the random variable.as_value_type (
Optional
[Callable
[[Any
], ~ValueType]]) –Function which can be used to transform usersupplied arguments, interpreted as realizations of this random variable, to an easytoprocess, normalized format. Will be called internally to transform the argument of functions like
in_support()
,cdf()
andlogcdf()
,pmf()
andlogpmf()
, and potentially by similar functions in subclasses.For instance, this method is useful if (
log
)cdf()
and (log
)pmf()
both only work onnumpy.float_
arguments, but we still want the user to be able to pass Pythonfloat
. Thenas_value_type()
should be set to something likelambda x: np.float64(x)
.
See also
RandomVariable
Class representing random variables.
ContinuousRandomVariable
A random variable with uncountably infinite range.
Examples
>>> # Create a custom categorical random variable >>> import numpy as np >>> from probnum.randvars import DiscreteRandomVariable >>> >>> # Distribution parameters >>> support = np.array([1, 0, 1]) >>> p = np.array([0.2, 0.5, 0.3]) >>> parameters_categorical = { ... "support" : support, ... "p" : p} >>> >>> # Sampling function >>> def sample_categorical(size=()): ... return np.random.choice(a=support, size=size, p=p) >>> >>> # Probability mass function >>> def pmf_categorical(x): ... idx = np.where(x == support)[0] ... if len(idx) > 0: ... return p[idx] ... else: ... return 0.0 >>> >>> # Create custom random variable >>> x = DiscreteRandomVariable( ... shape=(), ... dtype=np.dtype(np.int64), ... parameters=parameters_categorical, ... sample=sample_categorical, ... pmf=pmf_categorical, ... mean=lambda : np.float64(0), ... median=lambda : np.float64(0), ... ) >>> >>> # Sample from new random variable >>> np.random.seed(42) >>> x.sample(3) array([0, 1, 1]) >>> x.pmf(2) 0.0 >>> x.mean 0.0
Attributes Summary
Transpose the random variable.
Covariance \(\operatorname{Cov}(X) = \mathbb{E}((X\mathbb{E}(X))(X\mathbb{E}(X))^\top)\) of the random variable.
Data type of (elements of) a realization of this random variable.
Informationtheoretic entropy \(H(X)\) of the random variable.
Mean \(\mathbb{E}(X)\) of the random variable.
Median of the random variable.
The dtype of the
median
.Mode of the random variable.
The dtype of any (function of a) moment of the random variable, e.g.
Number of dimensions of realizations of the random variable.
Parameters of the associated probability distribution.
Random state of the random variable.
Shape of realizations of the random variable.
Size of realizations of the random variable, defined as the product over all components of
shape()
.Standard deviation of the random variable.
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 nonzero probability, i.e. ifx
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)Logcumulative distribution function.
logpmf
(x)Natural logarithm of the probability mass function.
pmf
(x)Probability mass 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 ofnumpy.ndarray.transpose()
. Return type

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
.

entropy
¶ Informationtheoretic 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
andnumpy.float_
. This is motivated by the fact that, even for discrete random variables, e.g. integervalued random variables, themedian
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

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
, orstd
. It will be set to the dtype arising from the multiplication of values with dtypesdtype
andnumpy.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 dtypesnumpy.float_
anddtype
, respectively. Return type

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
.

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
]

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)¶ 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 theshape
of the random variable. The cdf evaluation will be broadcast over all additional dimensions. Return type
float64

in_support
(x)¶ Check whether the random variable takes value
x
with nonzero probability, i.e. ifx
is in the support of its distribution. Parameters
x (~ValueType) – Input value.
 Return type

static
infer_median_dtype
(value_dtype)¶ Infer the dtype of the median.
Set the dtype to the dtype arising from the multiplication of values with dtypes
dtype
andnumpy.float_
. This is motivated by the fact that, even for discrete random variables, e.g. integervalued random variables, themedian
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\).

static
infer_moment_dtype
(value_dtype)¶ 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
, orstd
. Returns the dtype arising from the multiplication of values with dtypesdtype
andnumpy.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 dtypesnumpy.float_
anddtype
, respectively.

logcdf
(x)¶ Logcumulative 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 theshape
of the random variable. The logcdf evaluation will be broadcast over all additional dimensions. Return type
float64

logpmf
(x)[source]¶ Natural logarithm of the probability mass function.
 Parameters
x (~ValueType) – Evaluation points of the logprobability mass function. The shape of this argument should be
(..., S1, ..., SN)
, where(S1, ..., SN)
is theshape
of the random variable. The logpmf evaluation will be broadcast over all additional dimensions. Return type
float64

pmf
(x)[source]¶ Probability mass function.
Computes the probability of the random variable being equal to the given value. For a random variable \(X\) it is defined as \(p_X(x) = P(X = x)\) for a probability measure \(P\).
Probability mass functions are the discrete analogue of probability density functions in the sense that they are the RadonNikodym derivative of the pushforward measure \(P \circ X^{1}\) defined by the random variable with respect to the counting measure.
 Parameters
x (~ValueType) – Evaluation points of the probability mass function. The shape of this argument should be
(..., S1, ..., SN)
, where(S1, ..., SN)
is theshape
of the random variable. The pmf evaluation will be broadcast over all additional dimensions. Return type
float64

quantile
(p)¶ 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 themedian
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)¶ Give a new shape to a random variable.

sample
(size=())¶ Draw realizations from a random variable.

transpose
(*axes)¶ Transpose the random variable.
 Parameters
axes (
int
) – See documentation ofnumpy.ndarray.transpose()
. Return type