UncertainHistogramming API

const moment_list::SVector

Convenience list of all moment type symbols used. Each of these Symbols are @evaluated into an empty struct trait <: Moment.

UncertainHistogramming.moment_list

abstract type ContinuousDistribution end

Concept establishing what a continuous distribution is within the code base. Here, as with ContinuousHistogram, the continuity refers to the domain of the distribution, and not necessarily its range.

abstract type ContinuousHistogram end

abstract type representing the ContinuousHistogram concept. These are histograms whose input data have uncertainty associated with them, and therefore we build them using a value-error-dependent kernel for each entry.

For each new ContinuousHistogram, one must overload the functions given in each of the src/Kernels folder. Then one needs to add a new ContinuousDistribution and define its methods, like those shown in the src/Moments files. Finally, the KernelDistribution must be mapped.

Then all utility and stats functionality should just work.

GaussianDistribution <: ContinuousDistribution

Trait representing a Gaussian distribution.

GaussianHistogram{T <: Number} <: ContinuousHistogram

A ContinuousHistogram with a Gaussian kernel for each value-error pair.

This [ContinuousHistogram] is formed by summing Gaussian kernels for each $(\mu_i, \sigma_i)$ as

\[\mathcal{H}(y) = \frac{1}{M} \sum_{i = 1}^M G(y; \mu_i, \sigma_i),\]

where

\[G(y; \mu_i, \sigma_i) = \frac{ \exp\left[ -\frac{ \left( y - \mu_i \right)^2 }{2 \sigma_i^2} \right] }{ \sigma_i \sqrt{2\pi}}.\]

This expression makes the calculation of the non-central moment a simple mean of the individual non-central moment.

Contents

• moments::Vector{T}: a collection of moments for the GaussianHistogram which are updated in an online fashion
• values::Vector{T}: the values used to construct the GaussianHistogram
• errors::Vector{T}: the errors used to construct the GaussianHistogram

abstract type Moment end

Concept representing non-central statistical moments.

UniformDistribution <: ContinuousDistribution

Trait representing a uniform distribution.

UniformHistogram{T <: Number} <: ContinuousHistogram

A ContinuousHistogram with a uniform kernel for each value-error pair.

This [ContinuousHistogram] is formed by summing uniform kernels for each $(x_i, \epsilon_i)$ as

\[\mathcal{H}(y) = \frac{1}{M} \sum_{i = 1}^M \mathcal{U}(y; x_i, \epsilon_i),\]

where

\[\mathcal{U}(y; x_i, \epsilon_i) = \begin{cases} \frac{1}{2\epsilon_i}, & y \in (x_i - \epsilon_i, x_i + \epsilon_i) \\ 0, & \mathrm{otherwise} \end{cases}.\]

These expression makes the calculation of the non-central moments a simple mean of the individual non-central moment.

Contents

• moments::Vector{T}: a collection of moments for the UniformHistogram which are updated in an online fashion
• values::Vector{T}: the values used to construct the UniformHistogram
• errors::Vector{T}: the errors used to construct the UniformHistogram

eltype(::ContinuousHistogram)

Base overload for accessing the eltype.

julia> eltype(GaussianHistogram())
Float64

julia> eltype(UniformHistogram{Float32}())
Float32

getindex(::ContinuousHistogram, ::Type{<: Moment})

Convenience function to access a given Moment from its name.

julia> hist = GaussianHistogram();

julia> push!(hist, (0, 1))
GaussianHistogram{Float64}:
  length  = 1
  moments = 0.0  1.0  0.0  3.0  

  Statistics
    mean        = 0.0
    variance    = 1.0
    skewness    = 0.0
    kurtosis    = 0.0

julia> hist[FirstMoment]
0.0

julia> hist[SecondMoment]
1.0

julia> hist[ThirdMoment]
0.0

julia> hist[FourthMoment]
3.0

length(::ContinuousHistogram)

Base overload to return the length of the values Vector in the argument ContinuousHistogram.

push!(::ContinuousHistogram, ::Tuple{Number, Number})
push!(::ContinuousHistogram, ::Measurement)
push!(::ContinuousHistogram, ::AbstractVector)
push!(::ContinuousHistogram, ::Vector{Measurement})

Base overload to introduce a new value-error pair into the ContinuousHistogram. This function also _update_moments! in an amortized way to add little overhead.

setindex!(::ContinuousHistogram, val, ::Type{<: Moment})

Convenience function for accessing the ContinuousHistogram Moments from their name.

show([::IO = stdout], ::ContinuousHistogram)
show(::ContinuousHistogram)

print the relevant information for a ContinuousHistogram.

measurement(::ContinuousHistogram)

Interface to Measurements.jl. Return a Measurement with val as the ContinuousHistogram mean and the err as the ContinuousHistogram std (standard deviation).

mean(::ContinuousHistogram)

First moment of the ContinuousHistogram.

std(::ContinuousHistogram)

The standard deviation of the ContinuousHistogram.

var(::ContinuousHistogram)

Second cumulant of the ContinuousHistogram.

kurtosis(::ContinuousHistogram [, excess = true ])

Pearson (excess) kurtosis of a ContinuousHistogram.

skewness(::ContinuousHistogram)

Fisher's skewness of a ContinuousHistogram.

KernelDistribution(::ContinuousHistogram) -> MethodError
KernelDistribution(::GaussianHistogram)   -> GaussianDistribution
KernelDistribution(::UniformHistogram)    -> UniformDistribution

Interface function that assigns a ContinuousHistogram Type to a specific kernel distribution.

MomentIndex(::Type{<: Moment}) = -1

Mapping from <: Moment traits to indexable integers.

_online_mean(xnew, μold, nold)

Update the old mean μold over nold elements with the new data point xnew. This function implements

\[\mu_{n+1} = \mu_n + \frac{x_{n+1} - \mu_{n}}{n+1}.\]

_update_moment!(::ContinuousHistogram, moment_t, val, err)

Update the ContinuousHistogram's moment_t using an _online_mean with the inclusion of the value-error pair (val, err).

_update_moments!(::ContinuousHistogram, val, err)

Update the the non-central moments of the ContinuousHistogram online with the new value-error pair (val, err). This is done because each is non-central moment is the mean non-central moments of each ContinuousDistribution.

construct!(output, ::ContinuousHistogram, x)

Similar to construct but here, the output Array is modified in-place.

construct(::ContinuousHistogram, x)

Map the values of x through the [ContinuousHistogram] and return an Array of the same size as x.

gaussian(::Number, μ, σ)
gaussian(::AbstractArray, μ, σ)

Calculate the normalized value of a Gaussian with mean μ and variance σ².

kernel(::ContinuousHistogram, ::AbstractArray, data) -> MethodError
kernel(::GaussianHistogram, ::AbstractArray, data)
kernel(::UniformHistogram, ::AbstractArray, data)

The kernel function $\mathcal{K}(x)$ used to compute a ContinuousHistogram such that

\[\mathcal{H}(x) = \sum_{i = 1}^M \mathcal{K}_i(x),\]

where $M$ is the total number of data points. For brevity, we have represented all data-dependence through the subscript $i$.

moment(::ContinuousHistogram, ::Type{<: Moment})

Convenience wrapper to return a Moment from a ContinuousHistogram by that Moment's name.

julia> hist = GaussianHistogram();

julia> push!(hist, (0, 1))
GaussianHistogram{Float64}:
  length  = 1
  moments = 0.0  1.0  0.0  3.0  

  Statistics
    mean        = 0.0
    variance    = 1.0
    skewness    = 0.0
    kurtosis    = 0.0

julia> moment(hist, FirstMoment)
0.0

julia> moment(hist, SecondMoment)
1.0

julia> moment(hist, ThirdMoment)
0.0

julia> moment(hist, FourthMoment)
3.0

moment(::Type{GaussianDistribution}, FirstMoment, μ, σ)

Analytic expression for the no-central FirstMoment from a GaussianDistribution:

\[M_1 = \int_{-\infty}^{\infty} {\rm d}y\, G(y;\mu,\sigma)\cdot y = \mu. \]

moment(::Type{GaussianDistribution}, FourthMoment, μ, σ)

Analytic expression for the no-central FourthMoment from a GaussianDistribution:

\[M_4 = \int_{-\infty}^{\infty} {\rm d}y\, G(y;\mu,\sigma)\cdot y^4 = \mu^4 + 6\mu^2\sigma^2 + 3\sigma^4. \]

moment(::Type{GaussianDistribution}, SecondMoment, μ, σ)

Analytic expression for the no-central SecondMoment from a GaussianDistribution:

\[M_2 = \int_{-\infty}^{\infty} {\rm d}y\, G(y;\mu,\sigma)\cdot y^2 = \mu^2 + \sigma^2. \]

moment(::Type{GaussianDistribution}, ThirdMoment, μ, σ)

Analytic expression for the no-central ThirdMoment from a GaussianDistribution:

\[M_3 = \int_{-\infty}^{\infty} {\rm d}y\, G(y;\mu,\sigma)\cdot y^3 = \mu^3 + 3\mu\sigma^2. \]

moment(::Type{UniformDistribution}, FirstMoment, val, err)

Analytic expression for the no-central FirstMoment from a UniformDistribution:

\[M_1 = \int_{-\infty}^{\infty} {\rm d}y\, \mathcal{U}(y; x, \epsilon)\cdot y = x. \]

moment(::Type{UniformDistribution}, FourthMoment, val, err)

Analytic expression for the no-central FourthMoment from a UniformDistribution:

\[M_4 = \int_{-\infty}^{\infty} {\rm d}y\, \mathcal{U}(y; x, \epsilon)\cdot y^4 = x^4 + 2x^2\epsilon^2 + \frac{1}{5}\epsilon^4. \]

moment(::Type{UniformDistribution}, SecondMoment, val, err)

Analytic expression for the no-central SecondMoment from a UniformDistribution:

\[M_2 = \int_{-\infty}^{\infty} {\rm d}y\, \mathcal{U}(y; x, \epsilon)\cdot y^2 = x^2 + \frac{1}{3}\epsilon^2. \]

moment(::Type{UniformDistribution}, ThirdMoment, val, err)

Analytic expression for the no-central ThirdMoment from a UniformDistribution:

\[M_3 = \int_{-\infty}^{\infty} {\rm d}y\, \mathcal{U}(y; x, \epsilon)\cdot y^3 = x\left(x^2 + \epsilon^2 \right). \]

uniform_function(::Number, μ, σ)
uniform_function(::AbstractArray, μ, σ)

Calculate the normalized value of a uniform distribution centered at val that extends out by err above and below.

val_err(::ContinuousHistogram, idx)

Return a (value, error)-Tuple.