-- 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]
--   fmap succ uniform
--   </pre>
--   
--   Sequence distributions together using bind:
--   
--   <pre>
--   -- a beta-binomial compound 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.4


-- | A probability monad based on sampling functions, implemented as a thin
--   wrapper over the <a>mwc-random</a> 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 <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 allows one to transforms the support of a
--   distribution while leaving its density structure invariant. 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>
--   
--   The applicative instance guarantees that the generated samples are
--   generated independently:
--   
--   <pre>
--   &gt;&gt;&gt; create &gt;&gt;= sample ((,) &lt;$&gt; uniform &lt;*&gt; uniform)
--   </pre>
module System.Random.MWC.Probability

-- | A probability distribution characterized by a sampling function.
--   
--   <pre>
--   &gt;&gt;&gt; gen &lt;- createSystemRandom
--   
--   &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 at a specified type.
--   
--   Note that <a>Double</a> and <a>Float</a> variates are defined over the
--   unit interval.
--   
--   <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 specified mean and standard
--   deviation.
--   
--   Note that <tt>sd</tt> should be positive.
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.
--   
--   Note that <tt>sd</tt> should be positive.
isoNormal :: (Traversable f, PrimMonad m) => f Double -> Double -> Prob m (f Double)

-- | The log-normal distribution with specified mean and standard
--   deviation.
--   
--   Note that <tt>sd</tt> should be positive.
logNormal :: PrimMonad m => Double -> Double -> Prob m Double

-- | The exponential distribution with provided rate parameter.
--   
--   Note that <tt>r</tt> should be positive.
exponential :: PrimMonad m => Double -> Prob m Double

-- | The inverse Gaussian (also known as Wald) distribution with mean
--   parameter <tt>mu</tt> and shape parameter <tt>lambda</tt>.
--   
--   Note that both <tt>mu</tt> and <tt>lambda</tt> should be positive.
inverseGaussian :: PrimMonad m => Double -> Double -> Prob m Double

-- | The Laplace or double-exponential distribution with provided location
--   and scale parameters.
--   
--   Note that <tt>sigma</tt> should be positive.
laplace :: (Floating a, Variate a, PrimMonad m) => a -> a -> Prob m a

-- | The gamma distribution with shape parameter <tt>a</tt> and scale
--   parameter <tt>b</tt>.
--   
--   This is the parameterization used more traditionally in frequentist
--   statistics. It has the following corresponding probability density
--   function:
--   
--   <pre>
--   f(x; a, b) = 1 / (Gamma(a) * b ^ a) x ^ (a - 1) e ^ (- x / b)
--   </pre>
--   
--   Note that both parameters should be positive.
gamma :: PrimMonad m => Double -> Double -> Prob m Double

-- | The inverse-gamma distribution with shape parameter <tt>a</tt> and
--   scale parameter <tt>b</tt>.
--   
--   Note that both parameters should be positive.
inverseGamma :: PrimMonad m => Double -> Double -> Prob m Double

-- | The Normal-Gamma distribution.
--   
--   Note that the <tt>lambda</tt>, <tt>a</tt>, and <tt>b</tt> parameters
--   should be positive.
normalGamma :: PrimMonad m => Double -> Double -> Double -> Double -> Prob m Double

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

-- | The chi-square distribution with the specified degrees of freedom.
--   
--   Note that <tt>k</tt> should be positive.
chiSquare :: PrimMonad m => Int -> Prob m Double

-- | The beta distribution with the specified shape parameters.
--   
--   Note that both parameters should be positive.
beta :: PrimMonad m => Double -> Double -> Prob m Double

-- | Generalized Student's t distribution with location parameter
--   <tt>m</tt>, scale parameter <tt>s</tt>, and degrees of freedom
--   <tt>k</tt>.
--   
--   Note that the <tt>s</tt> and <tt>k</tt> parameters should be positive.
gstudent :: PrimMonad m => Double -> Double -> Double -> Prob m Double

-- | Student's t distribution with <tt>k</tt> degrees of freedom.
--   
--   Note that <tt>k</tt> should be positive.
student :: PrimMonad m => Double -> Prob m Double

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

-- | The Dirichlet distribution with the provided concentration parameters.
--   The dimension of the distribution is determined by the number of
--   concentration parameters supplied.
--   
--   <pre>
--   &gt;&gt;&gt; sample (dirichlet [0.1, 1, 10]) gen
--   [1.2375387187120799e-5,3.4952460651813816e-3,0.9964923785476316]
--   </pre>
--   
--   Note that all concentration parameters should be positive.
dirichlet :: (Traversable f, PrimMonad m) => f Double -> Prob m (f Double)

-- | The symmetric Dirichlet distribution with dimension <tt>n</tt>. The
--   provided concentration parameter is simply replicated <tt>n</tt>
--   times.
--   
--   Note that <tt>a</tt> should be positive.
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.
--   
--   Note that <tt>a</tt> should be positive, and that values close to 1
--   should be avoided as they are very computationally intensive.
--   
--   <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 probabilities.
--   
--   Note that the supplied container of probabilities must sum to 1.
categorical :: (Foldable f, PrimMonad m) => f Double -> Prob m Int

-- | The Bernoulli distribution with success probability <tt>p</tt>.
bernoulli :: PrimMonad m => Double -> Prob m Bool

-- | The binomial distribution with number of trials <tt>n</tt> and success
--   probability <tt>p</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; sample (binomial 10 0.3) gen
--   4
--   </pre>
binomial :: PrimMonad m => Int -> Double -> Prob m Int

-- | The negative binomial distribution with number of trials <tt>n</tt>
--   and success probability <tt>p</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; sample (negativeBinomial 10 0.3) gen
--   21
--   </pre>
negativeBinomial :: (PrimMonad m, Integral a) => a -> Double -> Prob m Int

-- | The multinomial distribution of <tt>n</tt> trials and category
--   probabilities <tt>ps</tt>.
--   
--   Note that <tt>ps</tt> is a vector of probabilities and should sum to
--   one.
multinomial :: (Foldable f, PrimMonad m) => Int -> f Double -> Prob m [Int]

-- | The Poisson distribution with rate parameter <tt>l</tt>.
--   
--   Note that <tt>l</tt> should be positive.
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)
