Copyright	(c) 2015-2018 Jared Tobin Marco Zocca
License	MIT
Maintainer	Jared Tobin <jared@jtobin.ca>, Marco Zocca <zocca.marco gmail>
Stability	unstable
Portability	ghc
Safe Haskell	None
Language	Haskell2010

System.Random.MWC.Probability

Description

A probability monad based on sampling functions, implemented as a thin wrapper over the mwc-random library.

Probability distributions are abstract constructs that can be represented in a variety of ways. The sampling function representation is particularly useful -- it's computationally efficient, and collections of samples are amenable to much practical work.

Probability monads propagate uncertainty under the hood. An expression like beta 1 8 >>= binomial 10 corresponds to a beta-binomial distribution in which the uncertainty captured by beta 1 8 has been marginalized out.

The distribution resulting from a series of effects is called the predictive distribution of the model described by the corresponding expression. The monadic structure lets one piece together a hierarchical structure from simpler, local conditionals:

hierarchicalModel = do
  [c, d, e, f] <- replicateM 4 $ uniformR (1, 10)
  a <- gamma c d
  b <- gamma e f
  p <- beta a b
  n <- uniformR (5, 10)
  binomial n p

The functor instance allows one to transforms the support of a distribution while leaving its density structure invariant. For example, uniform is a distribution over the 0-1 interval, but fmap (+ 1) uniform is the translated distribution over the 1-2 interval:

>>> create >>= sample (fmap (+ 1) uniform)
1.5480073474340754

The applicative instance guarantees that the generated samples are generated independently:

>>> create >>= sample ((,) <$> uniform <*> uniform)

Synopsis

Documentation

newtype Prob m a #

A probability distribution characterized by a sampling function.

>>> gen <- createSystemRandom
>>> sample uniform gen
0.4208881170464097

Constructors

Prob
Fields sample :: Gen (PrimState m) -> m a

Instances

MonadTrans Prob #
Methods lift :: Monad m => m a -> Prob m a #
Monad m => Monad (Prob m) #
Methods (>>=) :: Prob m a -> (a -> Prob m b) -> Prob m b # (>>) :: Prob m a -> Prob m b -> Prob m b # return :: a -> Prob m a # fail :: String -> Prob m a #
Functor m => Functor (Prob m) #
Methods fmap :: (a -> b) -> Prob m a -> Prob m b # (<$) :: a -> Prob m b -> Prob m a #
Monad m => Applicative (Prob m) #
Methods pure :: a -> Prob m a # (<>) :: Prob m (a -> b) -> Prob m a -> Prob m b # liftA2 :: (a -> b -> c) -> Prob m a -> Prob m b -> Prob m c # (>) :: Prob m a -> Prob m b -> Prob m b # (<*) :: Prob m a -> Prob m b -> Prob m a #
MonadIO m => MonadIO (Prob m) #
Methods liftIO :: IO a -> Prob m a #
PrimMonad m => PrimMonad (Prob m) #
Associated Types type PrimState (Prob m :: * -> ) :: # Methods primitive :: (State# (PrimState (Prob m)) -> (#TupleRep [RuntimeRep], LiftedRep, State# (PrimState (Prob m)), a#)) -> Prob m a #
(Monad m, Num a) => Num (Prob m a) #
Methods (+) :: Prob m a -> Prob m a -> Prob m a # (-) :: Prob m a -> Prob m a -> Prob m a # (*) :: Prob m a -> Prob m a -> Prob m a # negate :: Prob m a -> Prob m a # abs :: Prob m a -> Prob m a # signum :: Prob m a -> Prob m a # fromInteger :: Integer -> Prob m a #
type PrimState (Prob m) #
type PrimState (Prob m) = PrimState m

samples :: PrimMonad m => Int -> Prob m a -> Gen (PrimState m) -> m [a] #

Sample from a model n times.

>>> samples 2 uniform gen
[0.6738707766845254,0.9730405951541817]

uniform :: (PrimMonad m, Variate a) => Prob m a #

The uniform distribution at a specified type.

Note that Double and Float variates are defined over the unit interval.

>>> sample uniform gen :: IO Double
0.29308497534914946
>>> sample uniform gen :: IO Bool
False

uniformR :: (PrimMonad m, Variate a) => (a, a) -> Prob m a #

The uniform distribution over the provided interval.

>>> sample (uniformR (0, 1)) gen
0.44984153252922365

normal :: PrimMonad m => Double -> Double -> Prob m Double #

The normal or Gaussian distribution with specified mean and standard deviation.

Note that sd should be positive.

standardNormal :: PrimMonad m => Prob m Double #

The standard normal or Gaussian distribution with mean 0 and standard deviation 1.

isoNormal :: (Traversable f, PrimMonad m) => f Double -> Double -> Prob m (f Double) #

An isotropic or spherical Gaussian distribution with specified mean vector and scalar standard deviation parameter.

Note that sd should be positive.

logNormal :: PrimMonad m => Double -> Double -> Prob m Double #

The log-normal distribution with specified mean and standard deviation.

Note that sd should be positive.

exponential :: PrimMonad m => Double -> Prob m Double #

The exponential distribution with provided rate parameter.

Note that r should be positive.

inverseGaussian :: PrimMonad m => Double -> Double -> Prob m Double #

The inverse Gaussian (also known as Wald) distribution with mean parameter mu and shape parameter lambda.

Note that both mu and lambda should be positive.

laplace :: (Floating a, Variate a, PrimMonad m) => a -> a -> Prob m a #

The Laplace or double-exponential distribution with provided location and scale parameters.

Note that sigma should be positive.

gamma :: PrimMonad m => Double -> Double -> Prob m Double #

The gamma distribution with shape parameter a and scale parameter b.

This is the parameterization used more traditionally in frequentist statistics. It has the following corresponding probability density function:

f(x; a, b) = 1 / (Gamma(a) * b ^ a) x ^ (a - 1) e ^ (- x / b)

Note that both parameters should be positive.

inverseGamma :: PrimMonad m => Double -> Double -> Prob m Double #

The inverse-gamma distribution with shape parameter a and scale parameter b.

Note that both parameters should be positive.

normalGamma :: PrimMonad m => Double -> Double -> Double -> Double -> Prob m Double #

The Normal-Gamma distribution.

Note that the lambda, a, and b parameters should be positive.

weibull :: (Floating a, Variate a, PrimMonad m) => a -> a -> Prob m a #

The Weibull distribution with provided shape and scale parameters.

Note that both parameters should be positive.

chiSquare :: PrimMonad m => Int -> Prob m Double #

The chi-square distribution with the specified degrees of freedom.

Note that k should be positive.

beta :: PrimMonad m => Double -> Double -> Prob m Double #

The beta distribution with the specified shape parameters.

Note that both parameters should be positive.

gstudent :: PrimMonad m => Double -> Double -> Double -> Prob m Double #

Generalized Student's t distribution with location parameter m, scale parameter s, and degrees of freedom k.

Note that the s and k parameters should be positive.

student :: PrimMonad m => Double -> Prob m Double #

Student's t distribution with k degrees of freedom.

Note that k should be positive.

pareto :: PrimMonad m => Double -> Double -> Prob m Double #

The Pareto distribution with specified index a and minimum xmin parameters.

Note that both parameters should be positive.

dirichlet :: (Traversable f, PrimMonad m) => f Double -> Prob m (f Double) #

The Dirichlet distribution with the provided concentration parameters. The dimension of the distribution is determined by the number of concentration parameters supplied.

>>> sample (dirichlet [0.1, 1, 10]) gen
[1.2375387187120799e-5,3.4952460651813816e-3,0.9964923785476316]

Note that all concentration parameters should be positive.

symmetricDirichlet :: PrimMonad m => Int -> Double -> Prob m [Double] #

The symmetric Dirichlet distribution with dimension n. The provided concentration parameter is simply replicated n times.

Note that a should be positive.

discreteUniform :: (PrimMonad m, Foldable f) => f a -> Prob m a #

The discrete uniform distribution.

>>> sample (discreteUniform [0..10]) gen
6
>>> sample (discreteUniform "abcdefghijklmnopqrstuvwxyz") gen
'a'

zipf :: (PrimMonad m, Integral b) => Double -> Prob m b #

The Zipf-Mandelbrot distribution.

Note that a should be positive, and that values close to 1 should be avoided as they are very computationally intensive.

>>> samples 10 (zipf 1.1) gen
[11315371987423520,2746946,653,609,2,13,85,4,256184577853,50]

>>> samples 10 (zipf 1.5) gen
[19,3,3,1,1,2,1,191,2,1]

categorical :: (Foldable f, PrimMonad m) => f Double -> Prob m Int #

A categorical distribution defined by the supplied probabilities.

Note that the supplied container of probabilities must sum to 1.

bernoulli :: PrimMonad m => Double -> Prob m Bool #

The Bernoulli distribution with success probability p.

binomial :: PrimMonad m => Int -> Double -> Prob m Int #

The binomial distribution with number of trials n and success probability p.

>>> sample (binomial 10 0.3) gen
4

negativeBinomial :: (PrimMonad m, Integral a) => a -> Double -> Prob m Int #

The negative binomial distribution with number of trials n and success probability p.

>>> sample (negativeBinomial 10 0.3) gen
21

multinomial :: (Foldable f, PrimMonad m) => Int -> f Double -> Prob m [Int] #

The multinomial distribution of n trials and category probabilities ps.

Note that ps is a vector of probabilities and should sum to one.

poisson :: PrimMonad m => Double -> Prob m Int #

The Poisson distribution with rate parameter l.

Note that l should be positive.