-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Discrete probability monad -- -- Provides the Distribution monad, which describes discrete -- probability distributions. @package prob @version 0.1.1 -- | This module defines the Distribution monad and its operations. -- -- A Distribution a is a discrete probability -- distribution over values of type a. -- -- You can define distributions in several ways: -- -- -- -- Once you have a distribution, you can sample from it using -- sample, list its outcomes and their probabilities using -- probabilities or possibilities, and compute various -- statistics using probability, approxProbability, -- expectation, variance, stddev, entropy, -- relativeEntropy, or mutualInformation. -- -- It's important to make a distinction between *finite* and *infinite* -- distributions. An infinite distribution is one whose list of -- possibilities is infinite. Note that this *includes* -- distributions for which there are only finitely many distinct -- outcomes, but still an infinite number of paths to reach these -- outcomes. Infinite distributions typically arise from recursive -- expressions. Certain functions only work on finite distributions, and -- will hang or OOM if given an infinite distribution. -- -- For example, if you express the process of rolling a six-sided die, -- but always rerolling if the result is one, then there are five -- distinct outcomes: 2, 3, 4, 5, or 6. Nevertheless, this is an infinite -- distribution, because it's possible to roll any number of ones prior -- to the final result. module Probability.Distribution -- | A probability distribution of values. data Distribution prob a -- | An event is a predicate on values from a sample space. type Event s = s -> Bool -- | A random variable is a function mapping each element of a sample space -- to the corresponding value of the random variable. type RandVar s a = s -> a -- | A view of a probability distribution from the point of view of a given -- event. The event either always happens, never happens, or happens -- sometimes with some probability. In the latter case, there are -- posterior distributions for when the event does or does not happen. data EventView prob s Always :: Distribution prob s -> EventView prob s Never :: Distribution prob s -> EventView prob s Sometimes :: prob -> Distribution prob s -> Distribution prob s -> EventView prob s -- | Gives the list of all possible values of a given probability -- distribution. The list will often contain multiple entries for the -- same outcome, in which case the true probability for that outcome is -- the sum of probabilities of all entries. -- -- In the finite case, multiple entries can be combined by using -- simplify on the Distribution first. possibilities :: Num prob => Distribution prob a -> [(prob, a)] -- | Gives a map from outcomes to their probabilities in the given -- distribution. -- -- This only works for finite distributions. Infinite distributions -- (including even distributions with finitely many outcomes, but -- infinitely many paths to reach those outcomes) will hang. probabilities :: (Num prob, Ord a) => Distribution prob a -> Map a prob -- | Simplifies a finite distribution. -- -- This only works for finite distributions. Infinite distributions -- (including even distributions with finitely many outcomes, but -- infinitely many paths to reach those outcomes) will hang. simplify :: (Fractional prob, Ord a) => Distribution prob a -> Distribution prob a -- | Samples the probability distribution to produce a value. sample :: Real prob => Distribution prob a -> IO a -- | Gives a view on a probability distribution relative to some event. -- -- The following are guaranteed. 1. fromEventView . -- viewEvent ev = id 2. If viewEvent ev dist = -- Always dist', then dist = dist' and -- probability ev dist = 1. 3. If viewEvent ev -- dist = Never dist', then dist = dist' and -- probability ev dist = 0. 4. If viewEvent ev -- dist = Sometimes p a b, then probability ev -- dist = p and: * dist = bernoulli p >>= bool a -- b * probability ev a = 1 * probability -- ev b = 0 -- -- This only works for finite distributions. Infinite distributions -- (including even distributions with finitely many outcomes, but -- infinitely many paths to reach those outcomes) will hang. viewEvent :: Fractional prob => Event s -> Distribution prob s -> EventView prob s -- | Converts from EventView back to a Distribution. The -- resulting distribution is equivalent to the source distribution. fromEventView :: EventView prob s -> Distribution prob s -- | Truncates an infinite distribution to make it finite. The epsilon -- parameter is the amount of tail probability that you're willing to -- ignore and assign to an arbitrary outcome. finitize :: (Fractional prob, Ord prob) => prob -> Distribution prob a -> Distribution prob a -- | Truncates an infinite distribution to make it finite. This is -- equivalent to the original distribution, except with some arbitrary -- set of outcomes with probability less than epsilon replaced by -- Nothing. finitizeMaybe :: (Fractional prob, Ord prob) => prob -> Distribution prob a -> Distribution prob (Maybe a) -- | Produces the conditional probability distribution, assuming some -- event. This function works for all distributions, but always produces -- an infinite distribution for non-trivial events. conditional :: Event s -> Distribution prob s -> Distribution prob s -- | Produces the conditional probability distribution, assuming some -- event. -- -- This only works for finite distributions. Infinite distributions -- (including even distributions with finitely many outcomes, but -- infinitely many paths to reach those outcomes) will hang. finiteConditional :: Fractional prob => Event s -> Distribution prob s -> Distribution prob s -- | Updates a prior distribution of parameters for a model, based on an -- observed event. This implements Bayes' Law for distributions. -- -- This function works for all distributions, but always produces an -- infinite distribution for non-trivial events. bayesian :: (param -> Distribution prob s) -> Event s -> Distribution prob param -> Distribution prob param -- | Updates a prior distribution of parameters for a model, based on an -- observed event. This implements Bayes' Law for distributions. -- -- This only works for finite distributions. Infinite distributions -- (including even distributions with finitely many outcomes, but -- infinitely many paths to reach those outcomes) will hang. finiteBayesian :: Fractional prob => (param -> Distribution prob s) -> Event s -> Distribution prob param -> Distribution prob param -- | A distribution with a fixed probability for each outcome. The -- probabilities should add to 1, but this is not checked. categorical :: Fractional prob => [(prob, a)] -> Distribution prob a -- | A uniform distribution over a list of values. uniform :: Fractional prob => [a] -> Distribution prob a -- | Geometric distribution over a list of possibilities. geometric :: prob -> [a] -> Distribution prob a -- | A Bernoulli distribution. This gives True with probability p, -- and False otherwise. bernoulli :: prob -> Distribution prob Bool -- | A binomial distribution. This gives the distribution of number of -- successes in n trials with probability p of success. binomial :: (Fractional prob, Integral n) => prob -> n -> Distribution prob n -- | Negative binomial distribution. This gives the distribution of number -- of failures before r successes with probability p of -- success. negativeBinomial :: (Fractional prob, Integral n) => prob -> n -> Distribution prob n -- | Hypergeometric distribution. This gives the distribution of number of -- successful draws out of n attempts without replacement, when -- k possibilities are successful. hypergeometric :: (Fractional prob, Integral n) => n -> n -> n -> Distribution prob n -- | Poisson distribution. Gives the number of independent events occurring -- in a fixed time interval, if events are occurring at the given -- expected rate per time interval. poisson :: (Floating prob, Integral n) => prob -> Distribution prob n -- | Computes the probability of an event, represented by a predicate on -- values. -- -- This only works for finite distributions. Infinite distributions -- (including even distributions with finitely many outcomes, but -- infinitely many paths to reach those outcomes) will hang. probability :: Num prob => Event s -> Distribution prob s -> prob -- | Like probability, but produces a lazy list of ever-improving bounds on -- the probability. This can be used on infinite distributions, for which -- the exact probability cannot be calculated. probabilityBounds :: Num prob => Event s -> Distribution prob s -> [(prob, prob)] -- | Like probability, but produces a value that differs from the true -- probability by at most epsilon. This can be used on infinite -- distributions, for which the exact probability cannot be calculated. approxProbability :: (Ord prob, Fractional prob) => prob -> Event s -> Distribution prob s -> prob -- | Computes the expected value of a finite distribution. -- -- This only works for finite distributions. Infinite distributions -- (including even distributions with finitely many outcomes, but -- infinitely many paths to reach those outcomes) will hang. expectation :: Num a => Distribution a a -> a -- | Computes the variance of a finite distribution. -- -- This only works for finite distributions. Infinite distributions -- (including even distributions with finitely many outcomes, but -- infinitely many paths to reach those outcomes) will hang. variance :: Num a => Distribution a a -> a -- | Computes the standard deviation of a finite distribution. -- -- This only works for finite distributions. Infinite distributions -- (including even distributions with finitely many outcomes, but -- infinitely many paths to reach those outcomes) will hang. stddev :: Floating a => Distribution a a -> a -- | Computes the entropy of a distribution in bits. -- -- This only works for finite distributions. Infinite distributions -- (including even distributions with finitely many outcomes, but -- infinitely many paths to reach those outcomes) will hang. entropy :: (Floating prob, Ord a) => Distribution prob a -> prob -- | Computes the relative entropy, also known as Kullback-Leibler -- divergence, between two distributions in bits. -- -- This only works for finite distributions. Infinite distributions -- (including even distributions with finitely many outcomes, but -- infinitely many paths to reach those outcomes) will hang. relativeEntropy :: (Eq prob, Floating prob, Ord a) => Distribution prob a -> Distribution prob a -> prob -- | Computes the mutual information between two random variables, in bits. -- The given distribution is taken as a definition of a probability -- space, and the random variables are represented as functions from the -- sample space to values taken by the random variable. -- -- This only works for finite distributions. Infinite distributions -- (including even distributions with finitely many outcomes, but -- infinitely many paths to reach those outcomes) will hang. mutualInformation :: (Eq prob, Floating prob, Ord a, Ord b) => RandVar s a -> RandVar s b -> Distribution prob s -> prob instance GHC.Base.Functor (Probability.Distribution.Distribution prob) instance Data.Bifunctor.Bifunctor Probability.Distribution.Distribution instance GHC.Base.Applicative (Probability.Distribution.Distribution prob) instance GHC.Base.Monad (Probability.Distribution.Distribution prob) instance GHC.Num.Num a => GHC.Num.Num (Probability.Distribution.Distribution prob a) instance GHC.Real.Fractional a => GHC.Real.Fractional (Probability.Distribution.Distribution prob a)