docs: add documentation

README.md

@@ -7,10 +7,11 @@
 [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
 [![PkgEval](https://JuliaCI.github.io/NanosoldierReports/pkgeval_badges/B/BayesBase.svg)](https://JuliaCI.github.io/NanosoldierReports/pkgeval_badges/B/BayesBase.html)
 
-`BayesBase` is a package that serves as an umbrella, defining, exporting, and re-exporting methods essential for Bayesian statistics. 
+`BayesBase` is a package that serves as an umbrella, defining, exporting, and re-exporting methods essential for Bayesian statistics specifically for the [`RxInfer` ecosystem](https://github.com/biaslab/RxInfer.jl). 
 
 Related projects:
 
+- [`RxInfer`](https://github.com/biaslab/RxInfer.jl)
 - [`ExponentialFamily`](https://github.com/biaslab/ExponentialFamily.jl)
 
 

docs/src/index.md

@@ -2,20 +2,110 @@
 CurrentModule = BayesBase
 ```
 
-# BayesBase
+# BayesBase.jl
 
-Documentation for [BayesBase](https://github.com/biaslab/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](https://github.com/biaslab/RxInfer.jl). 
+
+Related projects:
+
+- [`RxInfer`](https://github.com/biaslab/RxInfer.jl)
+- [`ExponentialFamily`](https://github.com/biaslab/ExponentialFamily.jl)
+
+# Index
 
 ```@index
 ```
 
-# List of exported functions
+# [Library API](@id library)
+
+## [Generic densities](@id library-densities)
 
 ```@docs
-StatsAPI.params
-Statistics.mean
+BayesBase.PointMass
+BayesBase.ContinuousUnivariateLogPdf
+BayesBase.ContinuousMultivariateLogPdf
+BayesBase.SampleList
+BayesBase.FactorizedJoint
+BayesBase.MixtureDistribution
 ```
 
-```@autodocs
-Modules = [BayesBase]
+## [Product API](@id library-prod)
+
+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.
+
+```@docs
+prod(::UnspecifiedProd, left, right)
+BayesBase.default_prod_rule
+```
+
+### [Product strategies](@id library-prod-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.
+
+```@docs
+BayesBase.UnspecifiedProd
+BayesBase.ClosedProd
+BayesBase.PreserveTypeProd
+BayesBase.PreserveTypeLeftProd
+BayesBase.PreserveTypeRightProd
+BayesBase.GenericProd
+BayesBase.ProductOf
+BayesBase.LinearizedProductOf
+```
+
+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](@id library-promotion-utilities)
+
+```@docs
+BayesBase.deep_eltype
+BayesBase.isequal_typeof
+BayesBase.paramfloattype
+BayesBase.sampletype
+BayesBase.samplefloattype
+BayesBase.promote_variate_type
+BayesBase.promote_paramfloattype
+BayesBase.promote_sampletype
+BayesBase.promote_samplefloattype
+BayesBase.convert_paramfloattype
+```
+
+## [Extra stats functions](@id library-statsfuns)
+
+```@docs
+BayesBase.mirrorlog
+BayesBase.xtlog
+BayesBase.logmvbeta
+BayesBase.clamplog
+BayesBase.mvtrigamma
+BayesBase.probvec
+BayesBase.mean_std
+BayesBase.mean_var
+BayesBase.mean_cov
+BayesBase.mean_invcov
+BayesBase.mean_precision
+BayesBase.weightedmean
+BayesBase.weightedmean_std
+BayesBase.weightedmean_var
+BayesBase.weightedmean_cov
+BayesBase.weightedmean_invcov
+```
+
+## [Helper utilities](@id library-helpers)
+
+```@docs
+BayesBase.vague
+BayesBase.logpdf_sampling_optimized
+BayesBase.logpdf_optimized
+BayesBase.sampling_optimized
+BayesBase.fuse_supports
+BayesBase.UnspecifiedDomain
+BayesBase.UnspecifiedDimension
+BayesBase.Infinity
+BayesBase.MinusInfinity
+BayesBase.distribution_typewrapper
 ```

src/densities/factorizedjoint.jl

@@ -1,7 +1,7 @@
 export FactorizedJoint
 
 """
-    FactorizedJoint
+    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.

src/densities/mixture.jl

@@ -4,7 +4,7 @@ using LinearAlgebra
 export MixtureDistribution
 
 """
-    `MixtureDistribution{C,CT<:Real}`
+    MixtureDistribution(components, weights)
 
 A custom mixture distribution implementation, parameterized by:
 * `C` type family of the mixture

src/densities/pointmass.jl

@@ -3,6 +3,13 @@ using SpecialFunctions: loggamma, logbeta
 
 export PointMass
 
+"""
+    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`.
+"""
 struct PointMass{P}
     point::P
 end

src/prod.jl

@@ -26,32 +26,6 @@ struct UnspecifiedProd end
 `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`.
 
-# Examples:
-
-```jldoctest
-julia> product = prod(PreserveTypeProd(Distribution), NormalMeanVariance(-1.0, 1.0), NormalMeanVariance(1.0, 1.0))
-NormalWeightedMeanPrecision{Float64}(xi=0.0, w=2.0)
-
-julia> mean(product), var(product)
-(0.0, 0.5)
-```
-
-```jldoctest
-julia> product = prod(PreserveTypeProd(NormalMeanVariance), NormalMeanVariance(-1.0, 1.0), NormalMeanVariance(1.0, 1.0))
-NormalMeanVariance{Float64}(μ=0.0, v=0.5)
-
-julia> mean(product), var(product)
-(0.0, 0.5)
-```
-
-```jldoctest
-julia> product = prod(PreserveTypeProd(ExponentialFamilyDistribution), NormalMeanVariance(-1.0, 1.0), NormalMeanVariance(1.0, 1.0))
-ExponentialFamily(NormalMeanVariance)
-
-julia> mean(product), var(product)
-(0.0, 0.5)
-```
-
 See also: [`default_prod_rule`](@ref), [`ClosedProd`](@ref), [`PreserveTypeProd`](@ref), [`GenericProd`](@ref)
 """
 function Base.prod(strategy::UnspecifiedProd, left, right)
@@ -91,14 +65,6 @@ end
 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.
 
-```jldoctest
-julia> product = prod(PreserveTypeProd(NormalMeanVariance), NormalMeanVariance(-1.0, 1.0), NormalMeanVariance(1.0, 1.0))
-NormalMeanVariance{Float64}(μ=0.0, v=0.5)
-
-julia> mean(product), var(product)
-(0.0, 0.5)
-```
-
 See also: [`prod`](@ref), [`ClosedProd`](@ref), [`PreserveTypeLeftProd`](@ref), [`PreserveTypeRightProd`](@ref), [`GenericProd`](@ref)
 """
 struct PreserveTypeProd{T} end
@@ -118,14 +84,6 @@ Base.prod(::PreserveTypeProd, ::Missing, ::Missing) = missing
 
 An alias for the `PreserveTypeProd(L)` where `L` is the type of the `left` argument of the `prod` function.
 
-```jldoctest
-julia> product = prod(PreserveTypeLeftProd(), NormalMeanVariance(-1.0, 1.0), NormalMeanPrecision(1.0, 1.0))
-NormalMeanVariance{Float64}(μ=0.0, v=0.5)
-
-julia> mean(product), var(product)
-(0.0, 0.5)
-```
-
 See also: [`prod`](@ref), [`PreserveTypeProd`](@ref), [`PreserveTypeRightProd`](@ref), [`GenericProd`](@ref)
 """
 struct PreserveTypeLeftProd end
@@ -139,14 +97,6 @@ end
 
 An alias for the `PreserveTypeProd(R)` where `R` is the type of the `right` argument of the `prod` function.    
 
-```jldoctest
-julia> product = prod(PreserveTypeRightProd(), NormalMeanVariance(-1.0, 1.0), NormalMeanPrecision(1.0, 1.0))
-NormalMeanPrecision{Float64}(μ=0.0, w=2.0)
-
-julia> mean(product), var(product)
-(0.0, 0.5)
-```
-
 See also: [`prod`](@ref), [`PreserveTypeProd`](@ref), [`PreserveTypeLeftProd`](@ref), [`GenericProd`](@ref)
 """
 struct PreserveTypeRightProd end
@@ -208,7 +158,7 @@ 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`](@ref), [`GenericProd`](@ref), [`ExponentialFamily.fuse_supports`](@ref)
+See also: [`prod`](@ref), [`GenericProd`](@ref), [`fuse_supports`](@ref)
 """
 struct ProductOf{L,R}
     left::L

src/promotion.jl

@@ -66,7 +66,7 @@ end
 
 Returns the underlying float type of distribution's parameters.
 
-See also: [`ExponentialFamily.promote_paramfloattype`](@ref), [`ExponentialFamily.convert_paramfloattype`](@ref)
+See also: [`promote_paramfloattype`](@ref), [`convert_paramfloattype`](@ref)
 """
 function paramfloattype(distribution::Distribution)
     return promote_type(map(deep_eltype, params(distribution))...)
@@ -82,7 +82,7 @@ paramfloattype(::Nothing) = Bool
 
 Promotes `paramfloattype` of the `distributions` to a single type. See also `promote_type`.
 
-See also: [`ExponentialFamily.paramfloattype`](@ref), [`ExponentialFamily.convert_paramfloattype`](@ref)
+See also: [`paramfloattype`](@ref), [`convert_paramfloattype`](@ref)
 """
 function promote_paramfloattype(distributions...)
     return promote_type(map(paramfloattype, distributions)...)
@@ -93,7 +93,7 @@ end
 
 Converts (if possible) the params float type of the `distribution` to be of type `T`.
 
-See also: [`ExponentialFamily.paramfloattype`](@ref), [`ExponentialFamily.promote_paramfloattype`](@ref)
+See also: [`paramfloattype`](@ref), [`promote_paramfloattype`](@ref)
 """
 function convert_paramfloattype(::Type{T}, distribution::Distribution) where {T}
     return automatic_convert_paramfloattype(
@@ -137,7 +137,7 @@ convert_paramfloattype(::Type, ::Nothing) = nothing
 
 Returns a type of the distribution. By default fallbacks to the `eltype`.
 
-See also: [`ExponentialFamily.samplefloattype`](@ref), [`ExponentialFamily.promote_sampletype`](@ref), [`ExponentialFamily.promote_samplefloattype`](@ref)
+See also: [`samplefloattype`](@ref), [`promote_sampletype`](@ref), [`promote_samplefloattype`](@ref)
 """
 sampletype(distribution) = eltype(distribution)
 
@@ -154,7 +154,7 @@ sampletype(::Type{Matrixvariate}, distribution) = Matrix{eltype(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: [`ExponentialFamily.sampletype`](@ref), [`ExponentialFamily.promote_sampletype`](@ref), [`ExponentialFamily.promote_samplefloattype`](@ref)
+See also: [`sampletype`](@ref), [`promote_sampletype`](@ref), [`promote_samplefloattype`](@ref)
 """
 samplefloattype(distribution) = deep_eltype(sampletype(distribution))
 
@@ -163,7 +163,7 @@ samplefloattype(distribution) = deep_eltype(sampletype(distribution))
 
 Promotes `sampletype` of the `distributions` to a single type. See also `promote_type`.
 
-See also: [`ExponentialFamily.sampletype`](@ref), [`ExponentialFamily.samplefloattype`](@ref), [`ExponentialFamily.promote_samplefloattype`](@ref)
+See also: [`sampletype`](@ref), [`samplefloattype`](@ref), [`promote_samplefloattype`](@ref)
 """
 promote_sampletype(distributions...) = promote_type(map(sampletype, distributions)...)
 
@@ -172,7 +172,7 @@ promote_sampletype(distributions...) = promote_type(map(sampletype, distribution
 
 Promotes `samplefloattype` of the `distributions` to a single type. See also `promote_type`.
 
-See also: [`ExponentialFamily.sampletype`](@ref), [`ExponentialFamily.samplefloattype`](@ref), [`ExponentialFamily.promote_sampletype`](@ref)
+See also: [`sampletype`](@ref), [`samplefloattype`](@ref), [`promote_sampletype`](@ref)
 """
 function promote_samplefloattype(distributions...)
     return promote_type(map(samplefloattype, distributions)...)