Type Hierarchy

All samplers and distributions provided in this package are organized into a type hierarchy described as follows.

Sampleable

The root of this type hierarchy is Sampleable. The abstract type Sampleable subsumes any types of objects from which one can draw samples, which particularly includes samplers and distributions. Formally, Sampleable is defined as

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

It has two type parameters that define the kind of samples that can be drawn therefrom.

Distributions.Sampleable
Base.rand(::Distributions.Sampleable)

VariateForm

Distributions.VariateForm

The VariateForm subtypes defined in Distributions.jl are:

Type A single sample Multiple samples

Type	A single sample	Multiple samples
`Univariate == ArrayLikeVariate{0}`	a scalar number	A numeric array of arbitrary shape, each element being a sample
`Multivariate == ArrayLikeVariate{1}`	a numeric vector	A matrix, each column being a sample
`Matrixvariate == ArrayLikeVariate{2}`	a numeric matrix	An array of matrices, each element being a sample matrix

Univariate == ArrayLikeVariate{0}

a scalar number

A numeric array of arbitrary shape, each element being a sample

Multivariate == ArrayLikeVariate{1}

a numeric vector

A matrix, each column being a sample

Matrixvariate == ArrayLikeVariate{2}

a numeric matrix

An array of matrices, each element being a sample matrix

ValueSupport

# Distributions.ValueSupport — Type

ValueSupport

Abstract type that specifies the support of elements of samples.

It is either Discrete or Continuous.

The ValueSupport sub-types defined in Distributions.jl are:

# Distributions.Discrete — Type

Discrete <: ValueSupport

This type represents the support of a discrete random variable.

It is countable. For instance, it can be a finite set or a countably infinite set such as the natural numbers.

See also: Discrete, ValueSupport

Type Default element type Description Examples

Type	Default element type	Description	Examples
`Discrete`	`Int`	Samples take countably many values	,
`Continuous`	`Float64`	Samples take uncountably many values	],

Discrete

Int

Samples take countably many values

Continuous

Float64

Samples take uncountably many values

Multiple samples are often organized into an array, depending on the variate form.

The basic functionalities that a sampleable object provides are to retrieve information about the samples it generates and to draw samples. Particularly, the following functions are provided for sampleable objects:

# Base.length — Method

length(s::Sampleable)

The length of each sample. Always returns 1 when s is univariate.

# Base.size — Method

size(s::Sampleable)

The size (i.e. shape) of each sample. Always returns () when s is univariate, and (length(s),) when s is multivariate.

# Distributions.nsamples — Method

nsamples(s::Sampleable)

The number of values contained in one sample of s. Multiple samples are often organized into an array, depending on the variate form.

# Base.eltype — Method

eltype(::Type{Sampleable})

The default element type of a sample. This is the type of elements of the samples generated by the rand method. However, one can provide an array of different element types to store the samples using rand!.

# Base.rand — Method

rand(::AbstractRNG, ::Sampleable)

Samples from the sampler and returns the result.

# Random.rand! — Method

rand!(::AbstractRNG, ::Sampleable, ::AbstractArray)

Samples in-place from the sampler and stores the result in the provided array.

Distributions

We use Distribution, a subtype of Sampleable as defined below, to capture probabilistic distributions. In addition to being sampleable, a distribution typically comes with an explicit way to combine its domain, probability density function, and many other quantities.

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

Distributions.Distribution

To simplify the use in practice, we introduce a series of type alias as follows:

const UnivariateDistribution{S<:ValueSupport}   = Distribution{Univariate,S}
const MultivariateDistribution{S<:ValueSupport} = Distribution{Multivariate,S}
const MatrixDistribution{S<:ValueSupport}       = Distribution{Matrixvariate,S}
const NonMatrixDistribution = Union{UnivariateDistribution, MultivariateDistribution}

const DiscreteDistribution{F<:VariateForm}   = Distribution{F,Discrete}
const ContinuousDistribution{F<:VariateForm} = Distribution{F,Continuous}

const DiscreteUnivariateDistribution     = Distribution{Univariate,    Discrete}
const ContinuousUnivariateDistribution   = Distribution{Univariate,    Continuous}
const DiscreteMultivariateDistribution   = Distribution{Multivariate,  Discrete}
const ContinuousMultivariateDistribution = Distribution{Multivariate,  Continuous}
const DiscreteMatrixDistribution         = Distribution{Matrixvariate, Discrete}
const ContinuousMatrixDistribution       = Distribution{Matrixvariate, Continuous}

All methods applicable to Sampleable also apply to Distribution. The API for distributions of different variate forms are different (refer to univariates, multivariates, and matrix for details).