Data.Distribution.Measure

This modules provides various measures on finite discrete probability distributions.

Probability

probability :: (a -> Bool) -> Distribution a -> Probability

Probability that a predicate holds on the distribution.

>>> probability (\ x -> x == 1 || x == 6) $ uniform [1 .. 6]
1 % 3

Takes O(n) time. See probabilityAt and probabilityIn for a more efficient ways to query elements and ranges.

probabilityAt :: Ord a => a -> Distribution a -> Probability

Probability of a given value.

Takes O(log(n)) time.

probabilityIn :: Ord a => (a, a) -> Distribution a -> Probability

Probability of a the inclusive [low, high] range. When low > high, the probability is 0.

Takes O(log(n) + m) time, where n is the size of the distribution and m the size of the range.

Expectation

expectation :: (Real a, Fractional b) => Distribution a -> b

Returns the expectation, or mean, of a distribution.

>>> expectation $ uniform [0, 1]
0.5

Empty distributions have an expectation of 0.

mean :: (Real a, Fractional b) => Distribution a -> b

Synonym of expectation.

Variation

variance :: (Real a, Fractional b) => Distribution a -> b

Returns the variance of a distribution.

>>> variance $ always 1
0.0
>>> variance $ uniform [0 .. 1]
0.25
>>> variance $ uniform [1 .. 7]
4.0

Empty distributions have a variance of 0.

standardDeviation :: (Real a, Floating b) => Distribution a -> b

Standard deviation.

>>> standardDeviation $ always 1
0.0
>>> standardDeviation $ uniform [0 .. 1]
0.5
>>> standardDeviation $ uniform [1 .. 7]
2.0

Values

median :: Distribution a -> Maybe a

Returns the median of the values. The median is the smallest value such that at least 50% of the values are less or equal to it.

>>> median $ fromList [(1, 0.6), (2, 0.4)]
Just 1
>>> median $ fromList [(1, 0.4), (2, 0.6)]
Just 2

modes :: Distribution a -> [a]

Returns all values whose probability is maximal.

quantile :: Probability -> Distribution a -> Maybe a

Returns the smallest value in the distribution such that at least a fraction p of the values are less or equal to it.

>>> quantile 0.0 $ uniform [1, 2, 3]
Just 1
>>> quantile 0.5 $ uniform [1, 2, 3]
Just 2
>>> quantile 1.0 $ uniform [1, 2, 3]
Just 3
>>> quantile 0.5 $ fromList []
Nothing