Skip to content

Theoretical distributions

It is common in the scientific literature to encounter uncertain data values which are reported as following a specific distribution. For example, an author report the mean and standard deviation of a value stated to follow a normal distribution. UncertainData makes it easy to represent such values!

Supported distributions

Supported distributions are Uniform, Normal, Gamma, Beta, BetaPrime, Frechet, Binomial, BetaBinomial (more distributions will be added in the future!).

Examples

1
2
# Uncertain value generated by a uniform distribution on [-5.0, 5.1].
uv = UncertainValue(Uniform, -5.0, 5.1)

1
2
3
# Uncertain value generated by a normal distribution with parameters μ = -2 and
# σ = 0.5.
uv = UncertainValue(Normal, -2, 0.5)

1
2
3
# Uncertain value generated by a gamma distribution with parameters α = 2.2
# and θ = 3.
uv = UncertainValue(Gamma, 2.2, 3)

1
2
3
# Uncertain value generated by a beta distribution with parameters α = 1.5
# and β = 3.5
uv = UncertainValue(Beta, 1.5, 3.5)

1
2
3
# Uncertain value generated by a beta prime distribution with parameters α = 1.7
# and β = 3.2
uv = UncertainValue(Beta, 1.7, 3.2)

1
2
3
# Uncertain value generated by a Fréchet distribution with parameters α = 2.1
# and θ = 4
uv = UncertainValue(Beta, 2.1, 4)

1
2
3
# Uncertain value generated by binomial distribution with n = 28 trials and
# probability p = 0.2 of success in individual trials.
uv = UncertainValue(Binomial, 28, 0.2)

1
2
3
# Creates an uncertain value generated by a beta-binomial distribution with
# n = 28 trials, and parameters α = 1.5 and β = 3.5.
uv = UncertainValue(BetaBinomial, 28, 3.3, 4.4)

Constructors

There are two constructors that creates uncertain values represented by theoretical distributions. Parameters are provided to the constructor in the same order as for constructing the equivalent distributions in Distributions.jl.

Uncertain values represented by theoretical distributions may be constructed using the two-parameter or three-parameter constructors UncertainValue(d::Type{D}, a<:Number, b<:Number) or UncertainValue(d::Type{D}, a<:Number, b<:Number, c<:Number) (see below).

Two-parameter distributions

# UncertainData.UncertainValues.UncertainValue — Method.

1
2
UncertainValue(distribution::Type{D}, a::T1, b::T2;
    kwargs...) where {T1<:Number, T2 <: Number, D<:Distribution}

Constructor for two-parameter distributions

UncertainValues are currently implemented for the following two-parameter distributions: Uniform, Normal, Binomial, Beta, BetaPrime, Gamma, and Frechet.

Arguments

  • a, b: Generic parameters whose meaning varies depending on what distribution is provided. See the list below.
  • distribution: A valid univariate distribution from Distributions.jl.

Precisely what a and b are depends on which distribution is provided.

  • UncertainValue(Normal, μ, σ) returns an UncertainScalarNormallyDistributed instance.
  • UncertainValue(Uniform, lower, upper) returns an UncertainScalarUniformlyDistributed instance.
  • UncertainValue(Beta, α, β) returns an UncertainScalarBetaDistributed instance.
  • UncertainValue(BetaPrime, α, β) returns an UncertainScalarBetaPrimeDistributed instance.
  • UncertainValue(Gamma, α, θ) returns an UncertainScalarGammaDistributed instance.
  • UncertainValue(Frechet, α, θ) returns an UncertainScalarFrechetDistributed instance.
  • UncertainValue(Binomial, n, p) returns an UncertainScalarBinomialDistributed instance.

Keyword arguments

  • nσ: If distribution <: Distributions.Normal, then how many standard deviations away from μ does lower and upper (i.e. both, because they are the same distance away from μ) represent?
  • tolerance: A threshold determining how symmetric the uncertainties must be in order to allow the construction of Normal distribution (upper - lower > threshold is required).
  • trunc_lower: Lower truncation bound for distributions with infinite support. Defaults to -Inf.
  • trunc_upper: Upper truncation bound for distributions with infinite support. Defaults to Inf.

Examples

Normal distribution

Normal distributions are formed by using the constructor UncertainValue(μ, σ, Normal; kwargs...). This gives a normal distribution with mean μ and standard deviation σ/nσ (nσ must be given as a keyword argument).

1
2
3
4
5
6
7
8
9
# A normal distribution with mean = 2.3 and standard deviation 0.3.
UncertainValue(2.3, 0.3, Normal)

# A normal distribution with mean 2.3 and standard deviation 0.3/2.
UncertainValue(2.3, 0.3, Normal, nσ = 2)

# A normal distribution with mean 2.3 and standard deviation = 0.3,
truncated to the interval `[1, 3]`.
UncertainValue(2.3, 0.3, Normal, trunc_lower = 1.0, trunc_upper = 3.0)

Uniform distribution

Uniform distributions are formed using the UncertainValue(lower, upper, Uniform) constructor.

1
2
#  A uniform distribution on `[2, 3]`
UncertainValue(-2, 3, Uniform)

source

Three-parameter distributions

# UncertainData.UncertainValues.UncertainValue — Method.

1
2
UncertainValue(distribution::Type{D}, a::T1, b::T2, c::T3;
    kwargs...) where {T1<:Number, T2<:Number, T3<:Number, D<:Distribution}

Constructor for three-parameter distributions

Currently implemented distributions are BetaBinomial.

Arguments

  • a, b, c: Generic parameters whose meaning varies depending on what distribution is provided. See the list below.
  • distribution: A valid univariate distribution from Distributions.jl.

Precisely what a, b and c are depends on which distribution is provided.

  • UncertainValue(BetaBinomial, n, α, β) returns an UncertainScalarBetaBinomialDistributed instance.

Keyword arguments

  • nσ: If distribution <: Distributions.Normal, then how many standard deviations away from μ does lower and upper (i.e. both, because they are the same distance away from μ) represent?
  • tolerance: A threshold determining how symmetric the uncertainties must be in order to allow the construction of Normal distribution (upper - lower > threshold is required).
  • trunc_lower: Lower truncation bound for distributions with infinite support. Defaults to -Inf.
  • trunc_upper: Upper truncation bound for distributions with infinite support. Defaults to Inf.

Examples

BetaBinomial distribution

Normal distributions are formed by using the constructor UncertainValue(μ, σ, Normal; kwargs...). This gives a normal distribution with mean μ and standard deviation σ/nσ (nσ must be given as a keyword argument).

1
2
3
# A beta binomial distribution with n = 100 trials and parameters α = 2.3 and
# β = 5
UncertainValue(100, 2.3, 5, BetaBinomial)

source