Normal¶
- class probnum.randvars.Normal(mean, cov, cov_cholesky=None, random_state=None)¶
Bases:
probnum.randvars._random_variable.ContinuousRandomVariable
[Union
[numpy.floating
,numpy.ndarray
,probnum.linops.LinearOperator
]]Random variable with a normal distribution.
Gaussian random variables are ubiquitous in probability theory, since the Gaussian is the equilibrium distribution to which other distributions gravitate under a wide variety of smooth operations, e.g., convolutions and stochastic transformations. One example of this is the central limit theorem. Gaussian random variables are also attractive from a numerical point of view as they maintain their distribution family through many transformations (e.g. they are stable). In particular, they allow for efficient closed-form Bayesian inference given linear observations.
- Parameters
mean (
Union
[float
,floating
,ndarray
,LinearOperator
]) – Mean of the random variable.cov (
Union
[float
,floating
,ndarray
,LinearOperator
]) – (Co-)variance of the random variable.cov_cholesky (
Union
[float
,floating
,ndarray
,LinearOperator
,None
]) – (Lower triangular) Cholesky factor of the covariance matrix. If None, then the Cholesky factor of the covariance matrix is computed whenNormal.cov_cholesky
is called and then cached. If specified, the value is returned byNormal.cov_cholesky
. In this case, its type and data type are compared to the type and data type of the covariance. If the types do not match, an exception is thrown. If the data types do not match, the data type of the Cholesky factor is promoted to the data type of the covariance matrix.random_state (
Union
[None
,int
,RandomState
,Generator
]) – 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.
See also
RandomVariable
Class representing random variables.
Examples
>>> from probnum import randvars >>> x = randvars.Normal(mean=0.5, cov=1.0, random_state=42) >>> x.sample(size=(2, 2)) array([[0.99671415, 0.3617357 ], [1.14768854, 2.02302986]])
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.
Cholesky factor \(L\) of the covariance \(\operatorname{Cov}(X) =LL^\top\).
Return truth-value of whether the Cholesky factor of the covariance is readily available.
Dense representation of the covariance.
Dense representation of the mean.
Data type of (elements of) a realization of this random variable.
Information-theoretic 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.
dense_cov_cholesky
([damping_factor])Compute the Cholesky factorization of the covariance from its dense representation.
in_support
(x)Check whether the random variable takes value
x
with non-zero 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)Log-cumulative distribution function.
logpdf
(x)Natural logarithm of the probability density function.
pdf
(x)Probability density function.
precompute_cov_cholesky
([damping_factor])(P)recompute Cholesky factors (careful: in-place operation!).
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
.
- cov_cholesky¶
Cholesky factor \(L\) of the covariance \(\operatorname{Cov}(X) =LL^\top\).
- Return type
- cov_cholesky_is_precomputed¶
Return truth-value of whether the Cholesky factor of the covariance is readily available.
This happens if (i) the Cholesky factor is specified during initialization or if (ii) the property self.cov_cholesky has been called before.
- Return type
- dense_cov¶
Dense representation of the covariance.
- dense_mean¶
Dense representation of the mean.
- 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
andnumpy.float_
. This is motivated by the fact that, even for discrete random variables, e.g. integer-valued 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
- 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
- dense_cov_cholesky(damping_factor=1e-12)[source]¶
Compute the Cholesky factorization of the covariance from its dense representation.
- Return type
- in_support(x)¶
Check whether the random variable takes value
x
with non-zero 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. integer-valued 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)¶
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 theshape
of the random variable. The logcdf evaluation will be broadcast over all additional dimensions.- Return type
float64
- logpdf(x)¶
Natural logarithm of the probability density function.
- Parameters
x (~ValueType) – Evaluation points of the log-probability density function. The shape of this argument should be
(..., S1, ..., SN)
, where(S1, ..., SN)
is theshape
of the random variable. The logpdf evaluation will be broadcast over all additional dimensions.- Return type
float64
- pdf(x)¶
Probability density function.
The area under the curve defined by the probability density function specifies the probability of the random variable \(X\) taking values within that area.
Probability density functions are defined as the Radon-Nikodym derivative of the pushforward measure \(P \circ X^{-1}\) with respect to the Lebesgue measure for a given probability measure \(P\). Following convention we always assume the Lebesgue measure as a base measure unless stated otherwise.
- Parameters
x (~ValueType) – Evaluation points of the probability density function. The shape of this argument should be
(..., S1, ..., SN)
, where(S1, ..., SN)
is theshape
of the random variable. The pdf evaluation will be broadcast over all additional dimensions.- Return type
float64
- precompute_cov_cholesky(damping_factor=1e-12)[source]¶
(P)recompute Cholesky factors (careful: in-place operation!).
- 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
- sample(size=())¶
Draw realizations from a random variable.
- transpose(*axes)[source]¶
Transpose the random variable.
- Parameters
axes (
int
) – See documentation ofnumpy.ndarray.transpose()
.- Return type