{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE PatternGuards     #-}
{-# LANGUAGE DeriveDataTypeable, DeriveGeneric #-}
-- |
-- Module    : Statistics.Distribution.Binomial
-- Copyright : (c) 2009 Bryan O'Sullivan
-- License   : BSD3
--
-- Maintainer  : bos@serpentine.com
-- Stability   : experimental
-- Portability : portable
--
-- The binomial distribution.  This is the discrete probability
-- distribution of the number of successes in a sequence of /n/
-- independent yes\/no experiments, each of which yields success with
-- probability /p/.

module Statistics.Distribution.Binomial
    (
      BinomialDistribution
    -- * Constructors
    , binomial
    , binomialE
    -- * Accessors
    , bdTrials
    , bdProbability
    ) where

import Control.Applicative
import Data.Aeson            (FromJSON(..), ToJSON, Value(..), (.:))
import Data.Binary           (Binary(..))
import Data.Data             (Data, Typeable)
import GHC.Generics          (Generic)
import Numeric.SpecFunctions           (choose,logChoose,incompleteBeta,log1p)
import Numeric.MathFunctions.Constants (m_epsilon,m_tiny)

import qualified Statistics.Distribution as D
import qualified Statistics.Distribution.Poisson.Internal as I
import Statistics.Internal


-- | The binomial distribution.
data BinomialDistribution = BD {
      BinomialDistribution -> Int
bdTrials      :: {-# UNPACK #-} !Int
    -- ^ Number of trials.
    , BinomialDistribution -> Double
bdProbability :: {-# UNPACK #-} !Double
    -- ^ Probability.
    } deriving (BinomialDistribution -> BinomialDistribution -> Bool
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
/= :: BinomialDistribution -> BinomialDistribution -> Bool
$c/= :: BinomialDistribution -> BinomialDistribution -> Bool
== :: BinomialDistribution -> BinomialDistribution -> Bool
$c== :: BinomialDistribution -> BinomialDistribution -> Bool
Eq, Typeable, Typeable BinomialDistribution
BinomialDistribution -> DataType
BinomialDistribution -> Constr
(forall b. Data b => b -> b)
-> BinomialDistribution -> BinomialDistribution
forall a.
Typeable a
-> (forall (c :: * -> *).
    (forall d b. Data d => c (d -> b) -> d -> c b)
    -> (forall g. g -> c g) -> a -> c a)
-> (forall (c :: * -> *).
    (forall b r. Data b => c (b -> r) -> c r)
    -> (forall r. r -> c r) -> Constr -> c a)
-> (a -> Constr)
-> (a -> DataType)
-> (forall (t :: * -> *) (c :: * -> *).
    Typeable t =>
    (forall d. Data d => c (t d)) -> Maybe (c a))
-> (forall (t :: * -> * -> *) (c :: * -> *).
    Typeable t =>
    (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c a))
-> ((forall b. Data b => b -> b) -> a -> a)
-> (forall r r'.
    (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> a -> r)
-> (forall r r'.
    (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> a -> r)
-> (forall u. (forall d. Data d => d -> u) -> a -> [u])
-> (forall u. Int -> (forall d. Data d => d -> u) -> a -> u)
-> (forall (m :: * -> *).
    Monad m =>
    (forall d. Data d => d -> m d) -> a -> m a)
-> (forall (m :: * -> *).
    MonadPlus m =>
    (forall d. Data d => d -> m d) -> a -> m a)
-> (forall (m :: * -> *).
    MonadPlus m =>
    (forall d. Data d => d -> m d) -> a -> m a)
-> Data a
forall u.
Int -> (forall d. Data d => d -> u) -> BinomialDistribution -> u
forall u.
(forall d. Data d => d -> u) -> BinomialDistribution -> [u]
forall r r'.
(r -> r' -> r)
-> r -> (forall d. Data d => d -> r') -> BinomialDistribution -> r
forall r r'.
(r' -> r -> r)
-> r -> (forall d. Data d => d -> r') -> BinomialDistribution -> r
forall (m :: * -> *).
Monad m =>
(forall d. Data d => d -> m d)
-> BinomialDistribution -> m BinomialDistribution
forall (m :: * -> *).
MonadPlus m =>
(forall d. Data d => d -> m d)
-> BinomialDistribution -> m BinomialDistribution
forall (c :: * -> *).
(forall b r. Data b => c (b -> r) -> c r)
-> (forall r. r -> c r) -> Constr -> c BinomialDistribution
forall (c :: * -> *).
(forall d b. Data d => c (d -> b) -> d -> c b)
-> (forall g. g -> c g)
-> BinomialDistribution
-> c BinomialDistribution
forall (t :: * -> *) (c :: * -> *).
Typeable t =>
(forall d. Data d => c (t d)) -> Maybe (c BinomialDistribution)
forall (t :: * -> * -> *) (c :: * -> *).
Typeable t =>
(forall d e. (Data d, Data e) => c (t d e))
-> Maybe (c BinomialDistribution)
gmapMo :: forall (m :: * -> *).
MonadPlus m =>
(forall d. Data d => d -> m d)
-> BinomialDistribution -> m BinomialDistribution
$cgmapMo :: forall (m :: * -> *).
MonadPlus m =>
(forall d. Data d => d -> m d)
-> BinomialDistribution -> m BinomialDistribution
gmapMp :: forall (m :: * -> *).
MonadPlus m =>
(forall d. Data d => d -> m d)
-> BinomialDistribution -> m BinomialDistribution
$cgmapMp :: forall (m :: * -> *).
MonadPlus m =>
(forall d. Data d => d -> m d)
-> BinomialDistribution -> m BinomialDistribution
gmapM :: forall (m :: * -> *).
Monad m =>
(forall d. Data d => d -> m d)
-> BinomialDistribution -> m BinomialDistribution
$cgmapM :: forall (m :: * -> *).
Monad m =>
(forall d. Data d => d -> m d)
-> BinomialDistribution -> m BinomialDistribution
gmapQi :: forall u.
Int -> (forall d. Data d => d -> u) -> BinomialDistribution -> u
$cgmapQi :: forall u.
Int -> (forall d. Data d => d -> u) -> BinomialDistribution -> u
gmapQ :: forall u.
(forall d. Data d => d -> u) -> BinomialDistribution -> [u]
$cgmapQ :: forall u.
(forall d. Data d => d -> u) -> BinomialDistribution -> [u]
gmapQr :: forall r r'.
(r' -> r -> r)
-> r -> (forall d. Data d => d -> r') -> BinomialDistribution -> r
$cgmapQr :: forall r r'.
(r' -> r -> r)
-> r -> (forall d. Data d => d -> r') -> BinomialDistribution -> r
gmapQl :: forall r r'.
(r -> r' -> r)
-> r -> (forall d. Data d => d -> r') -> BinomialDistribution -> r
$cgmapQl :: forall r r'.
(r -> r' -> r)
-> r -> (forall d. Data d => d -> r') -> BinomialDistribution -> r
gmapT :: (forall b. Data b => b -> b)
-> BinomialDistribution -> BinomialDistribution
$cgmapT :: (forall b. Data b => b -> b)
-> BinomialDistribution -> BinomialDistribution
dataCast2 :: forall (t :: * -> * -> *) (c :: * -> *).
Typeable t =>
(forall d e. (Data d, Data e) => c (t d e))
-> Maybe (c BinomialDistribution)
$cdataCast2 :: forall (t :: * -> * -> *) (c :: * -> *).
Typeable t =>
(forall d e. (Data d, Data e) => c (t d e))
-> Maybe (c BinomialDistribution)
dataCast1 :: forall (t :: * -> *) (c :: * -> *).
Typeable t =>
(forall d. Data d => c (t d)) -> Maybe (c BinomialDistribution)
$cdataCast1 :: forall (t :: * -> *) (c :: * -> *).
Typeable t =>
(forall d. Data d => c (t d)) -> Maybe (c BinomialDistribution)
dataTypeOf :: BinomialDistribution -> DataType
$cdataTypeOf :: BinomialDistribution -> DataType
toConstr :: BinomialDistribution -> Constr
$ctoConstr :: BinomialDistribution -> Constr
gunfold :: forall (c :: * -> *).
(forall b r. Data b => c (b -> r) -> c r)
-> (forall r. r -> c r) -> Constr -> c BinomialDistribution
$cgunfold :: forall (c :: * -> *).
(forall b r. Data b => c (b -> r) -> c r)
-> (forall r. r -> c r) -> Constr -> c BinomialDistribution
gfoldl :: forall (c :: * -> *).
(forall d b. Data d => c (d -> b) -> d -> c b)
-> (forall g. g -> c g)
-> BinomialDistribution
-> c BinomialDistribution
$cgfoldl :: forall (c :: * -> *).
(forall d b. Data d => c (d -> b) -> d -> c b)
-> (forall g. g -> c g)
-> BinomialDistribution
-> c BinomialDistribution
Data, forall x. Rep BinomialDistribution x -> BinomialDistribution
forall x. BinomialDistribution -> Rep BinomialDistribution x
forall a.
(forall x. a -> Rep a x) -> (forall x. Rep a x -> a) -> Generic a
$cto :: forall x. Rep BinomialDistribution x -> BinomialDistribution
$cfrom :: forall x. BinomialDistribution -> Rep BinomialDistribution x
Generic)

instance Show BinomialDistribution where
  showsPrec :: Int -> BinomialDistribution -> ShowS
showsPrec Int
i (BD Int
n Double
p) = forall a b. (Show a, Show b) => [Char] -> a -> b -> Int -> ShowS
defaultShow2 [Char]
"binomial" Int
n Double
p Int
i
instance Read BinomialDistribution where
  readPrec :: ReadPrec BinomialDistribution
readPrec = forall a b r.
(Read a, Read b) =>
[Char] -> (a -> b -> Maybe r) -> ReadPrec r
defaultReadPrecM2 [Char]
"binomial" Int -> Double -> Maybe BinomialDistribution
binomialE

instance ToJSON BinomialDistribution
instance FromJSON BinomialDistribution where
  parseJSON :: Value -> Parser BinomialDistribution
parseJSON (Object Object
v) = do
    Int
n <- Object
v forall a. FromJSON a => Object -> Key -> Parser a
.: Key
"bdTrials"
    Double
p <- Object
v forall a. FromJSON a => Object -> Key -> Parser a
.: Key
"bdProbability"
    forall b a. b -> (a -> b) -> Maybe a -> b
maybe (forall (m :: * -> *) a. MonadFail m => [Char] -> m a
fail forall a b. (a -> b) -> a -> b
$ Int -> Double -> [Char]
errMsg Int
n Double
p) forall (m :: * -> *) a. Monad m => a -> m a
return forall a b. (a -> b) -> a -> b
$ Int -> Double -> Maybe BinomialDistribution
binomialE Int
n Double
p
  parseJSON Value
_ = forall (f :: * -> *) a. Alternative f => f a
empty

instance Binary BinomialDistribution where
  put :: BinomialDistribution -> Put
put (BD Int
x Double
y) = forall t. Binary t => t -> Put
put Int
x forall (m :: * -> *) a b. Monad m => m a -> m b -> m b
>> forall t. Binary t => t -> Put
put Double
y
  get :: Get BinomialDistribution
get = do
    Int
n <- forall t. Binary t => Get t
get
    Double
p <- forall t. Binary t => Get t
get
    forall b a. b -> (a -> b) -> Maybe a -> b
maybe (forall (m :: * -> *) a. MonadFail m => [Char] -> m a
fail forall a b. (a -> b) -> a -> b
$ Int -> Double -> [Char]
errMsg Int
n Double
p) forall (m :: * -> *) a. Monad m => a -> m a
return forall a b. (a -> b) -> a -> b
$ Int -> Double -> Maybe BinomialDistribution
binomialE Int
n Double
p



instance D.Distribution BinomialDistribution where
    cumulative :: BinomialDistribution -> Double -> Double
cumulative = BinomialDistribution -> Double -> Double
cumulative
    complCumulative :: BinomialDistribution -> Double -> Double
complCumulative = BinomialDistribution -> Double -> Double
complCumulative

instance D.DiscreteDistr BinomialDistribution where
    probability :: BinomialDistribution -> Int -> Double
probability    = BinomialDistribution -> Int -> Double
probability
    logProbability :: BinomialDistribution -> Int -> Double
logProbability = BinomialDistribution -> Int -> Double
logProbability

instance D.Mean BinomialDistribution where
    mean :: BinomialDistribution -> Double
mean = BinomialDistribution -> Double
mean

instance D.Variance BinomialDistribution where
    variance :: BinomialDistribution -> Double
variance = BinomialDistribution -> Double
variance

instance D.MaybeMean BinomialDistribution where
    maybeMean :: BinomialDistribution -> Maybe Double
maybeMean = forall a. a -> Maybe a
Just forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall d. Mean d => d -> Double
D.mean

instance D.MaybeVariance BinomialDistribution where
    maybeStdDev :: BinomialDistribution -> Maybe Double
maybeStdDev   = forall a. a -> Maybe a
Just forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall d. Variance d => d -> Double
D.stdDev
    maybeVariance :: BinomialDistribution -> Maybe Double
maybeVariance = forall a. a -> Maybe a
Just forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall d. Variance d => d -> Double
D.variance

instance D.Entropy BinomialDistribution where
  entropy :: BinomialDistribution -> Double
entropy (BD Int
n Double
p)
    | Int
n forall a. Eq a => a -> a -> Bool
== Int
0 = Double
0
    | Int
n forall a. Ord a => a -> a -> Bool
<= Int
100 = BinomialDistribution -> Double
directEntropy (Int -> Double -> BinomialDistribution
BD Int
n Double
p)
    | Bool
otherwise = Double -> Double
I.poissonEntropy (forall a b. (Integral a, Num b) => a -> b
fromIntegral Int
n forall a. Num a => a -> a -> a
* Double
p)

instance D.MaybeEntropy BinomialDistribution where
  maybeEntropy :: BinomialDistribution -> Maybe Double
maybeEntropy = forall a. a -> Maybe a
Just forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall d. Entropy d => d -> Double
D.entropy

-- This could be slow for big n
probability :: BinomialDistribution -> Int -> Double
probability :: BinomialDistribution -> Int -> Double
probability (BD Int
n Double
p) Int
k
  | Int
k forall a. Ord a => a -> a -> Bool
< Int
0 Bool -> Bool -> Bool
|| Int
k forall a. Ord a => a -> a -> Bool
> Int
n = Double
0
  | Int
n forall a. Eq a => a -> a -> Bool
== Int
0         = Double
1
    -- choose could overflow Double for n >= 1030 so we switch to
    -- log-domain to calculate probability
    --
    -- We also want to avoid underflow when computing p^k &
    -- (1-p)^(n-k).
  | Int
n forall a. Ord a => a -> a -> Bool
< Int
1000
  , Double
pK  forall a. Ord a => a -> a -> Bool
>= Double
m_tiny
  , Double
pNK forall a. Ord a => a -> a -> Bool
>= Double
m_tiny = Int -> Int -> Double
choose Int
n Int
k forall a. Num a => a -> a -> a
* Double
pK forall a. Num a => a -> a -> a
* Double
pNK
  | Bool
otherwise     = forall a. Floating a => a -> a
exp forall a b. (a -> b) -> a -> b
$ Int -> Int -> Double
logChoose Int
n Int
k forall a. Num a => a -> a -> a
+ forall a. Floating a => a -> a
log Double
p forall a. Num a => a -> a -> a
* Double
k' forall a. Num a => a -> a -> a
+ forall a. Floating a => a -> a
log1p (-Double
p) forall a. Num a => a -> a -> a
* Double
nk'
  where
    pK :: Double
pK  = Double
pforall a b. (Num a, Integral b) => a -> b -> a
^Int
k
    pNK :: Double
pNK = (Double
1forall a. Num a => a -> a -> a
-Double
p)forall a b. (Num a, Integral b) => a -> b -> a
^(Int
nforall a. Num a => a -> a -> a
-Int
k)
    k' :: Double
k'  = forall a b. (Integral a, Num b) => a -> b
fromIntegral Int
k
    nk' :: Double
nk' = forall a b. (Integral a, Num b) => a -> b
fromIntegral forall a b. (a -> b) -> a -> b
$ Int
n forall a. Num a => a -> a -> a
- Int
k

logProbability :: BinomialDistribution -> Int -> Double
logProbability :: BinomialDistribution -> Int -> Double
logProbability (BD Int
n Double
p) Int
k
  | Int
k forall a. Ord a => a -> a -> Bool
< Int
0 Bool -> Bool -> Bool
|| Int
k forall a. Ord a => a -> a -> Bool
> Int
n          = (-Double
1)forall a. Fractional a => a -> a -> a
/Double
0
  | Int
n forall a. Eq a => a -> a -> Bool
== Int
0                  = Double
0
  | Bool
otherwise               = Int -> Int -> Double
logChoose Int
n Int
k forall a. Num a => a -> a -> a
+ forall a. Floating a => a -> a
log Double
p forall a. Num a => a -> a -> a
* Double
k' forall a. Num a => a -> a -> a
+ forall a. Floating a => a -> a
log1p (-Double
p) forall a. Num a => a -> a -> a
* Double
nk'
  where
    k' :: Double
k'  = forall a b. (Integral a, Num b) => a -> b
fromIntegral   Int
k
    nk' :: Double
nk' = forall a b. (Integral a, Num b) => a -> b
fromIntegral forall a b. (a -> b) -> a -> b
$ Int
n forall a. Num a => a -> a -> a
- Int
k

cumulative :: BinomialDistribution -> Double -> Double
cumulative :: BinomialDistribution -> Double -> Double
cumulative (BD Int
n Double
p) Double
x
  | forall a. RealFloat a => a -> Bool
isNaN Double
x      = forall a. HasCallStack => [Char] -> a
error [Char]
"Statistics.Distribution.Binomial.cumulative: NaN input"
  | forall a. RealFloat a => a -> Bool
isInfinite Double
x = if Double
x forall a. Ord a => a -> a -> Bool
> Double
0 then Double
1 else Double
0
  | Int
k forall a. Ord a => a -> a -> Bool
<  Int
0       = Double
0
  | Int
k forall a. Ord a => a -> a -> Bool
>= Int
n       = Double
1
  | Bool
otherwise    = Double -> Double -> Double -> Double
incompleteBeta (forall a b. (Integral a, Num b) => a -> b
fromIntegral (Int
nforall a. Num a => a -> a -> a
-Int
k)) (forall a b. (Integral a, Num b) => a -> b
fromIntegral (Int
kforall a. Num a => a -> a -> a
+Int
1)) (Double
1 forall a. Num a => a -> a -> a
- Double
p)
  where
    k :: Int
k = forall a b. (RealFrac a, Integral b) => a -> b
floor Double
x

complCumulative :: BinomialDistribution -> Double -> Double
complCumulative :: BinomialDistribution -> Double -> Double
complCumulative (BD Int
n Double
p) Double
x
  | forall a. RealFloat a => a -> Bool
isNaN Double
x      = forall a. HasCallStack => [Char] -> a
error [Char]
"Statistics.Distribution.Binomial.complCumulative: NaN input"
  | forall a. RealFloat a => a -> Bool
isInfinite Double
x = if Double
x forall a. Ord a => a -> a -> Bool
> Double
0 then Double
0 else Double
1
  | Int
k forall a. Ord a => a -> a -> Bool
<  Int
0       = Double
1
  | Int
k forall a. Ord a => a -> a -> Bool
>= Int
n       = Double
0
  | Bool
otherwise    = Double -> Double -> Double -> Double
incompleteBeta (forall a b. (Integral a, Num b) => a -> b
fromIntegral (Int
kforall a. Num a => a -> a -> a
+Int
1)) (forall a b. (Integral a, Num b) => a -> b
fromIntegral (Int
nforall a. Num a => a -> a -> a
-Int
k)) Double
p
  where
    k :: Int
k = forall a b. (RealFrac a, Integral b) => a -> b
floor Double
x

mean :: BinomialDistribution -> Double
mean :: BinomialDistribution -> Double
mean (BD Int
n Double
p) = forall a b. (Integral a, Num b) => a -> b
fromIntegral Int
n forall a. Num a => a -> a -> a
* Double
p

variance :: BinomialDistribution -> Double
variance :: BinomialDistribution -> Double
variance (BD Int
n Double
p) = forall a b. (Integral a, Num b) => a -> b
fromIntegral Int
n forall a. Num a => a -> a -> a
* Double
p forall a. Num a => a -> a -> a
* (Double
1 forall a. Num a => a -> a -> a
- Double
p)

directEntropy :: BinomialDistribution -> Double
directEntropy :: BinomialDistribution -> Double
directEntropy d :: BinomialDistribution
d@(BD Int
n Double
_) =
  forall a. Num a => a -> a
negate forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (t :: * -> *) a. (Foldable t, Num a) => t a -> a
sum forall a b. (a -> b) -> a -> b
$
  forall a. (a -> Bool) -> [a] -> [a]
takeWhile (forall a. Ord a => a -> a -> Bool
< forall a. Num a => a -> a
negate Double
m_epsilon) forall a b. (a -> b) -> a -> b
$
  forall a. (a -> Bool) -> [a] -> [a]
dropWhile (Bool -> Bool
not forall b c a. (b -> c) -> (a -> b) -> a -> c
. (forall a. Ord a => a -> a -> Bool
< forall a. Num a => a -> a
negate Double
m_epsilon)) forall a b. (a -> b) -> a -> b
$
  [ let x :: Double
x = BinomialDistribution -> Int -> Double
probability BinomialDistribution
d Int
k in Double
x forall a. Num a => a -> a -> a
* forall a. Floating a => a -> a
log Double
x | Int
k <- [Int
0..Int
n]]

-- | Construct binomial distribution. Number of trials must be
--   non-negative and probability must be in [0,1] range
binomial :: Int                 -- ^ Number of trials.
         -> Double              -- ^ Probability.
         -> BinomialDistribution
binomial :: Int -> Double -> BinomialDistribution
binomial Int
n Double
p = forall b a. b -> (a -> b) -> Maybe a -> b
maybe (forall a. HasCallStack => [Char] -> a
error forall a b. (a -> b) -> a -> b
$ Int -> Double -> [Char]
errMsg Int
n Double
p) forall a. a -> a
id forall a b. (a -> b) -> a -> b
$ Int -> Double -> Maybe BinomialDistribution
binomialE Int
n Double
p

-- | Construct binomial distribution. Number of trials must be
--   non-negative and probability must be in [0,1] range
binomialE :: Int                 -- ^ Number of trials.
          -> Double              -- ^ Probability.
          -> Maybe BinomialDistribution
binomialE :: Int -> Double -> Maybe BinomialDistribution
binomialE Int
n Double
p
  | Int
n forall a. Ord a => a -> a -> Bool
< Int
0            = forall a. Maybe a
Nothing
  | Double
p forall a. Ord a => a -> a -> Bool
>= Double
0 Bool -> Bool -> Bool
&& Double
p forall a. Ord a => a -> a -> Bool
<= Double
1 = forall a. a -> Maybe a
Just (Int -> Double -> BinomialDistribution
BD Int
n Double
p)
  | Bool
otherwise        = forall a. Maybe a
Nothing

errMsg :: Int -> Double -> String
errMsg :: Int -> Double -> [Char]
errMsg Int
n Double
p
  = [Char]
"Statistics.Distribution.Binomial.binomial: n=" forall a. [a] -> [a] -> [a]
++ forall a. Show a => a -> [Char]
show Int
n
  forall a. [a] -> [a] -> [a]
++ [Char]
" p=" forall a. [a] -> [a] -> [a]
++ forall a. Show a => a -> [Char]
show Double
p forall a. [a] -> [a] -> [a]
++ [Char]
"but n>=0 and p in [0,1]"