Commits

Aleksey Khudyakov committed 2e27be8

Doc for bin

Comments (0)

Files changed (1)

Data/Histogram/Bin.hs

 -- Type classes
 ----------------------------------------------------------------
 
--- | This type represent some abstract data binning algorithms.
---   It maps some value to integer indices.
+-- | This type represent some abstract data binning algorithms. Such
+--   algorithm maps sets of values to integer indices.
 --
 --   Following invariant is expected to hold:
 --
 class Bin b where
   -- | Type of value to bin
   type BinValue b
-  -- | Convert from value to index. No bound checking
-  --   performed. Function must not fail for any input.
+  -- | Convert from value to index. Function must not fail for any
+  --   input and should produce out of range indices for invalid input.
   toIndex :: b -> BinValue b -> Int
   -- | Convert from index to value. Returned value should correspond
-  --   to "center" of bin. Definition of center is left for definition
+  --   to center of bin. Definition of center is left for definition
   --   of instance. Funtion may fail for invalid indices but
   --   encouraged not to do so.
   fromIndex :: b -> Int -> BinValue b
 ----------------------------------------------------------------
 -- | Simple binning algorithm which map continous range of bins onto
 -- indices. Each number correcsponds to different bin
+--
+-- 1. Lower bound (inclusive)
+--
+-- 2. Upper bound (inclusive)
 data BinI = BinI
             {-# UNPACK #-} !Int -- Lower bound (inclusive)
             {-# UNPACK #-} !Int -- Upper bound (inclusive)
 ----------------------------------------------------------------
 
 -- | Integer bins with size which differ from 1.
+--
+-- 1. Low bound
+--
+-- 2. Bin size
+--
+-- 3. Number of bins
 data BinInt = BinInt
               {-# UNPACK #-} !Int -- Low bound
               {-# UNPACK #-} !Int -- Bin size
 --
 -- Note that due to GHC bug #2271 this toIndex is really slow (20x
 -- slowdown with respect to BinD) and use of BinD is recommended
+--
+-- 1. Lower bound
+--
+-- 2. Size of bin
+--
+-- 3. Number of bins
 data BinF f = BinF {-# UNPACK #-} !f   -- Lower bound
                    {-# UNPACK #-} !f   -- Size of bin
                    {-# UNPACK #-} !Int -- Number of bins
 ----------------------------------------------------------------
 -- | Floaintg point bins with equal sizes. If you work with Doubles
 -- this data type should be used instead of BinF.
+--
+-- 1. Lower bound
+--
+-- 2. Size of bin
+--
+-- 3. Number of bins
 data BinD = BinD {-# UNPACK #-} !Double -- Lower bound
                  {-# UNPACK #-} !Double -- Size of bin
                  {-# UNPACK #-} !Int    -- Number of bins
 -- Log-scale bin
 ----------------------------------------------------------------
 -- | Logarithmic scale bins.
+--
+-- 1. Lower bound
+--
+-- 2. Upper bound
+--
+-- 2. Increment ratio
+--
+-- 3. Number of bins
 data LogBinD = LogBinD
                Double -- Low border
                Double -- Hi border