Distributions.jl

The Distributions.jl package provides a comprehensive collection of probabilistic distributions and statistical functions for Julia. It is designed to handle common tasks in probabilistic modeling and statistical analysis, including:

• Sampling: Generating random samples from various distributions.
• Statistical Properties: Calculating moments (mean, variance, skewness, kurtosis), entropy, and other properties.
• Probability Functions: Computing probability density/mass functions (pdf) and their logarithms (logpdf).
• Generating Functions: Working with moment-generating and characteristic functions.
• Estimation: Performing Maximum Likelihood Estimation (MLE).
• Distribution Composition: Creating complex distributions via Cartesian products, truncation, or censoring.

Distributions.jl is a Julia package for probability distributions and associated statistical functions. It provides a unified interface for:

• Moments: Calculating properties like mean, variance, skewness, and kurtosis.
• Entropy: Computing entropy and other statistical properties.
• Probability Functions: Accessing probability density/mass functions (pdf) and their logarithms (logpdf).
• Generating Functions: Working with moment generating functions and characteristic functions.
• Sampling: Drawing samples from a population or directly from a distribution.
• Estimation: Performing Maximum Likelihood Estimation (MLE).

Note: Functionalities related to conjugate priors are no longer in this package and have been moved to the ConjugatePriors.jl package.

In Distributions.jl, univariate distributions are distributions where each sample is a scalar (Univariate).

There are two primary abstract types for univariate distributions:

• DiscreteUnivariateDistribution: Distributions with discrete outcomes.
• ContinuousUnivariateDistribution: Distributions with continuous outcomes.

All univariate distributions follow the UnivariateDistribution{S<:ValueSupport} structure.

The Distributions.jl package provides support for the DensityInterface.jl ecosystem. This allows you to use standard DensityInterface functions on any distribution object.

For any distribution d and single variate value x:

• DensityInterface.densityof(d, x) is equivalent to pdf(d, x).
• DensityInterface.logdensityof(d, x) is equivalent to logpdf(d, x).

All distributions in this package are recognized by DensityInterface as having a density via the check: DensityInterface.DensityKind(::Distribution) === HasDensity().

using Distributions
using DensityInterface

d = Normal(0, 1)
x = 0.5

# These are equivalent
density = densityof(d, x) # same as pdf(d, x)
log_density = logdensityof(d, x) # same as logpdf(d, x)

The core of Distributions.jl is the Sampleable abstract type. It represents any object from which samples can be drawn, including both samplers and distributions.

Sampleable is parameterized by two types:

1. VariateForm: Defines the shape of the samples (e.g., scalar, vector, or matrix).
2. ValueSupport: Defines the nature of the values (e.g., discrete or continuous).

All functions applicable to Sampleable are also applicable to Distribution objects.

abstract type Sampleable{F<:VariateForm,S<:ValueSupport} end

Matrix-variate distributions are distributions where each sample is a matrix (represented by the Matrixvariate type). In Distributions.jl, these are categorized under the abstract type MatrixDistribution{S<:ValueSupport}.

There are two primary sub-types:

• DiscreteMatrixDistribution: For discrete matrix-valued distributions.
• ContinuousMatrixDistribution: For continuous matrix-valued distributions.

For advanced random matrix functionalities, consider using the RandomMatrices.jl package.

For many distributions, estimation can be performed using sufficient statistics rather than the raw dataset. This is useful for efficiency or when working with pre-aggregated data.

1. Compute sufficient statistics using suffstats(D, x) or suffstats(D, x, w) for weighted data.
2. Pass those statistics to fit_mle(D, ss) to obtain the fitted distribution.

Note: When calling fit_mle(D, x) directly, the package often internally calls suffstats as a fallback unless a more efficient specialized implementation exists.

# 1. Capture sufficient statistics
ss = suffstats(Normal, x)

# 2. Estimate distribution from statistics
d = fit_mle(Normal, ss)

Functions to compute descriptive statistics such as mean, mode, var, std, and entropy are not available for generic truncated distributions because these quantities are often difficult to compute due to truncation complications.

Exception: These methods are supported specifically for truncated normal distributions, which can be constructed using truncated(::Normal, ...). For these distributions, Truncated{<:Normal} will support standard statistical methods.

The package supports three main categories of distributions, each of which can be Discrete or Continuous:

1. Univariate (ArrayLikeVariate{0}): e.g., Binomial(n, p) (Discrete) or Cauchy(u, b) (Continuous).
2. Multivariate (ArrayLikeVariate{1}): e.g., Multinomial(n, p).
3. Matrixvariate (ArrayLikeVariate{2}): e.g., Wishart(nu, S).

You can also create truncated distributions from existing univariate distributions using the truncated(dist, l, u) function, where l and u are the lower and upper bounds.

# Example of different types
b = Binomial(n, p)
c = Cauchy(u, b)
m = Multinomial(n, p)
w = Wishart(nu, S)

# Truncated distribution
t = truncated(Normal(0, 1), -1, 1)