Skip to content

Theoretical distributions with known parameters

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!

Generic constructors

From instances of distributions

# UncertainData.UncertainValues.UncertainValue — Method.

1
UncertainValue(d::Distributions.Distribution)

Construct an uncertain value from an instance of a distribution. If a specific uncertain value type has not been implemented, the number of parameters is determined from the distribution and an instance of one of the following types is returned:

  • UncertainScalarTheoreticalOneParameter
  • UncertainScalarTheoreticalTwoParameter
  • UncertainScalarTheoreticalThreeParameter

Examples

1
2
3
UncertainValue(Normal(0, 1))
UncertainValue(Gamma(4, 5.1))
UncertainValue(Binomial, 8, 0.2)

source

Defined from scratch

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). Parameters are provided to the constructor in the same order as for constructing the equivalent distributions in Distributions.jl.

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

Type documentation

# UncertainData.UncertainValues.UncertainScalarBetaBinomialDistributed — Type.

Uncertain value represented by a beta binomial distribution.

source

# UncertainData.UncertainValues.UncertainScalarBetaDistributed — Type.

Uncertain value represented by a beta distribution.

source

# UncertainData.UncertainValues.UncertainScalarBetaPrimeDistributed — Type.

Uncertain value represented by a beta prime distribution.

source

# UncertainData.UncertainValues.UncertainScalarBinomialDistributed — Type.

Uncertain value represented by a binomial distribution.

source

# UncertainData.UncertainValues.UncertainScalarFrechetDistributed — Type.

Uncertain value represented by a Fréchet distribution.

source

# UncertainData.UncertainValues.UncertainScalarGammaDistributed — Type.

Uncertain value represented by a gamma distribution.

source

# UncertainData.UncertainValues.UncertainScalarNormallyDistributed — Type.

Uncertain value represented by a normal distribution.

source

# UncertainData.UncertainValues.UncertainScalarUniformlyDistributed — Type.

Uncertain value represented by a uniform distribution.

source

List of 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)