# BayesBase.jl

`BayesBase`

is a package that serves as an umbrella, defining, exporting, and re-exporting methods essential for Bayesian statistics specifically for the `RxInfer`

ecosystem.

Related projects:

# Index

`BayesBase.ClosedProd`

`BayesBase.Contingency`

`BayesBase.ContinuousMultivariateLogPdf`

`BayesBase.ContinuousUnivariateLogPdf`

`BayesBase.CountingReal`

`BayesBase.FactorizedJoint`

`BayesBase.GenericProd`

`BayesBase.LinearizedProductOf`

`BayesBase.MixtureDistribution`

`BayesBase.PointMass`

`BayesBase.PreserveTypeLeftProd`

`BayesBase.PreserveTypeProd`

`BayesBase.PreserveTypeRightProd`

`BayesBase.ProductOf`

`BayesBase.SampleList`

`BayesBase.TerminalProdArgument`

`BayesBase.UnspecifiedDimension`

`BayesBase.UnspecifiedDomain`

`BayesBase.UnspecifiedProd`

`Base.prod`

`BayesBase.Infinity`

`BayesBase.MinusInfinity`

`BayesBase.clamplog`

`BayesBase.convert_paramfloattype`

`BayesBase.deep_eltype`

`BayesBase.default_prod_rule`

`BayesBase.distribution_typewrapper`

`BayesBase.dtanh`

`BayesBase.fuse_supports`

`BayesBase.isequal_typeof`

`BayesBase.logmvbeta`

`BayesBase.logpdf_optimized`

`BayesBase.logpdf_sampling_optimized`

`BayesBase.mean_cov`

`BayesBase.mean_invcov`

`BayesBase.mean_precision`

`BayesBase.mean_std`

`BayesBase.mean_var`

`BayesBase.mirrorlog`

`BayesBase.mvtrigamma`

`BayesBase.paramfloattype`

`BayesBase.probvec`

`BayesBase.promote_paramfloattype`

`BayesBase.promote_samplefloattype`

`BayesBase.promote_sampletype`

`BayesBase.promote_variate_type`

`BayesBase.resolve_prod_strategy`

`BayesBase.samplefloattype`

`BayesBase.sampletype`

`BayesBase.sampling_optimized`

`BayesBase.vague`

`BayesBase.weightedmean`

`BayesBase.weightedmean_cov`

`BayesBase.weightedmean_invcov`

`BayesBase.weightedmean_std`

`BayesBase.weightedmean_var`

`BayesBase.xtlog`

# Library API

## Generic densities

`BayesBase.PointMass`

— Type`PointMass(point)`

A `PointMass`

structure represents a delta distribution, a discrete probability distribution where all probability mass is concentrated at a single point. This point is specified by the provided `point`

.

`BayesBase.ContinuousUnivariateLogPdf`

— Type`ContinuousUnivariateLogPdf{ D <: DomainSets.Domain, F } <: AbstractContinuousGenericLogPdf`

Generic continuous univariate distribution in a form of domain specification and logpdf function. Can be used in cases where no known analytical distribution available.

**Arguments**

`domain`

: domain specificatiom from`DomainSets.jl`

package, by default the`domain`

is set to`DomainSets.FullSpace()`

. Use`BayesBase.UnspecifiedDomain()`

to bypass domain checks.`logpdf`

: callable object that represents the logdensity. Can be un-normalised.

`BayesBase.ContinuousMultivariateLogPdf`

— Type`ContinuousMultivariateLogPdf{ D <: DomainSets.Domain, F } <: AbstractContinuousGenericLogPdf`

Generic continuous multivariate distribution in a form of domain specification and logpdf function. Can be used in cases where no known analytical distribution available.

**Arguments**

`domain`

: multidimensional domain specification from`DomainSets.jl`

package. Use`BayesBase.UnspecifiedDomain()`

to bypass domain checks.`logpdf`

: callable object that accepts an`AbstractVector`

as an input and represents the logdensity. Can be un-normalised.

`BayesBase.SampleList`

— Type`SampleList`

Generic distribution represented as a list of weighted samples.

**Arguments**

`samples::S`

`weights::W`

: optional, equivalent to`fill(1 / N, N)`

by default, where`N`

is the length of`samples`

container

`BayesBase.FactorizedJoint`

— Type`FactorizedJoint(components)`

`FactorizedJoint`

represents a joint distribution of independent random variables. Use `component()`

function or square-brackets indexing to access the marginal distribution for individual variables. Use `components()`

function to get a tuple of multipliers.

`BayesBase.MixtureDistribution`

— Type`MixtureDistribution(components, weights)`

A custom mixture distribution implementation, parameterized by:

`C`

type family of the mixture`CT`

the type for the weights

This implementation solves:

`BayesBase.Contingency`

— Type`Contingency(P, renormalize = Val(true))`

The contingency distribution is a multivariate generalization of the categorical distribution. As a bivariate distribution, the contingency distribution defines the joint probability over two unit vectors `v1`

and `v2`

. The parameter `P`

encodes a contingency matrix that specifies the probability of co-occurrence.

```
v1 ∈ {0, 1}^d1 where Σ_j v1_j = 1
v2 ∈ {0, 1}^d2 where Σ_k v2_k = 1
P ∈ [0, 1]^{d1 × d2}, where Σ_jk P_jk = 1
f(v1, v2, P) = Contingency(out1, out2 | P) = Π_jk P_jk^{v1_j * v2_k}
```

A `Contingency`

distribution over more than two variables requires higher-order tensors as parameters; these are not implemented in ReactiveMP.

**Arguments:**

`P`

, required, contingency matrix`renormalize`

, optional, supports either`Val(true)`

or`Val(false)`

, specifies whether matrix`P`

must be automatically renormalized. Does not modify the original`P`

and allocates a new one for the renormalized version. If set to`false`

the contingency matrix`P`

**must**be normalized by hand, otherwise the result of related calculations might be wrong

## Product API

The `prod`

function defines an interface to compute a product between two probability distributions over the same variable. It accepts a strategy as its first argument, which defines how the prod function should behave and what results you can expect.

`Base.prod`

— Method`prod(strategy, left, right)`

`prod`

function is used to find a product of two probability distributions (or any other objects) over same variable (e.g. 𝓝(x|μ*1, σ*1) × 𝓝(x|μ*2, σ*2)). There are multiple strategies for prod function, e.g. `ClosedProd`

, `GenericProd`

or `PreserveTypeProd`

.

See also: `default_prod_rule`

, `ClosedProd`

, `PreserveTypeProd`

, `GenericProd`

`BayesBase.default_prod_rule`

— Function`default_prod_rule(::Type, ::Type)`

Returns the most suitable `prod`

rule for two given distribution types. Returns `UnspecifiedProd`

by default.

See also: `prod`

, `ClosedProd`

, `GenericProd`

### Product strategies

For certain distributions, it's possible to compute the product using a straightforward mathematical equation, yielding a closed-form solution. However, for some distributions, finding a closed-form solution might not be feasible. Various strategies ensure consistent behavior in these situations. These strategies can either guarantee a fast and closed-form solution or, when necessary, fall back to a slower but more generic method.

`BayesBase.UnspecifiedProd`

— Type`UnspecifiedProd`

A strategy for the `prod`

function, which does not compute the `prod`

, but instead fails in run-time and prints a descriptive error message.

See also: `prod`

, `ClosedProd`

, `GenericProd`

`BayesBase.ClosedProd`

— Type`ClosedProd`

`ClosedProd`

is one of the strategies for `prod`

function. For example, if both inputs are of type `Distribution`

, then `ClosedProd`

would fallback to `PreserveTypeProd(Distribution)`

.

See also: `prod`

, `PreserveTypeProd`

, `GenericProd`

`BayesBase.PreserveTypeProd`

— Type`PreserveTypeProd{T}`

`PreserveTypeProd`

is one of the strategies for `prod`

function. This strategy constraint an output of a prod to be in some specific form. By default it uses the strategy from `default_prod_rule`

and converts the output to the prespecified type but can be overwritten for some distributions for better performance.

See also: `prod`

, `ClosedProd`

, `PreserveTypeLeftProd`

, `PreserveTypeRightProd`

, `GenericProd`

`BayesBase.PreserveTypeLeftProd`

— Type`PreserveTypeLeftProd`

An alias for the `PreserveTypeProd(L)`

where `L`

is the type of the `left`

argument of the `prod`

function.

See also: `prod`

, `PreserveTypeProd`

, `PreserveTypeRightProd`

, `GenericProd`

`BayesBase.PreserveTypeRightProd`

— Type`PreserveTypeRightProd`

An alias for the `PreserveTypeProd(R)`

where `R`

is the type of the `right`

argument of the `prod`

function.

See also: `prod`

, `PreserveTypeProd`

, `PreserveTypeLeftProd`

, `GenericProd`

`BayesBase.GenericProd`

— Type`GenericProd`

`GenericProd`

is one of the strategies for `prod`

function. This strategy does always produces a result, even if the closed form product is not availble, in which case simply returns the `ProductOf`

object. `GenericProd`

sometimes fallbacks to the `default_prod_rule`

which it may or may not use under some circumstances. For example if the `default_prod_rule`

is `ClosedProd`

- `GenericProd`

will try to optimize the tree with analytical closed solutions (if possible).

See also: `prod`

, `ProductOf`

, `ClosedProd`

, `PreserveTypeProd`

, `default_prod_rule`

`BayesBase.ProductOf`

— Type`ProductOf`

A generic structure representing a product of two distributions. Can be viewed as a tuple of `(left, right)`

. Does not check nor supports neither variate forms during the creation stage. Uses the `fuse_support`

function to fuse supports of two different distributions.

This object does not define any statistical properties (such as `mean`

or `var`

etc) and cannot be used as a distribution explicitly. Instead, it must be further approximated as a member of some other distribution.

See also: `prod`

, `GenericProd`

, `fuse_supports`

`BayesBase.LinearizedProductOf`

— Type`LinearizedProductOf`

An efficient **linearized** implementation of product of multiple distributions. This structure prevents `ProductOf`

tree from growing too much in case of identical objects. This trick significantly reduces Julia compilation times when closed product rules are not available but distributions are of the same type. Essentially this structure linearizes leaves of the `ProductOf`

tree in case if it sees objects of the same type (via dispatch).

See also: `ProductOf`

, [`GenericProd`

]

`BayesBase.TerminalProdArgument`

— Type`TerminalProdArgument(argument)`

`TerminalProdArgument`

is a specialized wrapper structure. When used as an argument to the `prod`

function, it returns itself without considering any product strategy and does not perform any safety checks (e.g. `variate_form`

or `support`

). Attempting to calculate the product of two instances of `TerminalProdArgument`

will raise an error. Use `.argument`

field to get the underlying wrapped argument.

`BayesBase.resolve_prod_strategy`

— Function`resolve_prod_strategy(left, right)`

Given two strategies, this function returns the one with higher priority, if possible.

These strategies offer flexibility and reliability when working with different types of distributions, ensuring that the package can handle a wide range of cases effectively.

## Promotion type utilities

`BayesBase.deep_eltype`

— Function`deep_eltype(T)`

Returns:

`deep_eltype`

of`T`

if`T`

is an`AbstractArray`

container`T`

otherwise

```
julia> deep_eltype(Float64)
Float64
julia> deep_eltype(Vector{Float64})
Float64
julia> deep_eltype(Vector{Matrix{Vector{Float64}}})
Float64
```

`BayesBase.isequal_typeof`

— Function`isequal_typeof(left, right)`

Alias for `typeof(left) === typeof(right)`

, but can be specialized.

`BayesBase.paramfloattype`

— Function`paramfloattype(distribution)`

Returns the underlying float type of distribution's parameters.

See also: `promote_paramfloattype`

, `convert_paramfloattype`

`BayesBase.sampletype`

— Function`sampletype(distribution)`

Returns a type of the distribution. By default fallbacks to the `eltype`

.

See also: `samplefloattype`

, `promote_sampletype`

, `promote_samplefloattype`

`BayesBase.samplefloattype`

— Function`samplefloattype(distribution)`

Returns a type of the distribution or the underlying float type in case if sample is `Multivariate`

or `Matrixvariate`

. By default fallbacks to the `deep_eltype(sampletype(distribution))`

.

See also: `sampletype`

, `promote_sampletype`

, `promote_samplefloattype`

`BayesBase.promote_variate_type`

— Function`promote_variate_type(::Type{ <: VariateForm }, distribution_type)`

Promotes (if possible) a `distribution_type`

to be of the specified variate form.

`BayesBase.promote_paramfloattype`

— Function`promote_paramfloattype(distributions...)`

Promotes `paramfloattype`

of the `distributions`

to a single type. See also `promote_type`

.

See also: `paramfloattype`

, `convert_paramfloattype`

`BayesBase.promote_sampletype`

— Function`promote_sampletype(distributions...)`

Promotes `sampletype`

of the `distributions`

to a single type. See also `promote_type`

.

See also: `sampletype`

, `samplefloattype`

, `promote_samplefloattype`

`BayesBase.promote_samplefloattype`

— Function`promote_samplefloattype(distributions...)`

Promotes `samplefloattype`

of the `distributions`

to a single type. See also `promote_type`

.

See also: `sampletype`

, `samplefloattype`

, `promote_sampletype`

`BayesBase.convert_paramfloattype`

— Function`convert_paramfloattype(::Type{T}, distribution)`

Converts (if possible) the params float type of the `distribution`

to be of type `T`

.

See also: `paramfloattype`

, `promote_paramfloattype`

`convert_paramfloattype(::Type{T}, container)`

Converts (if possible) the elements of the `container`

to be of type `T`

.

## Extra stats functions

`BayesBase.mirrorlog`

— Function`mirrorlog(x)`

Returns `log(1 - x)`

.

`BayesBase.xtlog`

— Function`xtlog(x)`

Returns `x * log(x)`

.

`BayesBase.logmvbeta`

— Function`logmvbeta(x)`

Uses the numerically stable algorithm to compute the logarithm of the multivariate beta distribution over with the parameter vector x.

`BayesBase.clamplog`

— Function`clamplog(x)`

Same as `log`

but clamps the input argument `x`

to be in the range `tiny <= x <= typemax(x)`

such that `log(0)`

does not explode.

`BayesBase.mvtrigamma`

— Function`mvtrigamma(p, x)`

Computes multivariate trigamma function .

`BayesBase.dtanh`

— Function`dtanh(x)`

Alias for `1 - tanh(x) ^ 2`

`BayesBase.probvec`

— Function`probvec(d)`

Returns the probability vector of the given distribution.

`BayesBase.mean_std`

— FunctionAlias for `(mean(d), std(d))`

, but can be specialized.

`BayesBase.mean_var`

— FunctionAlias for `(mean(d), var(d))`

, but can be specialized.

`BayesBase.mean_cov`

— FunctionAlias for `(mean(d), cov(d))`

, but can be specialized.

`BayesBase.mean_invcov`

— FunctionAlias for `(mean(d), invcov(d))`

, but can be specialized.

`BayesBase.mean_precision`

— FunctionAlias for `mean_invcov(d)`

, but can be specialized.

`BayesBase.weightedmean`

— Function`weightedmean(d)`

Returns the weighted mean of the given distribution. Alias to `invcov(d) * mean(d)`

, but can be specialized

`BayesBase.weightedmean_std`

— FunctionAlias for `(weightedmean(d), std(d))`

, but can be specialized.

`BayesBase.weightedmean_var`

— FunctionAlias for `(weightedmean(d), var(d))`

, but can be specialized.

`BayesBase.weightedmean_cov`

— FunctionAlias for `(weightedmean(d), cov(d))`

, but can be specialized.

`BayesBase.weightedmean_invcov`

— FunctionAlias for `weightedmean_invcov(d)`

, but can be specialized.

## Helper utilities

`BayesBase.vague`

— Function`vague(distribution_type, [ dims... ])`

Returns uninformative probability distribution of the given type.

`BayesBase.logpdf_sampling_optimized`

— Function`logpdf_sampling_optimized(d)`

`logpdf_sample_optimized`

function takes as an input a distribution `d`

and returns corresponding optimized two versions for taking `logpdf()`

and sampling with `rand!`

respectively. Alias for `(logpdf_optimized(d), sampling_optimized(d))`

, but can be specialized.

`BayesBase.logpdf_optimized`

— Function`logpdf_optimized(d)`

Returns a version of `d`

specifically optimized to call `logpdf(d, x)`

. By default returns the same `d`

, but can be specialized.

`BayesBase.sampling_optimized`

— Function`sampling_optimized(d)`

Returns a version of `d`

specifically optimized to call `rand`

and `rand!`

. By default returns the same `d`

, but can be specialized.

`BayesBase.fuse_supports`

— Function`fuse_supports(left, right)`

Fuses supports `left`

and `right`

. By default, checks that the inputs are identical and throws an error otherwise. Can implement specific fusions for specific supports.

`BayesBase.UnspecifiedDomain`

— TypeUnknown domain that is used as a placeholder when exact domain knowledge is unavailable

`BayesBase.UnspecifiedDimension`

— TypeUnknown dimension is equal and not equal to any number

`BayesBase.distribution_typewrapper`

— FunctionStrips type parameters from the type of the `distribution`

.

`BayesBase.CountingReal`

— Type`CountingReal`

`CountingReal`

implements a real "number" that counts 'infinities' in a separate field. See also `BayesBase.Infinity`

and `BayesBase.MinusInfinity`

.

**Arguments**

`value::T`

: value of type`<: Real`

`infinities::Int`

: number of added/subtracted infinities

```
julia> r = BayesBase.CountingReal(0.0, 0)
CountingReal{Float64}(0.0, 0)
julia> float(r)
0.0
julia> r = r + BayesBase.Infinity(Float64)
CountingReal{Float64}(0.0, 1)
julia> float(r)
Inf
julia> r = r + BayesBase.MinusInfinity(Float64)
CountingReal{Float64}(0.0, 0)
julia> float(r)
0.0
```

`BayesBase.Infinity`

— FunctionAn object representing infinity.

`BayesBase.MinusInfinity`

— FunctionAn object representing minus infinity.