diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 2ee13987..ee07eb10 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-03T10:47:57","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-11-24T12:19:50","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/dev/examples/index.html b/dev/examples/index.html index 7b93e855..8c12698c 100644 --- a/dev/examples/index.html +++ b/dev/examples/index.html @@ -45,4 +45,4 @@ fisherinformation_of_gamma_in_natural_space(gamma_parameters_in_natural_space)
2×2 StaticArraysCore.SMatrix{2, 2, Float64, 4} with indices SOneTo(2)×SOneTo(2):
  1.64493  2.0
- 2.0      4.0

Approximating attributes

Refer to the ExpectationApproximations.jl package for approximating various attributes of the members of the exponential family.

+ 2.0 4.0

Approximating attributes

Refer to the ExpectationApproximations.jl package for approximating various attributes of the members of the exponential family.

diff --git a/dev/index.html b/dev/index.html index 6eb27cb4..f4828d59 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · ExponentialFamily.jl
GitHub

ExponentialFamily.jl

Julia package that extends the functionality of Distributions.jl by providing a collection of exponential family distributions and customized implementations. It is designed to facilitate working with exponential family distributions and offers specialized functionality tailored to this class of distributions.

Core Principles

The package is built around several core principles:

  • High performance with minimal allocations, striving for complete type stability.
  • Compatibility with distributions defined in Distributions.jl.
  • Ease of use and rich functionality.

Table of Contents

Index

+Home · ExponentialFamily.jl
GitHub

ExponentialFamily.jl

Julia package that extends the functionality of Distributions.jl by providing a collection of exponential family distributions and customized implementations. It is designed to facilitate working with exponential family distributions and offers specialized functionality tailored to this class of distributions.

Core Principles

The package is built around several core principles:

  • High performance with minimal allocations, striving for complete type stability.
  • Compatibility with distributions defined in Distributions.jl.
  • Ease of use and rich functionality.

Table of Contents

Index

diff --git a/dev/interface/index.html b/dev/interface/index.html index 416e3fb0..12f61793 100644 --- a/dev/interface/index.html +++ b/dev/interface/index.html @@ -7,29 +7,29 @@ ExponentialFamily(Laplace, conditioned on 1.0) julia> logpdf(ef, 4.0) --6.0

See also: getbasemeasure, getsufficientstatistics, getnaturalparameters, getlogpartition, getsupport

source
ExponentialFamily.ExponentialFamilyDistributionAttributes — Type
ExponentialFamilyDistributionAttributes(basemeasure, sufficientstatistics, logpartition, support)

A structure to represent the attributes of an exponential family member.

Fields

  • basemeasure::B: The basemeasure of the exponential family member.
  • sufficientstatistics::S: The sufficient statistics of the exponential family member.
  • logpartition::L: The log-partition (cumulant) of the exponential family member.
  • support::P: The support of the exponential family member.

See also: ExponentialFamilyDistribution, getbasemeasure, getsufficientstatistics, getlogpartition, getsupport

source
Distributions.logpdf — Method
logpdf(ef::ExponentialFamilyDistribution, x)

Evaluates and returns the log-density of the exponential family distribution for the input x.

source
Distributions.pdf — Method
pdf(ef::ExponentialFamilyDistribution, x)

Evaluates and returns the probability density function of the exponential family distribution for the input x.

source
Distributions.cdf — Method
cdf(ef::ExponentialFamilyDistribution{D}, x) where { D <: Distribution }

Evaluates and returns the cumulative distribution function of the exponential family distribution for the input x.

source
ExponentialFamily.getnaturalparameters — Function
getnaturalparameters(::ExponentialFamilyDistribution)

Get the natural parameters of the exponential family distribution.

source
ExponentialFamily.getattributes — Function
getattributes(::ExponentialFamilyDistribution)

Returns iether the attributes of the exponential family member or nothing.

See also: ExponentialFamilyDistributionAttributes

source
ExponentialFamily.getconditioner — Function
getconditioner(::ExponentialFamilyDistribution)

Returns either the conditioner of the exponential family distribution or nothing. conditioner is a fixed parameter that is used to ensure that the distribution belongs to the exponential family.

source
ExponentialFamily.isproper — Function
isproper(::ExponentialFamilyDistribution)

Checks if the object of type ExponentialFamilyDistribution is a proper distribution.

source
isproper([ space = NaturalParametersSpace() ], ::Type{T}, parameters, conditioner = nothing) where { T <: Distribution }

A specific verion of isproper defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. Optionally, accepts the space parameter, which defines the parameters space. For conditional exponential family distributions requires an extra conditioner argument.

See also: NaturalParametersSpace, MeanParametersSpace

source
ExponentialFamily.getbasemeasure — Function
getbasemeasure(::ExponentialFamilyDistribution)
-getbasemeasure(::Type{ <: Distribution }, [ conditioner ])

Returns the base measure function of the exponential family distribution.

source
ExponentialFamily.getsufficientstatistics — Function
getsufficientstatistics(::ExponentialFamilyDistribution)
-getsufficientstatistics(::Type{ <: Distribution }, [ conditioner ])

Returns the list of sufficient statistics of the exponential family distribution.

source
ExponentialFamily.getlogpartition — Function
getlogpartition(::ExponentialFamilyDistribution)
-getlogpartition([ space ], ::Type{ <: Distribution }, [ conditioner ])

Returns the log partition function of the exponential family distribution.

source
ExponentialFamily.getfisherinformation — Function
getfisherinformation(::ExponentialFamilyDistribution)
-getfisherinformation([ space ], ::Type{ <: Distribution }, [ conditioner ])

Returns the function that computes the fisher information matrix of the exponential family distribution.

source
ExponentialFamily.getsupport — Function
getsupport(distribution_or_type)

Returns the support of the exponential family distribution.

source
ExponentialFamily.basemeasure — Function
basemeasure(::ExponentialFamilyDistribution, x)

Returns the computed value of basemeasure of the exponential family distribution at the point x.

See also: getbasemeasure

source
ExponentialFamily.sufficientstatistics — Function
sufficientstatistics(::ExponentialFamilyDistribution)

Returns the computed values of sufficientstatistics of the exponential family distribution at the point x.

source
ExponentialFamily.logpartition — Function
logpartition(::ExponentialFamilyDistribution, η)

Return the computed value of logpartition of the exponential family distribution at the point η. By default η = getnaturalparameters(ef).

See also: getlogpartition

source
ExponentialFamily.fisherinformation — Function
fisherinformation(distribution, η)

Return the computed value of fisherinformation of the exponential family distribution at the point η By default η = getnaturalparameters(ef).

See also: getfisherinformation

source
ExponentialFamily.isbasemeasureconstant — Function
isbasemeasureconstant(something)

Returns either NonConstantBaseMeasure() or ConstantBaseMeasure() depending on if the base measure is a constant with respect to the natural parameters of something or not. By default the package assumes that any base measure in a form of the Function is not a constant. It, however, is not true for basemeasure that simply return a constant. In such cases the isbasemeasureconstant must have a specific method.

See also: getbasemeasure, basemeasure

source
ExponentialFamily.ConstantBaseMeasure — Type

A trait object representing that the base measure is constant.

source
ExponentialFamily.NonConstantBaseMeasure — Type

A trait object representing that the base measure is not constant.

source

Interfacing with Distributions Defined in the Distributions.jl Package

The Distributions.jl package is a comprehensive library that defines a wide collection of standard distributions. The main objective of the Distributions package is to offer a unified interface for evaluating likelihoods of various distributions, along with convenient sampling routines from these distributions. The ExponentialFamily package provides a lightweight interface for a subset of the distributions defined in the Distributions package.

Conversion between Mean Parameters Space and Natural Parameters Space

The Distributions package introduces the params function, which allows the retrieval of parameters for different distributions. For example:

using Distributions, ExponentialFamily
+-6.0

See also: getbasemeasure, getsufficientstatistics, getnaturalparameters, getlogpartition, getsupport

source
ExponentialFamily.ExponentialFamilyDistributionAttributes — Type
ExponentialFamilyDistributionAttributes(basemeasure, sufficientstatistics, logpartition, support)

A structure to represent the attributes of an exponential family member.

Fields

  • basemeasure::B: The basemeasure of the exponential family member.
  • sufficientstatistics::S: The sufficient statistics of the exponential family member.
  • logpartition::L: The log-partition (cumulant) of the exponential family member.
  • support::P: The support of the exponential family member.

See also: ExponentialFamilyDistribution, getbasemeasure, getsufficientstatistics, getlogpartition, getsupport

source
Distributions.logpdf — Method
logpdf(ef::ExponentialFamilyDistribution, x)

Evaluates and returns the log-density of the exponential family distribution for the input x.

source
Distributions.pdf — Method
pdf(ef::ExponentialFamilyDistribution, x)

Evaluates and returns the probability density function of the exponential family distribution for the input x.

source
Distributions.cdf — Method
cdf(ef::ExponentialFamilyDistribution{D}, x) where { D <: Distribution }

Evaluates and returns the cumulative distribution function of the exponential family distribution for the input x.

source
ExponentialFamily.getnaturalparameters — Function
getnaturalparameters(::ExponentialFamilyDistribution)

Get the natural parameters of the exponential family distribution.

source
ExponentialFamily.getattributes — Function
getattributes(::ExponentialFamilyDistribution)

Returns iether the attributes of the exponential family member or nothing.

See also: ExponentialFamilyDistributionAttributes

source
ExponentialFamily.getconditioner — Function
getconditioner(::ExponentialFamilyDistribution)

Returns either the conditioner of the exponential family distribution or nothing. conditioner is a fixed parameter that is used to ensure that the distribution belongs to the exponential family.

source
ExponentialFamily.isproper — Function
isproper(::ExponentialFamilyDistribution)

Checks if the object of type ExponentialFamilyDistribution is a proper distribution.

source
isproper([ space = NaturalParametersSpace() ], ::Type{T}, parameters, conditioner = nothing) where { T <: Distribution }

A specific verion of isproper defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. Optionally, accepts the space parameter, which defines the parameters space. For conditional exponential family distributions requires an extra conditioner argument.

See also: NaturalParametersSpace, MeanParametersSpace

source
ExponentialFamily.getbasemeasure — Function
getbasemeasure(::ExponentialFamilyDistribution)
+getbasemeasure(::Type{ <: Distribution }, [ conditioner ])

Returns the base measure function of the exponential family distribution.

source
ExponentialFamily.getsufficientstatistics — Function
getsufficientstatistics(::ExponentialFamilyDistribution)
+getsufficientstatistics(::Type{ <: Distribution }, [ conditioner ])

Returns the list of sufficient statistics of the exponential family distribution.

source
ExponentialFamily.getlogpartition — Function
getlogpartition(::ExponentialFamilyDistribution)
+getlogpartition([ space ], ::Type{ <: Distribution }, [ conditioner ])

Returns the log partition function of the exponential family distribution.

source
ExponentialFamily.getfisherinformation — Function
getfisherinformation(::ExponentialFamilyDistribution)
+getfisherinformation([ space ], ::Type{ <: Distribution }, [ conditioner ])

Returns the function that computes the fisher information matrix of the exponential family distribution.

source
ExponentialFamily.getsupport — Function
getsupport(distribution_or_type)

Returns the support of the exponential family distribution.

source
ExponentialFamily.basemeasure — Function
basemeasure(::ExponentialFamilyDistribution, x)

Returns the computed value of basemeasure of the exponential family distribution at the point x.

See also: getbasemeasure

source
ExponentialFamily.sufficientstatistics — Function
sufficientstatistics(::ExponentialFamilyDistribution)

Returns the computed values of sufficientstatistics of the exponential family distribution at the point x.

source
ExponentialFamily.logpartition — Function
logpartition(::ExponentialFamilyDistribution, η)

Return the computed value of logpartition of the exponential family distribution at the point η. By default η = getnaturalparameters(ef).

See also: getlogpartition

source
ExponentialFamily.fisherinformation — Function
fisherinformation(distribution, η)

Return the computed value of fisherinformation of the exponential family distribution at the point η By default η = getnaturalparameters(ef).

See also: getfisherinformation

source
ExponentialFamily.isbasemeasureconstant — Function
isbasemeasureconstant(something)

Returns either NonConstantBaseMeasure() or ConstantBaseMeasure() depending on if the base measure is a constant with respect to the natural parameters of something or not. By default the package assumes that any base measure in a form of the Function is not a constant. It, however, is not true for basemeasure that simply return a constant. In such cases the isbasemeasureconstant must have a specific method.

See also: getbasemeasure, basemeasure

source
ExponentialFamily.ConstantBaseMeasure — Type

A trait object representing that the base measure is constant.

source
ExponentialFamily.NonConstantBaseMeasure — Type

A trait object representing that the base measure is not constant.

source

Interfacing with Distributions Defined in the Distributions.jl Package

The Distributions.jl package is a comprehensive library that defines a wide collection of standard distributions. The main objective of the Distributions package is to offer a unified interface for evaluating likelihoods of various distributions, along with convenient sampling routines from these distributions. The ExponentialFamily package provides a lightweight interface for a subset of the distributions defined in the Distributions package.

Conversion between Mean Parameters Space and Natural Parameters Space

The Distributions package introduces the params function, which allows the retrieval of parameters for different distributions. For example:

using Distributions, ExponentialFamily
 
 distribution = Bernoulli(0.25)
 
-tuple_of_θ = params(distribution)
(0.25,)

These parameters are typically defined in what's known as the mean parameters space. However, the ExponentialFamilyDistribution expects parameters to be in the natural parameters space. To facilitate conversion between these two representations, the ExponentialFamily package provides two structures:

ExponentialFamily.MeanToNatural — Type
MeanToNatural(::Type{T})

Return the transformation function that maps the parameters in the mean parameters space to the natural parameters space for a distribution of type T. The transformation function is of signature (params_in_mean_space, [ conditioner ]) -> params_in_natural_space.

See also: NaturalToMean, NaturalParametersSpace, MeanParametersSpace, getmapping

source
ExponentialFamily.NaturalToMean — Type
NaturalToMean(::Type{T})

Return the transformation function that maps the parameters in the natural parameters space to the mean parameters space for a distribution of type T. The transformation function is of signature (params_in_natural_space, [ conditioner ]) -> params_in_mean_space.

See also: MeanToNatural, NaturalParametersSpace, MeanParametersSpace, getmapping

source
ExponentialFamily.getmapping — Function
getmapping(::Pair{L, R}, T)

Returns a transformation L -> R between different parametrizations of a distribution of type T.

See also: NaturalParametersSpace, MeanParametersSpace, NaturalToMean, MeanToNatural

source

To convert from the mean parameters space to the corresponding natural parameters space, you can use the following code:

tuple_of_η = MeanToNatural(Bernoulli)(tuple_of_θ)
(-1.0986122886681098,)

And to convert back:

tuple_of_θ = NaturalToMean(Bernoulli)(tuple_of_η)
(0.25,)

Alternatuvely, the following API is supported 

map(MeanParametersSpace() => NaturalParametersSpace(), Bernoulli, tuple_of_θ)
(-1.0986122886681098,)
map(NaturalParametersSpace() => MeanParametersSpace(), Bernoulli, tuple_of_η)
(0.25,)

While the ExponentialFamily package employs the respective mappings where needed, it's also possible to call these functions manually. For instance, the generic implementation of the convert function between ExponentialFamilyDistribution and Distribution is built in terms of MeanToNatural and NaturalToMean. Moreover, the convert function performs checks to ensure that the provided parameters and conditioner are suitable for a specific distribution type.

ExponentialFamily.isproper — Method
isproper([ space = NaturalParametersSpace() ], ::Type{T}, parameters, conditioner = nothing) where { T <: Distribution }

A specific verion of isproper defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. Optionally, accepts the space parameter, which defines the parameters space. For conditional exponential family distributions requires an extra conditioner argument.

See also: NaturalParametersSpace, MeanParametersSpace

source

Note on the conditioned distributions

For the conditioned distributions, two additional functions separate_conditioner and join_conditioner are used to separate the conditioner and actual parameters returned from the Distributions.params function.

ExponentialFamily.separate_conditioner — Function
separate_conditioner(::Type{T}, params) where {T <: Distribution}

Separates the conditioner argument from params and returns a tuple of (conditioned_params, conditioner). By default returns (params, nothing) but can be overwritten for certain distributions.

julia> (cparams, conditioner) = ExponentialFamily.separate_conditioner(Laplace, (0.0, 1.0))
+tuple_of_θ = params(distribution)
(0.25,)

These parameters are typically defined in what's known as the mean parameters space. However, the ExponentialFamilyDistribution expects parameters to be in the natural parameters space. To facilitate conversion between these two representations, the ExponentialFamily package provides two structures:

To convert from the mean parameters space to the corresponding natural parameters space, you can use the following code:

tuple_of_η = MeanToNatural(Bernoulli)(tuple_of_θ)
(-1.0986122886681098,)

And to convert back:

tuple_of_θ = NaturalToMean(Bernoulli)(tuple_of_η)
(0.25,)

Alternatuvely, the following API is supported 

map(MeanParametersSpace() => NaturalParametersSpace(), Bernoulli, tuple_of_θ)
(-1.0986122886681098,)
map(NaturalParametersSpace() => MeanParametersSpace(), Bernoulli, tuple_of_η)
(0.25,)

While the ExponentialFamily package employs the respective mappings where needed, it's also possible to call these functions manually. For instance, the generic implementation of the convert function between ExponentialFamilyDistribution and Distribution is built in terms of MeanToNatural and NaturalToMean. Moreover, the convert function performs checks to ensure that the provided parameters and conditioner are suitable for a specific distribution type.

ExponentialFamily.isproper — Method
isproper([ space = NaturalParametersSpace() ], ::Type{T}, parameters, conditioner = nothing) where { T <: Distribution }

A specific verion of isproper defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. Optionally, accepts the space parameter, which defines the parameters space. For conditional exponential family distributions requires an extra conditioner argument.

See also: NaturalParametersSpace, MeanParametersSpace

source

Note on the conditioned distributions

For the conditioned distributions, two additional functions separate_conditioner and join_conditioner are used to separate the conditioner and actual parameters returned from the Distributions.params function.

ExponentialFamily.separate_conditioner — Function
separate_conditioner(::Type{T}, params) where {T <: Distribution}

Separates the conditioner argument from params and returns a tuple of (conditioned_params, conditioner). By default returns (params, nothing) but can be overwritten for certain distributions.

julia> (cparams, conditioner) = ExponentialFamily.separate_conditioner(Laplace, (0.0, 1.0))
 ((1.0,), 0.0)
 
 julia> params = ExponentialFamily.join_conditioner(Laplace, cparams, conditioner)
 (0.0, 1.0)
 
 julia> Laplace(params...) == Laplace(0.0, 1.0)
-true

See also: ExponentialFamily.join_conditioner

source
ExponentialFamily.join_conditioner — Function
join_conditioner(::Type{T}, params, conditioner) where { T <: Distribution }

Joins the conditioner argument with the params and returns a tuple of joined params, such that it can be used in a constructor of the T distribution.

julia> (cparams, conditioner) = ExponentialFamily.separate_conditioner(Laplace, (0.0, 1.0))
+true

See also: ExponentialFamily.join_conditioner

source
ExponentialFamily.join_conditioner — Function
join_conditioner(::Type{T}, params, conditioner) where { T <: Distribution }

Joins the conditioner argument with the params and returns a tuple of joined params, such that it can be used in a constructor of the T distribution.

julia> (cparams, conditioner) = ExponentialFamily.separate_conditioner(Laplace, (0.0, 1.0))
 ((1.0,), 0.0)
 
 julia> params = ExponentialFamily.join_conditioner(Laplace, cparams, conditioner)
 (0.0, 1.0)
 
 julia> Laplace(params...) == Laplace(0.0, 1.0)
-true

See also: ExponentialFamily.separate_conditioner

source

For example, Laplace distribution defines the functions in the following way

# `params` are coming from the `Distribution.params(::Laplace)` and return (location, scale)
+true

See also: ExponentialFamily.separate_conditioner

source

For example, Laplace distribution defines the functions in the following way

# `params` are coming from the `Distribution.params(::Laplace)` and return (location, scale)
 # The `location`, however is a fixed parameter in the exponential distribution representation of Laplace
 # Hence, we return a tuple of tuple of actual parameter and the conditioner
 function separate_conditioner(::Type{Laplace}, params)
@@ -43,7 +43,7 @@
     (scale, ) = cparams
     location = conditioner
     return (location, scale)
-end

In general, all functions defined for the ExponentialFamilyDistribution, such as getlogpartition or getbasemeasure accept an optional conditioner parameter, which is assumed to be nothing. Conditioned distribution implement the "conditioned" versions of such functions by explicitly requiring the conditioner parameter, e.g.

getsufficientstatistics(Laplace, 1.0) # explicit `conditioner = 1.0`
(ExponentialFamily.var"#340#341"{Float64}(1.0),)

Efficient packing of the natural parameters into a vectorized form

The ExponentialFamilyDistribution type stores its natural parameters in a vectorized, or packed, format. This is done for the sake of efficiency and to enhance compatibility with autodiff packages like ForwardDiff, which anticipate a single parameter vector. As a result, the tuple of natural parameters needs to be converted to its corresponding vectorized form and vice versa. To achieve this, the package provides the flatten_parameters, pack_parameters and unpack_parameters functions.

ExponentialFamily.flatten_parameters — Function
flatten_parameters(::Type{T}, params::Tuple)

This function returns the parameters of a distribution of type T in a flattened form without actually allocating the container.

source
ExponentialFamily.pack_parameters — Function
pack_parameters([ space ], ::Type{T}, params::Tuple)

This function returns the parameters of a distribution of type T in a vectorized (packed) form. For most of the distributions the packed versions are of the same structure in any parameters space. For some distributions, however, it is necessary to indicate the space of the packaged parameters.

julia> ExponentialFamily.pack_parameters((1, [2.0, 3.0], [4.0 5.0 6.0; 7.0 8.0 9.0]))
+end

In general, all functions defined for the ExponentialFamilyDistribution, such as getlogpartition or getbasemeasure accept an optional conditioner parameter, which is assumed to be nothing. Conditioned distribution implement the "conditioned" versions of such functions by explicitly requiring the conditioner parameter, e.g.

getsufficientstatistics(Laplace, 1.0) # explicit `conditioner = 1.0`
(ExponentialFamily.var"#340#341"{Float64}(1.0),)

Efficient packing of the natural parameters into a vectorized form

The ExponentialFamilyDistribution type stores its natural parameters in a vectorized, or packed, format. This is done for the sake of efficiency and to enhance compatibility with autodiff packages like ForwardDiff, which anticipate a single parameter vector. As a result, the tuple of natural parameters needs to be converted to its corresponding vectorized form and vice versa. To achieve this, the package provides the flatten_parameters, pack_parameters and unpack_parameters functions.

ExponentialFamily.flatten_parameters — Function
flatten_parameters(::Type{T}, params::Tuple)

This function returns the parameters of a distribution of type T in a flattened form without actually allocating the container.

source
ExponentialFamily.pack_parameters — Function
pack_parameters([ space ], ::Type{T}, params::Tuple)

This function returns the parameters of a distribution of type T in a vectorized (packed) form. For most of the distributions the packed versions are of the same structure in any parameters space. For some distributions, however, it is necessary to indicate the space of the packaged parameters.

julia> ExponentialFamily.pack_parameters((1, [2.0, 3.0], [4.0 5.0 6.0; 7.0 8.0 9.0]))
 9-element Vector{Float64}:
  1.0
  2.0
@@ -53,6 +53,6 @@
  5.0
  8.0
  6.0
- 9.0
source
ExponentialFamily.unpack_parameters — Function
unpack_parameters([ space ], ::Type{T}, parameters)

This function "unpack" the vectorized form of the parameters in a tuple. For most of the distributions the packed parameters are of the same structure in any parameters space. For some distributions, however, it is necessary to indicate the space of the packaged parameters.

See also: MeanParametersSpace, NaturalParametersSpace

source

These functions are not exported by default, but it's important to note that the ExponentialFamilyDistributions type doesn't actually store the parameter tuple internally. Instead, the getnaturalparameters function returns the corresponding vectorized (packed) form of the natural parameters. In general, only the ExponentialFamily.unpack_parameters function must be implemented, as others could be implemented in a generic way.

Attributes of the exponential family distribution based on Distribution

The ExponentialFamilyDistribution{T} where { T <: Distribution } type encompasses all fundamental attributes of the exponential family, including basemeasure, logpartition, sufficientstatistics, and fisherinformation. Furthermore, it's possible to retrieve the actual functions that compute these attributes. For instance, consider the following example:

basemeasure_of_bernoilli = getbasemeasure(Bernoulli)
+ 9.0
source
ExponentialFamily.unpack_parameters — Function
unpack_parameters([ space ], ::Type{T}, parameters)

This function "unpack" the vectorized form of the parameters in a tuple. For most of the distributions the packed parameters are of the same structure in any parameters space. For some distributions, however, it is necessary to indicate the space of the packaged parameters.

See also: MeanParametersSpace, NaturalParametersSpace

source

These functions are not exported by default, but it's important to note that the ExponentialFamilyDistributions type doesn't actually store the parameter tuple internally. Instead, the getnaturalparameters function returns the corresponding vectorized (packed) form of the natural parameters. In general, only the ExponentialFamily.unpack_parameters function must be implemented, as others could be implemented in a generic way.

Attributes of the exponential family distribution based on Distribution

The ExponentialFamilyDistribution{T} where { T <: Distribution } type encompasses all fundamental attributes of the exponential family, including basemeasure, logpartition, sufficientstatistics, and fisherinformation. Furthermore, it's possible to retrieve the actual functions that compute these attributes. For instance, consider the following example:

basemeasure_of_bernoilli = getbasemeasure(Bernoulli)
 
-basemeasure_of_bernoilli(0)
1
ExponentialFamily.isproper — Method
isproper([ space = NaturalParametersSpace() ], ::Type{T}, parameters, conditioner = nothing) where { T <: Distribution }

A specific verion of isproper defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. Optionally, accepts the space parameter, which defines the parameters space. For conditional exponential family distributions requires an extra conditioner argument.

See also: NaturalParametersSpace, MeanParametersSpace

source
ExponentialFamily.getbasemeasure — Method
getbasemeasure(::Type{<:Distribution}, [ conditioner ])

A specific verion of getbasemeasure defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. For conditional exponential family distributions requires an extra conditioner argument.

source
ExponentialFamily.getsufficientstatistics — Method
getsufficientstatistics(::Type{<:Distribution}, [ conditioner ])

A specific verion of getsufficientstatistics defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. For conditional exponential family distributions requires an extra conditioner argument.

source
ExponentialFamily.getlogpartition — Method
getlogpartition([ space = NaturalParametersSpace() ], ::Type{T}, [ conditioner ]) where { T <: Distribution }

A specific verion of getlogpartition defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. Optionally, accepts the space parameter, which defines the parameters space. For conditional exponential family distributions requires an extra conditioner argument.

See also: NaturalParametersSpace, MeanParametersSpace

source
ExponentialFamily.getfisherinformation — Method
getfisherinformation([ space = NaturalParametersSpace() ], ::Type{T}) where { T <: Distribution }

A specific verion of getfisherinformation defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. Optionally, accepts the space parameter, which defines the parameters space. For conditional exponential family distributions requires an extra conditioner argument.

See also: NaturalParametersSpace, MeanParametersSpace

source

Certain functions require knowledge about which parameter space is being used. By default, the NaturalParametersSpace is assumed.

getlogpartition(Bernoulli) === getlogpartition(NaturalParametersSpace(), Bernoulli)
true
ExponentialFamily.NaturalParametersSpace — Type
NaturalParametersSpace

Specifies the natural parameters space η as the desired parameters space. Some functions (such as logpartition or fisherinformation) accept an additional space parameter to disambiguate the desired parameters space. Use map(NaturalParametersSpace() => MeanParametersSpace(), T, parameters, conditioner) to map the parameters and the conditioner of a distribution of type T from the natural parametrization to the corresponding mean parametrization.

See also: MeanParametersSpace, getmapping, NaturalToMean, MeanToNatural

source
ExponentialFamily.MeanParametersSpace — Type
MeanParametersSpace

Specifies the mean parameters space θ as the desired parameters space. Some functions (such as logpartition or fisherinformation) accept an additional space parameter to disambiguate the desired parameters space. Use map(MeanParametersSpace() => NaturalParametersSpace(), T, parameters, conditioner) to map the parameters and the conditioner of a distribution of type T from the mean parametrization to the corresponding natural parametrization.

See also: NaturalParametersSpace, getmapping, NaturalToMean, MeanToNatural

source

The isbasemeasureconstant function is defined for all supported distributions as well.

isbasemeasureconstant(Bernoulli)
ConstantBaseMeasure()

Extra defined distributions

The package defines a list of extra distributions for a purpose of more efficiency in different circumstances. The list is available here.

+basemeasure_of_bernoilli(0)
1
ExponentialFamily.isproper — Method
isproper([ space = NaturalParametersSpace() ], ::Type{T}, parameters, conditioner = nothing) where { T <: Distribution }

A specific verion of isproper defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. Optionally, accepts the space parameter, which defines the parameters space. For conditional exponential family distributions requires an extra conditioner argument.

See also: NaturalParametersSpace, MeanParametersSpace

source
ExponentialFamily.getbasemeasure — Method
getbasemeasure(::Type{<:Distribution}, [ conditioner ])

A specific verion of getbasemeasure defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. For conditional exponential family distributions requires an extra conditioner argument.

source
ExponentialFamily.getsufficientstatistics — Method
getsufficientstatistics(::Type{<:Distribution}, [ conditioner ])

A specific verion of getsufficientstatistics defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. For conditional exponential family distributions requires an extra conditioner argument.

source
ExponentialFamily.getlogpartition — Method
getlogpartition([ space = NaturalParametersSpace() ], ::Type{T}, [ conditioner ]) where { T <: Distribution }

A specific verion of getlogpartition defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. Optionally, accepts the space parameter, which defines the parameters space. For conditional exponential family distributions requires an extra conditioner argument.

See also: NaturalParametersSpace, MeanParametersSpace

source
ExponentialFamily.getfisherinformation — Method
getfisherinformation([ space = NaturalParametersSpace() ], ::Type{T}) where { T <: Distribution }

A specific verion of getfisherinformation defined particularly for distribution types from Distributions.jl package. Does not require an instance of the ExponentialFamilyDistribution and can be called directly with a specific distribution type instead. Optionally, accepts the space parameter, which defines the parameters space. For conditional exponential family distributions requires an extra conditioner argument.

See also: NaturalParametersSpace, MeanParametersSpace

source

Certain functions require knowledge about which parameter space is being used. By default, the NaturalParametersSpace is assumed.

getlogpartition(Bernoulli) === getlogpartition(NaturalParametersSpace(), Bernoulli)
true
ExponentialFamily.NaturalParametersSpace — Type
NaturalParametersSpace

Specifies the natural parameters space η as the desired parameters space. Some functions (such as logpartition or fisherinformation) accept an additional space parameter to disambiguate the desired parameters space. Use map(NaturalParametersSpace() => MeanParametersSpace(), T, parameters, conditioner) to map the parameters and the conditioner of a distribution of type T from the natural parametrization to the corresponding mean parametrization.

See also: MeanParametersSpace, getmapping, NaturalToMean, MeanToNatural

source
ExponentialFamily.MeanParametersSpace — Type
MeanParametersSpace

Specifies the mean parameters space θ as the desired parameters space. Some functions (such as logpartition or fisherinformation) accept an additional space parameter to disambiguate the desired parameters space. Use map(MeanParametersSpace() => NaturalParametersSpace(), T, parameters, conditioner) to map the parameters and the conditioner of a distribution of type T from the mean parametrization to the corresponding natural parametrization.

See also: NaturalParametersSpace, getmapping, NaturalToMean, MeanToNatural

source

The isbasemeasureconstant function is defined for all supported distributions as well.

isbasemeasureconstant(Bernoulli)
ConstantBaseMeasure()

Extra defined distributions

The package defines a list of extra distributions for a purpose of more efficiency in different circumstances. The list is available here.

diff --git a/dev/library/index.html b/dev/library/index.html index 4c2ffb40..c886de95 100644 --- a/dev/library/index.html +++ b/dev/library/index.html @@ -1,2 +1,2 @@ -Library · ExponentialFamily.jl
GitHub

Library API

Additional distributions

These are the distributions that are not included in the Distributions.jl package.

ExponentialFamily.MatrixDirichlet — Type
MatrixDirichlet{T <: Real, A <: AbstractMatrix{T}} <: ContinuousMatrixDistribution

A matrix-valued MatrixDirichlet distribution, where T is the element type of the matrix A. The a field stores the matrix parameter of the distribution.

Fields

  • a::A: The matrix parameter of the MatrixDirichlet distribution.
source
ExponentialFamily.GammaShapeRate — Type
GammaShapeRate{T <: Real}

A univariate gamma distribution parametrized by its shape a and rate b.

Fields

  • a: The shape parameter of the gamma distribution. It should be a positive real number.
  • b: The rate parameter of the gamma distribution. It should be a positive real number.
source
ExponentialFamily.GammaShapeScale — Type
GammaShapeScale{T}

A continuous univariate gamma distribution parametrized by its shape α and scale β parameters.

Fields

  • α: The shape parameter of the gamma distribution. It should be a positive real number.
  • β: The scale parameter of the gamma distribution. It should be a positive real number.

Note

  • GammaShapeScale is an alias for Gamma from Distributions.jl.
source
ExponentialFamily.NormalMeanPrecision — Type
NormalMeanPrecision{T <: Real} <: ContinuousUnivariateDistribution

A normal distribution with a known mean μ and precision w.

Fields

  • μ::T: The mean of the normal distribution.
  • w::T: The precision of the normal distribution.
source
ExponentialFamily.NormalMeanVariance — Type
NormalMeanVariance{T <: Real} <: ContinuousUnivariateDistribution

A normal distribution with a known mean μ and variance v.

Fields

  • μ::T: The mean of the normal distribution.
  • v::T: The variance of the normal distribution.
source
ExponentialFamily.NormalWeightedMeanPrecision — Type
NormalWeightedMeanPrecision{T <: Real} <: ContinuousUnivariateDistribution

A normal distribution parametrized by its natural parameters: the weighted mean xi and precision w.

Fields

  • xi::T: The weighted mean of the normal distribution. xi is computed as w * μ, where μ is the mean of the distribution.
  • w::T: The precision (inverse variance) of the normal distribution.
source
ExponentialFamily.MvNormalMeanPrecision — Type
MvNormalMeanPrecision{T <: Real, M <: AbstractVector{T}, P <: AbstractMatrix{T}} <: AbstractMvNormal

A multivariate normal distribution with mean μ and precision matrix Λ, where T is the element type of the vectors M and matrices P.

Fields

  • μ::M: The mean vector of the multivariate normal distribution.
  • Λ::P: The precision matrix (inverse of the covariance matrix) of the multivariate normal distribution.
source
ExponentialFamily.MvNormalMeanCovariance — Type
MvNormalMeanCovariance{T <: Real, M <: AbstractVector{T}, P <: AbstractMatrix{T}} <: AbstractMvNormal

A multivariate normal distribution with mean μ and covariance matrix Σ, where T is the element type of the vectors M and matrices P.

Fields

  • μ::M: The mean vector of the multivariate normal distribution.
  • Σ::P: The covariance matrix of the multivariate normal distribution
source
ExponentialFamily.MvNormalWeightedMeanPrecision — Type
MvNormalWeightedMeanPrecision{T <: Real, M <: AbstractVector{T}, P <: AbstractMatrix{T}} <: AbstractMvNormal

A multivariate normal distribution with a weighted mean vector xi and precision matrix Λ, where T is the element type of the vectors M and matrices P. This struct represents a natural parametrization of a multivariate Gaussian distribution.

Fields

  • xi::M: The weighted mean vector of the multivariate normal distribution.
  • Λ::P: The precision matrix (inverse of the covariance matrix) of the multivariate normal distribution.
source
ExponentialFamily.JointNormal — Type
JointNormal{D, S}

JointNormal is an auxilary structure used for the joint marginal over Normally distributed variables. JointNormal stores a vector with the original dimensionalities (ds), so statistics can later be re-separated.

Use ExponentialFamily.getcomponent(joint, index) to get a specific component of the joint distribution.

Fields

  • dist: joint distribution (typically just a big MvNormal distribution, but maybe a tuple of individual means and covariance matrices)
  • ds: a tuple with the original dimensionalities of individual Normal distributions
  • ds[k] = (n,) where n is an integer indicates Multivariate normal of size n
  • ds[k] = () indicates Univariate normal
source
ExponentialFamily.WishartFast — Type
WishartFast{T <: Real, A <: AbstractMatrix{T}} <: ContinuousMatrixDistribution

The WishartFast struct represents a fast version of the Wishart distribution. It is similar to the Wishart distribution from Distributions.jl, but it does not check input arguments, allowing the creation of improper Wishart messages.

For model creation and regular usage, it is recommended to use Wishart from Distributions.jl. The WishartFast distribution is intended for internal purposes and should not be directly used by regular users.

Fields

  • ν::T: The degrees of freedom parameter of the Wishart distribution.
  • invS::A: The inverse scale matrix parameter of the Wishart distribution.

Note

Internally, WishartFast stores and creates the inverse of its scale matrix. However, the params() function returns the scale matrix itself for backward compatibility. This is done to ensure better stability in the message passing update rules for ReactiveMP.jl.

source
ExponentialFamily.InverseWishartFast — Type
InverseWishartFast{T <: Real, A <: AbstractMatrix{T}} <: ContinuousMatrixDistribution

The InverseWishartFast struct represents an improper Inverse Wishart distribution. It is similar to the InverseWishart distribution from Distributions.jl, but it does not check input arguments, allowing the creation of improper InverseWishart messages.

For model creation and regular usage, it is recommended to use InverseWishart from Distributions.jl. The InverseWishartFast distribution is intended for internal purposes and should not be directly used by regular users.

Fields

  • ν::T: The degrees of freedom parameter of the inverse Wishart distribution.
  • S::A: The scale matrix parameter of the inverse Wishart distribution.

Note

The InverseWishartFast distribution does not enforce input argument validation, making it suitable for specialized cases where improper message constructions are needed.

source
ExponentialFamily.NormalGamma — Type
NormalGamma{T <: Real} <: ContinuousMultivariateDistribution

A normal-gamma distribution, where T is a real number. This distribution is a joint distribution of a normal random variable with mean μ and precision λ, and a gamma-distributed random variable with shape α and rate β.

Fields

  • μ::T: The mean of the normal distribution.
  • λ::T: The precision of the normal distribution.
  • α::T: The shape parameter of the gamma distribution.
  • β::T: The rate parameter of the gamma distribution.
source
ExponentialFamily.MvNormalWishart — Type
MvNormalWishart{T, M <: AbstractArray{T}, V <: AbstractMatrix{T}, K <: Real, N <: Real} <: ContinuousMatrixDistribution

A multivariate normal-Wishart distribution, where T is the element type of the arrays M and matrices V, and K and N are real numbers. This distribution is a joint distribution of a multivariate normal random variable with mean μ and a Wishart-distributed random matrix with scale matrix Ψ, degrees of freedom ν, and the scalar κ as a scaling parameter.

Fields

  • μ::M: The mean vector of the multivariate normal distribution.
  • Ψ::V: The scale matrix of the Wishart distribution.
  • κ::K: The scaling parameter of the Wishart distribution.
  • ν::N: The degrees of freedom of the Wishart distribution
source
+Library · ExponentialFamily.jl
GitHub

Library API

Additional distributions

These are the distributions that are not included in the Distributions.jl package.

ExponentialFamily.MatrixDirichlet — Type
MatrixDirichlet{T <: Real, A <: AbstractMatrix{T}} <: ContinuousMatrixDistribution

A matrix-valued MatrixDirichlet distribution, where T is the element type of the matrix A. The a field stores the matrix parameter of the distribution.

Fields

  • a::A: The matrix parameter of the MatrixDirichlet distribution.
source
ExponentialFamily.GammaShapeRate — Type
GammaShapeRate{T <: Real}

A univariate gamma distribution parametrized by its shape a and rate b.

Fields

  • a: The shape parameter of the gamma distribution. It should be a positive real number.
  • b: The rate parameter of the gamma distribution. It should be a positive real number.
source
ExponentialFamily.GammaShapeScale — Type
GammaShapeScale{T}

A continuous univariate gamma distribution parametrized by its shape α and scale β parameters.

Fields

  • α: The shape parameter of the gamma distribution. It should be a positive real number.
  • β: The scale parameter of the gamma distribution. It should be a positive real number.

Note

  • GammaShapeScale is an alias for Gamma from Distributions.jl.
source
ExponentialFamily.NormalMeanPrecision — Type
NormalMeanPrecision{T <: Real} <: ContinuousUnivariateDistribution

A normal distribution with a known mean μ and precision w.

Fields

  • μ::T: The mean of the normal distribution.
  • w::T: The precision of the normal distribution.
source
ExponentialFamily.NormalMeanVariance — Type
NormalMeanVariance{T <: Real} <: ContinuousUnivariateDistribution

A normal distribution with a known mean μ and variance v.

Fields

  • μ::T: The mean of the normal distribution.
  • v::T: The variance of the normal distribution.
source
ExponentialFamily.NormalWeightedMeanPrecision — Type
NormalWeightedMeanPrecision{T <: Real} <: ContinuousUnivariateDistribution

A normal distribution parametrized by its natural parameters: the weighted mean xi and precision w.

Fields

  • xi::T: The weighted mean of the normal distribution. xi is computed as w * μ, where μ is the mean of the distribution.
  • w::T: The precision (inverse variance) of the normal distribution.
source
ExponentialFamily.MvNormalMeanPrecision — Type
MvNormalMeanPrecision{T <: Real, M <: AbstractVector{T}, P <: AbstractMatrix{T}} <: AbstractMvNormal

A multivariate normal distribution with mean μ and precision matrix Λ, where T is the element type of the vectors M and matrices P.

Fields

  • μ::M: The mean vector of the multivariate normal distribution.
  • Λ::P: The precision matrix (inverse of the covariance matrix) of the multivariate normal distribution.
source
ExponentialFamily.MvNormalMeanCovariance — Type
MvNormalMeanCovariance{T <: Real, M <: AbstractVector{T}, P <: AbstractMatrix{T}} <: AbstractMvNormal

A multivariate normal distribution with mean μ and covariance matrix Σ, where T is the element type of the vectors M and matrices P.

Fields

  • μ::M: The mean vector of the multivariate normal distribution.
  • Σ::P: The covariance matrix of the multivariate normal distribution
source
ExponentialFamily.MvNormalWeightedMeanPrecision — Type
MvNormalWeightedMeanPrecision{T <: Real, M <: AbstractVector{T}, P <: AbstractMatrix{T}} <: AbstractMvNormal

A multivariate normal distribution with a weighted mean vector xi and precision matrix Λ, where T is the element type of the vectors M and matrices P. This struct represents a natural parametrization of a multivariate Gaussian distribution.

Fields

  • xi::M: The weighted mean vector of the multivariate normal distribution.
  • Λ::P: The precision matrix (inverse of the covariance matrix) of the multivariate normal distribution.
source
ExponentialFamily.JointNormal — Type
JointNormal{D, S}

JointNormal is an auxilary structure used for the joint marginal over Normally distributed variables. JointNormal stores a vector with the original dimensionalities (ds), so statistics can later be re-separated.

Use ExponentialFamily.getcomponent(joint, index) to get a specific component of the joint distribution.

Fields

  • dist: joint distribution (typically just a big MvNormal distribution, but maybe a tuple of individual means and covariance matrices)
  • ds: a tuple with the original dimensionalities of individual Normal distributions
  • ds[k] = (n,) where n is an integer indicates Multivariate normal of size n
  • ds[k] = () indicates Univariate normal
source
ExponentialFamily.WishartFast — Type
WishartFast{T <: Real, A <: AbstractMatrix{T}} <: ContinuousMatrixDistribution

The WishartFast struct represents a fast version of the Wishart distribution. It is similar to the Wishart distribution from Distributions.jl, but it does not check input arguments, allowing the creation of improper Wishart messages.

For model creation and regular usage, it is recommended to use Wishart from Distributions.jl. The WishartFast distribution is intended for internal purposes and should not be directly used by regular users.

Fields

  • ν::T: The degrees of freedom parameter of the Wishart distribution.
  • invS::A: The inverse scale matrix parameter of the Wishart distribution.

Note

Internally, WishartFast stores and creates the inverse of its scale matrix. However, the params() function returns the scale matrix itself for backward compatibility. This is done to ensure better stability in the message passing update rules for ReactiveMP.jl.

source
ExponentialFamily.InverseWishartFast — Type
InverseWishartFast{T <: Real, A <: AbstractMatrix{T}} <: ContinuousMatrixDistribution

The InverseWishartFast struct represents an improper Inverse Wishart distribution. It is similar to the InverseWishart distribution from Distributions.jl, but it does not check input arguments, allowing the creation of improper InverseWishart messages.

For model creation and regular usage, it is recommended to use InverseWishart from Distributions.jl. The InverseWishartFast distribution is intended for internal purposes and should not be directly used by regular users.

Fields

  • ν::T: The degrees of freedom parameter of the inverse Wishart distribution.
  • S::A: The scale matrix parameter of the inverse Wishart distribution.

Note

The InverseWishartFast distribution does not enforce input argument validation, making it suitable for specialized cases where improper message constructions are needed.

source
ExponentialFamily.NormalGamma — Type
NormalGamma{T <: Real} <: ContinuousMultivariateDistribution

A normal-gamma distribution, where T is a real number. This distribution is a joint distribution of a normal random variable with mean μ and precision λ, and a gamma-distributed random variable with shape α and rate β.

Fields

  • μ::T: The mean of the normal distribution.
  • λ::T: The precision of the normal distribution.
  • α::T: The shape parameter of the gamma distribution.
  • β::T: The rate parameter of the gamma distribution.
source
ExponentialFamily.MvNormalWishart — Type
MvNormalWishart{T, M <: AbstractArray{T}, V <: AbstractMatrix{T}, K <: Real, N <: Real} <: ContinuousMatrixDistribution

A multivariate normal-Wishart distribution, where T is the element type of the arrays M and matrices V, and K and N are real numbers. This distribution is a joint distribution of a multivariate normal random variable with mean μ and a Wishart-distributed random matrix with scale matrix Ψ, degrees of freedom ν, and the scalar κ as a scaling parameter.

Fields

  • μ::M: The mean vector of the multivariate normal distribution.
  • Ψ::V: The scale matrix of the Wishart distribution.
  • κ::K: The scaling parameter of the Wishart distribution.
  • ν::N: The degrees of freedom of the Wishart distribution
source