-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Sampling function-based probability distributions.
--   
--   A simple probability distribution type, where distributions are
--   characterized by sampling functions.
--   
--   This implementation is a thin layer over <tt>mwc-random</tt>, which
--   handles RNG state-passing automatically by using a <tt>PrimMonad</tt>
--   like <tt>IO</tt> or <tt>ST s</tt> under the hood.
--   
--   <i>Examples</i>
--   
--   Transform a distribution's support while leaving its density structure
--   invariant:
--   
--   <pre>
--   -- uniform over [0, 1] to uniform over [1, 2]
--   succ &lt;$&gt; uniform
--   </pre>
--   
--   Sequence distributions together using bind:
--   
--   <pre>
--   -- a beta-binomial conjugate distribution
--   beta 1 10 &gt;&gt;= binomial 10
--   </pre>
--   
--   Use do-notation to build complex joint distributions from composable,
--   local conditionals:
--   
--   <pre>
--   hierarchicalModel = do
--     [c, d, e, f] &lt;- replicateM 4 $ uniformR (1, 10)
--     a &lt;- gamma c d
--     b &lt;- gamma e f
--     p &lt;- beta a b
--     n &lt;- uniformR (5, 10)
--     binomial n p
--   </pre>
@package mwc-probability
@version 2.0.2


-- | A probability monad based on sampling functions.
--   
--   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 <tt><a>beta</a> 1 8 &gt;&gt;= <a>binomial</a> 10</tt> corresponds
--   to a <a>beta-binomial</a> distribution in which the uncertainty
--   captured by <tt><a>beta</a> 1 8</tt> has been marginalized out.
--   
--   The distribution resulting from a series of effects is called the
--   <i>predictive distribution</i> of the model described by the
--   corresponding expression. The monadic structure lets one piece
--   together a hierarchical structure from simpler, local conditionals:
--   
--   <pre>
--   hierarchicalModel = do
--     [c, d, e, f] &lt;- replicateM 4 $ uniformR (1, 10)
--     a &lt;- gamma c d
--     b &lt;- gamma e f
--     p &lt;- beta a b
--     n &lt;- uniformR (5, 10)
--     binomial n p
--   </pre>
--   
--   The functor instance for a probability monad transforms the support of
--   the distribution while leaving its density structure invariant in some
--   sense. For example, <tt><a>uniform</a></tt> is a distribution over the
--   0-1 interval, but <tt>fmap (+ 1) uniform</tt> is the translated
--   distribution over the 1-2 interval.
--   
--   <pre>
--   &gt;&gt;&gt; create &gt;&gt;= sample (fmap (+ 1) uniform)
--   1.5480073474340754
--   </pre>
--   
--   <h2>Running the examples</h2>
--   
--   In the following we will assume an interactive GHCi session; the user
--   should first declare a random number generator:
--   
--   <pre>
--   &gt;&gt;&gt; gen &lt;- create
--   </pre>
--   
--   which will be reused throughout all examples. Note: creating a random
--   generator is an expensive operation, so it should be only performed
--   once in the code (usually in the top-level IO action, e.g
--   <tt>main</tt>).
--   
--   <h2>References</h2>
--   
--   1) L.Devroye, Non-Uniform Random Variate Generation, Springer-Verlag,
--   New York, 1986. (Made freely available by the author:
--   <a>http://www.nrbook.com/devroye</a> )
module System.Random.MWC.Probability

-- | A probability distribution characterized by a sampling function.
--   
--   <pre>
--   &gt;&gt;&gt; sample uniform gen
--   0.4208881170464097
--   </pre>
newtype Prob m a
Prob :: (Gen (PrimState m) -> m a) -> Prob m a
[sample] :: Prob m a -> Gen (PrimState m) -> m a

-- | Sample from a model <tt>n</tt> times.
--   
--   <pre>
--   &gt;&gt;&gt; samples 2 uniform gen
--   [0.6738707766845254,0.9730405951541817]
--   </pre>
samples :: PrimMonad m => Int -> Prob m a -> Gen (PrimState m) -> m [a]

-- | The uniform distribution over a type.
--   
--   <pre>
--   &gt;&gt;&gt; sample uniform gen :: IO Double
--   0.29308497534914946
--   
--   &gt;&gt;&gt; sample uniform gen :: IO Bool
--   False
--   </pre>
uniform :: (PrimMonad m, Variate a) => Prob m a

-- | The uniform distribution over the provided interval.
--   
--   <pre>
--   &gt;&gt;&gt; sample (uniformR (0, 1)) gen
--   0.44984153252922365
--   </pre>
uniformR :: (PrimMonad m, Variate a) => (a, a) -> Prob m a

-- | The normal or Gaussian distribution with a specified mean and standard
--   deviation.
normal :: PrimMonad m => Double -> Double -> Prob m Double

-- | The standard normal or Gaussian distribution (with mean 0 and standard
--   deviation 1).
standardNormal :: PrimMonad m => Prob m Double

-- | An isotropic or spherical Gaussian distribution with specified mean
--   vector and scalar standard deviation parameter.
isoNormal :: (Traversable f, PrimMonad m) => f Double -> Double -> Prob m (f Double)

-- | The log-normal distribution with specified mean and standard
--   deviation.
logNormal :: PrimMonad m => Double -> Double -> Prob m Double

-- | The exponential distribution with provided rate parameter.
exponential :: PrimMonad m => Double -> Prob m Double

-- | The Laplace distribution with provided location and scale parameters.
laplace :: (Floating a, Variate a, PrimMonad m) => a -> a -> Prob m a

-- | 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 <i> (Gamma(a) * b ^ a) x ^ (a - 1) e ^ (- x </i> b)
gamma :: PrimMonad m => Double -> Double -> Prob m Double

-- | The inverse-gamma distribution.
inverseGamma :: PrimMonad m => Double -> Double -> Prob m Double

-- | The Normal-Gamma distribution of parameters mu, lambda, a, b
normalGamma :: PrimMonad m => Double -> Double -> Double -> Double -> Prob m Double

-- | The Weibull distribution with provided shape and scale parameters.
weibull :: (Floating a, Variate a, PrimMonad m) => a -> a -> Prob m a

-- | The chi-square distribution.
chiSquare :: PrimMonad m => Int -> Prob m Double

-- | The beta distribution.
beta :: PrimMonad m => Double -> Double -> Prob m Double

-- | Student's t distribution.
student :: PrimMonad m => Double -> Double -> Double -> Prob m Double

-- | The Pareto distribution with specified index <tt>a</tt> and minimum
--   <tt>xmin</tt> parameters.
--   
--   Both <tt>a</tt> and <tt>xmin</tt> must be positive.
pareto :: PrimMonad m => Double -> Double -> Prob m Double

-- | The Dirichlet distribution.
dirichlet :: (Traversable f, PrimMonad m) => f Double -> Prob m (f Double)

-- | The symmetric Dirichlet distribution of dimension n.
symmetricDirichlet :: PrimMonad m => Int -> Double -> Prob m [Double]

-- | The discrete uniform distribution.
--   
--   <pre>
--   &gt;&gt;&gt; sample (discreteUniform [0..10]) gen
--   6
--   
--   &gt;&gt;&gt; sample (discreteUniform "abcdefghijklmnopqrstuvwxyz") gen
--   'a'
--   </pre>
discreteUniform :: (PrimMonad m, Foldable f) => f a -> Prob m a

-- | The Zipf-Mandelbrot distribution, generated with the rejection
--   sampling algorithm X.6.1 shown in [1].
--   
--   The parameter should be positive, but values close to 1 should be
--   avoided as they are very computationally intensive. The following code
--   illustrates this behaviour.
--   
--   <pre>
--   &gt;&gt;&gt; samples 10 (zipf 1.1) gen
--   [11315371987423520,2746946,653,609,2,13,85,4,256184577853,50]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; samples 10 (zipf 1.5) gen
--   [19,3,3,1,1,2,1,191,2,1]
--   </pre>
zipf :: (PrimMonad m, Integral b) => Double -> Prob m b

-- | A categorical distribution defined by the supplied list of
--   probabilities.
categorical :: (Foldable f, PrimMonad m) => f Double -> Prob m Int

-- | The Bernoulli distribution.
bernoulli :: PrimMonad m => Double -> Prob m Bool

-- | The binomial distribution.
binomial :: PrimMonad m => Int -> Double -> Prob m Int

-- | The negative binomial distribution with <tt>n</tt> trials each with
--   "success" probability <tt>p</tt>. Example X.1.5 in [1].
--   
--   Note: <tt>n</tt> must be larger than 1 and <tt>p</tt> included between
--   0 and 1.
negativeBinomial :: (PrimMonad m, Integral a) => a -> Double -> Prob m Int

-- | The multinomial distribution.
multinomial :: (Foldable f, PrimMonad m) => Int -> f Double -> Prob m [Int]

-- | The Poisson distribution.
poisson :: PrimMonad m => Double -> Prob m Int
instance GHC.Base.Functor m => GHC.Base.Functor (System.Random.MWC.Probability.Prob m)
instance GHC.Base.Monad m => GHC.Base.Applicative (System.Random.MWC.Probability.Prob m)
instance GHC.Base.Monad m => GHC.Base.Monad (System.Random.MWC.Probability.Prob m)
instance (GHC.Base.Monad m, GHC.Num.Num a) => GHC.Num.Num (System.Random.MWC.Probability.Prob m a)
instance Control.Monad.Trans.Class.MonadTrans System.Random.MWC.Probability.Prob
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (System.Random.MWC.Probability.Prob m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (System.Random.MWC.Probability.Prob m)
