{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE DeriveDataTypeable, DeriveGeneric #-}
-- |
-- Module    : Statistics.Distribution.Lognormal
-- Copyright : (c) 2020 Ximin Luo
-- License   : BSD3
--
-- Maintainer  : infinity0@pwned.gg
-- Stability   : experimental
-- Portability : portable
--
-- The log normal distribution.  This is a continuous probability
-- distribution that describes data whose log is clustered around a
-- mean. For example, the multiplicative product of many independent
-- positive random variables.

module Statistics.Distribution.Lognormal
    (
      LognormalDistribution
      -- * Constructors
    , lognormalDistr
    , lognormalDistrErr
    , lognormalDistrMeanStddevErr
    , lognormalStandard
    ) where

import Data.Aeson            (FromJSON, ToJSON)
import Data.Binary           (Binary (..))
import Data.Data             (Data, Typeable)
import GHC.Generics          (Generic)
import Numeric.MathFunctions.Constants (m_huge, m_sqrt_2_pi)
import Numeric.SpecFunctions (expm1, log1p)
import qualified Data.Vector.Generic as G

import qualified Statistics.Distribution as D
import qualified Statistics.Distribution.Normal as N
import Statistics.Internal


-- | The lognormal distribution.
newtype LognormalDistribution = LND N.NormalDistribution
    deriving (LognormalDistribution -> LognormalDistribution -> Bool
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
/= :: LognormalDistribution -> LognormalDistribution -> Bool
$c/= :: LognormalDistribution -> LognormalDistribution -> Bool
== :: LognormalDistribution -> LognormalDistribution -> Bool
$c== :: LognormalDistribution -> LognormalDistribution -> Bool
Eq, Typeable, Typeable LognormalDistribution
LognormalDistribution -> DataType
LognormalDistribution -> Constr
(forall b. Data b => b -> b)
-> LognormalDistribution -> LognormalDistribution
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) -> LognormalDistribution -> u
forall u.
(forall d. Data d => d -> u) -> LognormalDistribution -> [u]
forall r r'.
(r -> r' -> r)
-> r -> (forall d. Data d => d -> r') -> LognormalDistribution -> r
forall r r'.
(r' -> r -> r)
-> r -> (forall d. Data d => d -> r') -> LognormalDistribution -> r
forall (m :: * -> *).
Monad m =>
(forall d. Data d => d -> m d)
-> LognormalDistribution -> m LognormalDistribution
forall (m :: * -> *).
MonadPlus m =>
(forall d. Data d => d -> m d)
-> LognormalDistribution -> m LognormalDistribution
forall (c :: * -> *).
(forall b r. Data b => c (b -> r) -> c r)
-> (forall r. r -> c r) -> Constr -> c LognormalDistribution
forall (c :: * -> *).
(forall d b. Data d => c (d -> b) -> d -> c b)
-> (forall g. g -> c g)
-> LognormalDistribution
-> c LognormalDistribution
forall (t :: * -> *) (c :: * -> *).
Typeable t =>
(forall d. Data d => c (t d)) -> Maybe (c LognormalDistribution)
forall (t :: * -> * -> *) (c :: * -> *).
Typeable t =>
(forall d e. (Data d, Data e) => c (t d e))
-> Maybe (c LognormalDistribution)
gmapMo :: forall (m :: * -> *).
MonadPlus m =>
(forall d. Data d => d -> m d)
-> LognormalDistribution -> m LognormalDistribution
$cgmapMo :: forall (m :: * -> *).
MonadPlus m =>
(forall d. Data d => d -> m d)
-> LognormalDistribution -> m LognormalDistribution
gmapMp :: forall (m :: * -> *).
MonadPlus m =>
(forall d. Data d => d -> m d)
-> LognormalDistribution -> m LognormalDistribution
$cgmapMp :: forall (m :: * -> *).
MonadPlus m =>
(forall d. Data d => d -> m d)
-> LognormalDistribution -> m LognormalDistribution
gmapM :: forall (m :: * -> *).
Monad m =>
(forall d. Data d => d -> m d)
-> LognormalDistribution -> m LognormalDistribution
$cgmapM :: forall (m :: * -> *).
Monad m =>
(forall d. Data d => d -> m d)
-> LognormalDistribution -> m LognormalDistribution
gmapQi :: forall u.
Int -> (forall d. Data d => d -> u) -> LognormalDistribution -> u
$cgmapQi :: forall u.
Int -> (forall d. Data d => d -> u) -> LognormalDistribution -> u
gmapQ :: forall u.
(forall d. Data d => d -> u) -> LognormalDistribution -> [u]
$cgmapQ :: forall u.
(forall d. Data d => d -> u) -> LognormalDistribution -> [u]
gmapQr :: forall r r'.
(r' -> r -> r)
-> r -> (forall d. Data d => d -> r') -> LognormalDistribution -> r
$cgmapQr :: forall r r'.
(r' -> r -> r)
-> r -> (forall d. Data d => d -> r') -> LognormalDistribution -> r
gmapQl :: forall r r'.
(r -> r' -> r)
-> r -> (forall d. Data d => d -> r') -> LognormalDistribution -> r
$cgmapQl :: forall r r'.
(r -> r' -> r)
-> r -> (forall d. Data d => d -> r') -> LognormalDistribution -> r
gmapT :: (forall b. Data b => b -> b)
-> LognormalDistribution -> LognormalDistribution
$cgmapT :: (forall b. Data b => b -> b)
-> LognormalDistribution -> LognormalDistribution
dataCast2 :: forall (t :: * -> * -> *) (c :: * -> *).
Typeable t =>
(forall d e. (Data d, Data e) => c (t d e))
-> Maybe (c LognormalDistribution)
$cdataCast2 :: forall (t :: * -> * -> *) (c :: * -> *).
Typeable t =>
(forall d e. (Data d, Data e) => c (t d e))
-> Maybe (c LognormalDistribution)
dataCast1 :: forall (t :: * -> *) (c :: * -> *).
Typeable t =>
(forall d. Data d => c (t d)) -> Maybe (c LognormalDistribution)
$cdataCast1 :: forall (t :: * -> *) (c :: * -> *).
Typeable t =>
(forall d. Data d => c (t d)) -> Maybe (c LognormalDistribution)
dataTypeOf :: LognormalDistribution -> DataType
$cdataTypeOf :: LognormalDistribution -> DataType
toConstr :: LognormalDistribution -> Constr
$ctoConstr :: LognormalDistribution -> Constr
gunfold :: forall (c :: * -> *).
(forall b r. Data b => c (b -> r) -> c r)
-> (forall r. r -> c r) -> Constr -> c LognormalDistribution
$cgunfold :: forall (c :: * -> *).
(forall b r. Data b => c (b -> r) -> c r)
-> (forall r. r -> c r) -> Constr -> c LognormalDistribution
gfoldl :: forall (c :: * -> *).
(forall d b. Data d => c (d -> b) -> d -> c b)
-> (forall g. g -> c g)
-> LognormalDistribution
-> c LognormalDistribution
$cgfoldl :: forall (c :: * -> *).
(forall d b. Data d => c (d -> b) -> d -> c b)
-> (forall g. g -> c g)
-> LognormalDistribution
-> c LognormalDistribution
Data, forall x. Rep LognormalDistribution x -> LognormalDistribution
forall x. LognormalDistribution -> Rep LognormalDistribution x
forall a.
(forall x. a -> Rep a x) -> (forall x. Rep a x -> a) -> Generic a
$cto :: forall x. Rep LognormalDistribution x -> LognormalDistribution
$cfrom :: forall x. LognormalDistribution -> Rep LognormalDistribution x
Generic)

instance Show LognormalDistribution where
  showsPrec :: Int -> LognormalDistribution -> ShowS
showsPrec Int
i (LND NormalDistribution
d) = forall a b. (Show a, Show b) => String -> a -> b -> Int -> ShowS
defaultShow2 String
"lognormalDistr" Double
m Double
s Int
i
   where
    m :: Double
m = forall d. Mean d => d -> Double
D.mean NormalDistribution
d
    s :: Double
s = forall d. Variance d => d -> Double
D.stdDev NormalDistribution
d
instance Read LognormalDistribution where
  readPrec :: ReadPrec LognormalDistribution
readPrec = forall a b r.
(Read a, Read b) =>
String -> (a -> b -> Maybe r) -> ReadPrec r
defaultReadPrecM2 String
"lognormalDistr" forall a b. (a -> b) -> a -> b
$
    (forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either (forall a b. a -> b -> a
const forall a. Maybe a
Nothing) forall a. a -> Maybe a
Just forall b c a. (b -> c) -> (a -> b) -> a -> c
.) forall b c a. (b -> c) -> (a -> b) -> a -> c
. Double -> Double -> Either String LognormalDistribution
lognormalDistrErr

instance ToJSON LognormalDistribution
instance FromJSON LognormalDistribution

instance Binary LognormalDistribution where
  put :: LognormalDistribution -> Put
put (LND NormalDistribution
d) = forall t. Binary t => t -> Put
put Double
m forall (m :: * -> *) a b. Monad m => m a -> m b -> m b
>> forall t. Binary t => t -> Put
put Double
s
   where
    m :: Double
m = forall d. Mean d => d -> Double
D.mean NormalDistribution
d
    s :: Double
s = forall d. Variance d => d -> Double
D.stdDev NormalDistribution
d
  get :: Get LognormalDistribution
get = do
    Double
m  <- forall t. Binary t => Get t
get
    Double
sd <- forall t. Binary t => Get t
get
    forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either forall (m :: * -> *) a. MonadFail m => String -> m a
fail forall (m :: * -> *) a. Monad m => a -> m a
return forall a b. (a -> b) -> a -> b
$ Double -> Double -> Either String LognormalDistribution
lognormalDistrErr Double
m Double
sd

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

instance D.ContDistr LognormalDistribution where
  logDensity :: LognormalDistribution -> Double -> Double
logDensity    = LognormalDistribution -> Double -> Double
logDensity
  quantile :: LognormalDistribution -> Double -> Double
quantile      = LognormalDistribution -> Double -> Double
quantile
  complQuantile :: LognormalDistribution -> Double -> Double
complQuantile = LognormalDistribution -> Double -> Double
complQuantile

instance D.MaybeMean LognormalDistribution where
  maybeMean :: LognormalDistribution -> 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.Mean LognormalDistribution where
  mean :: LognormalDistribution -> Double
mean (LND NormalDistribution
d) = forall a. Floating a => a -> a
exp (Double
m forall a. Num a => a -> a -> a
+ Double
v forall a. Fractional a => a -> a -> a
/ Double
2)
   where
    m :: Double
m = forall d. Mean d => d -> Double
D.mean NormalDistribution
d
    v :: Double
v = forall d. Variance d => d -> Double
D.variance NormalDistribution
d

instance D.MaybeVariance LognormalDistribution where
  maybeStdDev :: LognormalDistribution -> 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 :: LognormalDistribution -> 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.Variance LognormalDistribution where
  variance :: LognormalDistribution -> Double
variance (LND NormalDistribution
d) = forall a. Floating a => a -> a
expm1 Double
v forall a. Num a => a -> a -> a
* forall a. Floating a => a -> a
exp (Double
2 forall a. Num a => a -> a -> a
* Double
m forall a. Num a => a -> a -> a
+ Double
v)
   where
    m :: Double
m = forall d. Mean d => d -> Double
D.mean NormalDistribution
d
    v :: Double
v = forall d. Variance d => d -> Double
D.variance NormalDistribution
d

instance D.Entropy LognormalDistribution where
  entropy :: LognormalDistribution -> Double
entropy (LND NormalDistribution
d) = forall a. Floating a => a -> a -> a
logBase Double
2 (Double
s forall a. Num a => a -> a -> a
* forall a. Floating a => a -> a
exp (Double
m forall a. Num a => a -> a -> a
+ Double
0.5) forall a. Num a => a -> a -> a
* Double
m_sqrt_2_pi)
   where
    m :: Double
m = forall d. Mean d => d -> Double
D.mean NormalDistribution
d
    s :: Double
s = forall d. Variance d => d -> Double
D.stdDev NormalDistribution
d

instance D.MaybeEntropy LognormalDistribution where
  maybeEntropy :: LognormalDistribution -> 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

instance D.ContGen LognormalDistribution where
  genContVar :: forall g (m :: * -> *).
StatefulGen g m =>
LognormalDistribution -> g -> m Double
genContVar LognormalDistribution
d = forall d g (m :: * -> *).
(ContDistr d, StatefulGen g m) =>
d -> g -> m Double
D.genContinuous LognormalDistribution
d

-- | Standard log normal distribution with mu 0 and sigma 1.
--
-- Mean is @sqrt e@ and variance is @(e - 1) * e@.
lognormalStandard :: LognormalDistribution
lognormalStandard :: LognormalDistribution
lognormalStandard = NormalDistribution -> LognormalDistribution
LND NormalDistribution
N.standard

-- | Create log normal distribution from parameters.
lognormalDistr
  :: Double            -- ^ Mu
  -> Double            -- ^ Sigma
  -> LognormalDistribution
lognormalDistr :: Double -> Double -> LognormalDistribution
lognormalDistr Double
mu Double
sig = forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either forall a. HasCallStack => String -> a
error forall a. a -> a
id forall a b. (a -> b) -> a -> b
$ Double -> Double -> Either String LognormalDistribution
lognormalDistrErr Double
mu Double
sig

-- | Create log normal distribution from parameters.
lognormalDistrErr
  :: Double            -- ^ Mu
  -> Double            -- ^ Sigma
  -> Either String LognormalDistribution
lognormalDistrErr :: Double -> Double -> Either String LognormalDistribution
lognormalDistrErr Double
mu Double
sig
  | Double
sig forall a. Ord a => a -> a -> Bool
>= forall a. Floating a => a -> a
sqrt (forall a. Floating a => a -> a
log Double
m_huge forall a. Num a => a -> a -> a
- Double
2 forall a. Num a => a -> a -> a
* Double
mu) = forall a b. a -> Either a b
Left forall a b. (a -> b) -> a -> b
$ Double -> Double -> String
errMsg Double
mu Double
sig
  | Bool
otherwise = NormalDistribution -> LognormalDistribution
LND forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> Double -> Double -> Either String NormalDistribution
N.normalDistrErr Double
mu Double
sig

errMsg :: Double -> Double -> String
errMsg :: Double -> Double -> String
errMsg Double
mu Double
sig =
  String
"Statistics.Distribution.Lognormal.lognormalDistr: sigma must be > 0 && < "
    forall a. [a] -> [a] -> [a]
++ forall a. Show a => a -> String
show Double
lim forall a. [a] -> [a] -> [a]
++ String
". Got " forall a. [a] -> [a] -> [a]
++ forall a. Show a => a -> String
show Double
sig
  where lim :: Double
lim = forall a. Floating a => a -> a
sqrt (forall a. Floating a => a -> a
log Double
m_huge forall a. Num a => a -> a -> a
- Double
2 forall a. Num a => a -> a -> a
* Double
mu)

-- | Create log normal distribution from mean and standard deviation.
lognormalDistrMeanStddevErr
  :: Double            -- ^ Mu
  -> Double            -- ^ Sigma
  -> Either String LognormalDistribution
lognormalDistrMeanStddevErr :: Double -> Double -> Either String LognormalDistribution
lognormalDistrMeanStddevErr Double
m Double
sd = NormalDistribution -> LognormalDistribution
LND forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> Double -> Double -> Either String NormalDistribution
N.normalDistrErr Double
mu Double
sig
  where r :: Double
r = Double
sd forall a. Fractional a => a -> a -> a
/ Double
m
        sig2 :: Double
sig2 = forall a. Floating a => a -> a
log1p (Double
r forall a. Num a => a -> a -> a
* Double
r)
        sig :: Double
sig = forall a. Floating a => a -> a
sqrt Double
sig2
        mu :: Double
mu = forall a. Floating a => a -> a
log Double
m forall a. Num a => a -> a -> a
- Double
sig2 forall a. Fractional a => a -> a -> a
/ Double
2

-- | Variance is estimated using maximum likelihood method
--   (biased estimation) over the log of the data.
--
--   Returns @Nothing@ if sample contains less than one element or
--   variance is zero (all elements are equal)
instance D.FromSample LognormalDistribution Double where
  fromSample :: forall (v :: * -> *).
Vector v Double =>
v Double -> Maybe LognormalDistribution
fromSample = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap NormalDistribution -> LognormalDistribution
LND forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall d a (v :: * -> *).
(FromSample d a, Vector v a) =>
v a -> Maybe d
D.fromSample forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (v :: * -> *) a b.
(Vector v a, Vector v b) =>
(a -> b) -> v a -> v b
G.map forall a. Floating a => a -> a
log

logDensity :: LognormalDistribution -> Double -> Double
logDensity :: LognormalDistribution -> Double -> Double
logDensity (LND NormalDistribution
d) Double
x
  | Double
x forall a. Ord a => a -> a -> Bool
> Double
0 = let lx :: Double
lx = forall a. Floating a => a -> a
log Double
x in forall d. ContDistr d => d -> Double -> Double
D.logDensity NormalDistribution
d Double
lx forall a. Num a => a -> a -> a
- Double
lx
  | Bool
otherwise = Double
0

cumulative :: LognormalDistribution -> Double -> Double
cumulative :: LognormalDistribution -> Double -> Double
cumulative (LND NormalDistribution
d) Double
x
  | Double
x forall a. Ord a => a -> a -> Bool
> Double
0 = forall d. Distribution d => d -> Double -> Double
D.cumulative NormalDistribution
d forall a b. (a -> b) -> a -> b
$ forall a. Floating a => a -> a
log Double
x
  | Bool
otherwise = Double
0

complCumulative :: LognormalDistribution -> Double -> Double
complCumulative :: LognormalDistribution -> Double -> Double
complCumulative (LND NormalDistribution
d) Double
x
  | Double
x forall a. Ord a => a -> a -> Bool
> Double
0 = forall d. Distribution d => d -> Double -> Double
D.complCumulative NormalDistribution
d forall a b. (a -> b) -> a -> b
$ forall a. Floating a => a -> a
log Double
x
  | Bool
otherwise = Double
1

quantile :: LognormalDistribution -> Double -> Double
quantile :: LognormalDistribution -> Double -> Double
quantile (LND NormalDistribution
d) = forall a. Floating a => a -> a
exp forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall d. ContDistr d => d -> Double -> Double
D.quantile NormalDistribution
d

complQuantile :: LognormalDistribution -> Double -> Double
complQuantile :: LognormalDistribution -> Double -> Double
complQuantile (LND NormalDistribution
d) = forall a. Floating a => a -> a
exp forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall d. ContDistr d => d -> Double -> Double
D.complQuantile NormalDistribution
d