Probability Distributions

val::T = random(dist::Distribution{T}, args...)

Sample a random choice from the given distribution with the given arguments.

lpdf = logpdf(dist::Distribution{T}, value::T, args...)

Evaluate the log probability (density) of the value.

has::Bool = has_output_grad(dist::Distribution)

Return true of the gradient if the distribution computes the gradient of the logpdf with respect to the value of the random choice.

grads::Tuple = logpdf_grad(dist::Distribution{T}, value::T, args...)

Compute the gradient of the logpdf with respect to the value, and each of the arguments.

If has_output_grad returns false, then the first element of the returned tuple is nothing. Otherwise, the first element of the tuple is the gradient with respect to the value. If the return value of has_argument_grads has a false value for at position i, then the i+1th element of the returned tuple has value nothing. Otherwise, this element contains the gradient with respect to the ith argument.

bernoulli(prob_true::Real)

Samples a Bool value which is true with given probability

beta(alpha::Real, beta::Real)

Sample a Float64 from a beta distribution.

beta_uniform(theta::Real, alpha::Real, beta::Real)

Samples a Float64 value from a mixture of a uniform distribution on [0, 1] with probability 1-theta and a beta distribution with parameters alpha and beta with probability theta.

binom(n::Integer, p::Real)

Sample an Int from the Binomial distribution with parameters n (number of trials) and p (probability of success in each trial).

categorical(probs::AbstractArray{U, 1}) where {U <: Real}

Given a vector of probabilities probs where sum(probs) = 1, sample an Int i from the set {1, 2, .., length(probs)} with probability probs[i].

cauchy(x0::Real, gamma::Real)

Sample a Float64 value from a Cauchy distribution with location x0 and scale gamma.

dirichlet(alpha::Vector{Float64})

Sample a simplex Vector{Float64} from a Dirichlet distribution.

exponential(rate::Real)

Sample a Float64 from the exponential distribution with rate parameter rate.

gamma(shape::Real, scale::Real)

Sample a Float64 from a gamma distribution.

geometric(p::Real)

Sample an Int from the Geometric distribution with parameter p.

inv_gamma(shape::Real, scale::Real)

Sample a Float64 from a inverse gamma distribution.

laplace(loc::Real, scale::Real)

Sample a Float64 from a laplace distribution.

mvnormal(mu::AbstractVector{T}, cov::AbstractMatrix{U}} where {T<:Real,U<:Real}

Samples a Vector{Float64} value from a multivariate normal distribution.

neg_binom(r::Real, p::Real)

Sample an Int from a Negative Binomial distribution. Returns the number of failures before the rth success in a sequence of independent Bernoulli trials. r is the number of successes (which may be fractional) and p is the probability of success per trial.

normal(mu::Real, std::Real)

Samples a Float64 value from a normal distribution.

piecewise_uniform(bounds, probs)

Samples a Float64 value from a piecewise uniform continuous distribution.

There are n bins where n = length(probs) and n + 1 = length(bounds). Bounds must satisfy bounds[i] < bounds[i+1] for all i. The probability density at x is zero if x <= bounds[1] or x >= bounds[end] and is otherwise probs[bin] / (bounds[bin] - bounds[bin+1]) where bounds[bin] < x <= bounds[bin+1].

poisson(lambda::Real)

Sample an Int from the Poisson distribution with rate lambda.

uniform(low::Real, high::Real)

Sample a Float64 from the uniform distribution on the interval [low, high].

uniform_discrete(low::Integer, high::Integer)

Sample an Int from the uniform distribution on the set {low, low + 1, ..., high-1, high}.

broadcasted_normal(mu::AbstractArray{<:Real, N1},
                   std::AbstractArray{<:Real, N2}) where {N1, N2}

Samples an Array{Float64, max(N1, N2)} of shape Broadcast.broadcast_shapes(size(mu), size(std)) where each element is independently normally distributed. This is equivalent to (a reshape of) a multivariate normal with diagonal covariance matrix, but its implementation is more efficient than that of the more general mvnormal for this case.

The shapes of mu and std must be broadcast-compatible.

If all args are 0-dimensional arrays, then sampling via broadcasted_normal(...) returns a Float64 rather than properly returning an Array{Float64, 0}. This is consistent with Julia's own inconsistency on the matter:

julia> typeof(ones())
Array{Float64,0}

julia> typeof(ones() .* ones())
Float64

HomogeneousMixture(distribution::Distribution, dims::Vector{Int})

Define a new distribution that is a mixture of some number of instances of single base distributions.

The first argument defines the base distribution of each component in the mixture.

The second argument must have length equal to the number of arguments taken by the base distribution. A value of 0 at a position in the vector an indicates that the corresponding argument to the base distribution is a scalar, and integer values of i for i >= 1 indicate that the corresponding argument is an i-dimensional array.

Example:

mixture_of_normals = HomogeneousMixture(normal, [0, 0])

The resulting distribution (e.g. mixture_of_normals above) can then be used like the built-in distribution values like normal. The distribution takes n+1 arguments where n is the number of arguments taken by the base distribution. The first argument to the distribution is a vector of non-negative mixture weights, which must sum to 1.0. The remaining arguments to the distribution correspond to the arguments of the base distribution, but have a different type: If an argument to the base distribution is a scalar of type T, then the corresponding argument to the mixture distribution is a Vector{T}, where each element of this vector is the argument to the corresponding mixture component. If an argument to the base distribution is an Array{T,N} for some N, then the corresponding argument to the mixture distribution is of the form arr::Array{T,N+1}, where each slice of the array of the form arr[:,:,...,i] is the argument for the ith mixture component.

Example:

mixture_of_normals = HomogeneousMixture(normal, [0, 0])
mixture_of_mvnormals = HomogeneousMixture(mvnormal, [1, 2])

@gen function foo()
    # mixture of two normal distributions
    # with means -1.0 and 1.0
    # and standard deviations 0.1 and 10.0
    # the first normal distribution has weight 0.4; the second has weight 0.6
    x ~ mixture_of_normals([0.4, 0.6], [-1.0, 1.0], [0.1, 10.0])

    # mixture of two multivariate normal distributions
    # with means: [0.0, 0.0] and [1.0, 1.0]
    # and covariance matrices: [1.0 0.0; 0.0 1.0] and [10.0 0.0; 0.0 10.0]
    # the first multivariate normal distribution has weight 0.4;
    # the second has weight 0.6
    means = [0.0 1.0; 0.0 1.0] # or, cat([0.0, 0.0], [1.0, 1.0], dims=2)
    covs = cat([1.0 0.0; 0.0 1.0], [10.0 0.0; 0.0 10.0], dims=3)
    y ~ mixture_of_mvnormals([0.4, 0.6], means, covs)
end

HeterogeneousMixture(distributions::Vector{Distribution{T}}) where {T}

Define a new distribution that is a mixture of a given list of base distributions.

The argument is the vector of base distributions, one for each mixture component.

Note that the base distributions must have the same output type.

Example:

uniform_beta_mixture = HeterogeneousMixture([uniform, beta])

The resulting mixture distribution takes n+1 arguments, where n is the sum of the number of arguments taken by each distribution in the list. The first argument to the mixture distribution is a vector of non-negative mixture weights, which must sum to 1.0. The remaining arguments are the arguments to each mixture component distribution, in order in which the distributions are passed into the constructor.

Example:

@gen function foo()
    # mixure of a uniform distribution on the interval [`lower`, `upper`]
    # and a beta distribution with alpha parameter `a` and beta parameter `b`
    # the uniform as weight 0.4 and the beta has weight 0.6
    x ~ uniform_beta_mixture([0.4, 0.6], lower, upper, a, b)
end

ProductDistribution(distributions::Vararg{<:Distribution})

Define new distribution that is the product of the given nonempty list of distributions having a common type.

The arguments comprise the list of base distributions.

Example:

normal_strip = ProductDistribution(uniform, normal)

The resulting product distribution takes n arguments, where n is the sum of the numbers of arguments taken by each distribution in the list. These arguments are the arguments to each component distribution, in the order in which the distributions are passed to the constructor.

Example:

@gen function unit_strip_and_near_seven()
    x ~ flip_and_number(0.0, 0.1, 7.0, 0.01)
end