Data.Histogram.Generic

Generic immutable histograms.

Immutable histograms

data Histogram v bin a

Immutable histogram. A histogram consists of a binning algorithm, an optional number of under- and overflows, and data. Type parameters have following meaning:

v

type of vector used to store bin content.

bin

binning. It should be instance of Bin. Check that type class description for details.

a

type of bin content.

Instances

Functor v => Functor (Histogram v bin)

If vector is a functor then histogram is functor as well

Methods

fmap :: (a -> b) -> Histogram v bin a -> Histogram v bin b

(<$) :: a -> Histogram v bin b -> Histogram v bin a

(Eq (v a), Eq a, Eq bin) => Eq (Histogram v bin a)

Methods

(==) :: Histogram v bin a -> Histogram v bin a -> Bool

(/=) :: Histogram v bin a -> Histogram v bin a -> Bool

(Show a, Show (BinValue bin), Show bin, Bin bin, Vector v a) => Show (Histogram v bin a)

Methods

showsPrec :: Int -> Histogram v bin a -> ShowS

show :: Histogram v bin a -> String

showList :: [Histogram v bin a] -> ShowS

(NFData a, NFData bin, NFData (v a)) => NFData (Histogram v bin a)

Vector do not supply NFData instance so let just seq it and hope it's enough. Should be enough for unboxed vectors.

Methods

rnf :: Histogram v bin a -> ()

module Data.Histogram.Bin

Constructors

histogram :: (Vector v a, Bin bin) => bin -> v a -> Histogram v bin a

Create histogram from binning algorithm and a vector with data. Overflows are set to Nothing.

Number of bins and vector size must match.

histogramUO :: (Vector v a, Bin bin) => bin -> Maybe (a, a) -> v a -> Histogram v bin a

Create histogram from binning algorithm and vector with data.

Number of bins and vector size must match.

Conversion to other data types

asList :: (Vector v a, Bin bin) => Histogram v bin a -> [(BinValue bin, a)]

Convert histogram data to list.

asVector :: (Bin bin, Vector v a, Vector v (BinValue bin, a)) => Histogram v bin a -> v (BinValue bin, a)

Convert histogram data to vector

Serialization to strings

Show instance is abused for serialization and produces human readable data like that:

# Histogram
# Underflows = 0
# Overflows  = 88
# BinI
# Low  = 0
# High = 9
0       99
1       91
2       95
3       81
4       92
5       105
6       90
7       79
8       91
9       89

It could be deserialize using readHistogram function. Read instance could be provided as well but it turned out to be impractically slow.

Serialization with cereal package is provided by histogram-fill-cereal

readHistogram :: (Read bin, Read a, Bin bin, Vector v a) => String -> Histogram v bin a

Convert a String to a histogram. Histogram does not have a Read instance because of the slowness of ReadP

readFileHistogram :: (Read bin, Read a, Bin bin, Vector v a) => FilePath -> IO (Histogram v bin a)

Read histogram from file.

Accessors

bins :: Histogram v bin a -> bin

Histogram bins

histData :: Histogram v bin a -> v a

Histogram data as vector

underflows :: Histogram v bin a -> Maybe a

Number of underflows

overflows :: Histogram v bin a -> Maybe a

Number of overflows

outOfRange :: Histogram v bin a -> Maybe (a, a)

Underflows and overflows

Indexing

data HistIndex b

Point inside histogram's domain. It could be either bin index or bin value. First and Last constructors are useful for histogram slicing.

Constructors

Index Int

Index for a bin

Value (BinValue b)

Value

First

Bin with index 0

Last

Bin maximum index.

histIndex :: Bin b => b -> HistIndex b -> Int

Convert HistIndex to actual index

at :: (Bin bin, Vector v a) => Histogram v bin a -> HistIndex bin -> a

Index histogtam.

atV :: (Bin bin, Vector v a) => Histogram v bin a -> BinValue bin -> a

Index histogram using bin value

atI :: (Bin bin, Vector v a) => Histogram v bin a -> Int -> a

Index histogram using vector index

Transformations

map :: (Vector v a, Vector v b) => (a -> b) -> Histogram v bin a -> Histogram v bin b

fmap lookalike. It's not possible to create Functor instance because of type class context.

bmap :: (Vector v a, Vector v b, Bin bin) => (BinValue bin -> a -> b) -> Histogram v bin a -> Histogram v bin b

Map histogram using bin value and content. Overflows and underflows are set to Nothing.

mapData :: (Vector v a, Vector u b, Bin bin) => (v a -> u b) -> Histogram v bin a -> Histogram u bin b

zip :: (BinEq bin, Vector v a, Vector v b, Vector v c) => (a -> b -> c) -> Histogram v bin a -> Histogram v bin b -> Histogram v bin c

Zip two histograms elementwise. Bins of histograms must be equal otherwise error will be called.

zipSafe :: (BinEq bin, Vector v a, Vector v b, Vector v c) => (a -> b -> c) -> Histogram v bin a -> Histogram v bin b -> Maybe (Histogram v bin c)

Zip two histograms elementwise. If bins are not equal return Nothing

Type conversion

convert :: (Vector v a, Vector w a) => Histogram v bin a -> Histogram w bin a

Convert between different vector types

convertBinning :: (ConvertBin bin bin', Vector v a) => Histogram v bin a -> Histogram v bin' a

Convert between binning types using ConvertBin type class.

Folding

foldl :: Vector v a => (b -> a -> b) -> b -> Histogram v bin a -> b

Strict fold over bin content in index order. Underflows and overflows are ignored.

bfoldl :: (Bin bin, Vector v a) => (b -> BinValue bin -> a -> b) -> b -> Histogram v bin a -> b

Strict fold over bin content in index order. Function is applied to bin content and bin value. Underflows and overflows are ignored.

Specialized folds

sum :: (Vector v a, Num a) => Histogram v bin a -> a

Sum contents of all bins

minimum :: (Vector v a, Ord a) => Histogram v bin a -> a

Minimal bin content.

minimumBy :: Vector v a => (a -> a -> Ordering) -> Histogram v bin a -> a

Minimal bin content using custom comparison.

maximum :: (Vector v a, Ord a) => Histogram v bin a -> a

Maximal bin content.

maximumBy :: Vector v a => (a -> a -> Ordering) -> Histogram v bin a -> a

Maximal bin content using custom comparison.

minIndex :: (Ord a, Vector v a) => Histogram v bin a -> Int

Index of a bin with minimal content.

minIndexBy :: Vector v a => (a -> a -> Ordering) -> Histogram v bin a -> Int

Index of a bin with minimal content using custom comparison.

maxIndex :: (Ord a, Vector v a) => Histogram v bin a -> Int

Index of a bin with maximal content.

maxIndexBy :: Vector v a => (a -> a -> Ordering) -> Histogram v bin a -> Int

Index of a bin with maximal content using custom comparison.

minBin :: (Bin bin, Ord a, Vector v a) => Histogram v bin a -> BinValue bin

Value of a bin with minimal content

minBinBy :: (Bin bin, Vector v a) => (a -> a -> Ordering) -> Histogram v bin a -> BinValue bin

Value bin with minimal content using custom comparison.

maxBin :: (Bin bin, Ord a, Vector v a) => Histogram v bin a -> BinValue bin

Value of a bin with maximal content.

maxBinBy :: (Bin bin, Vector v a) => (a -> a -> Ordering) -> Histogram v bin a -> BinValue bin

Value of a bin with maximal content using custom comparison.

Slicing & rebinning

slice

Arguments

:: (SliceableBin bin, Vector v a)

=> HistIndex bin

Lower inclusive bound

-> HistIndex bin

Upper inclusive bound

-> Histogram v bin a

Histogram to slice

-> Histogram v bin a

Slice a histogram. Values/indices specify inclusive variant. Under/overflows are discarded. If requested value falls out of histogram range, it will be truncated. Use First or Last constructor if you need to slice from first or to last bin correspondingly.

rebin

Arguments

:: (MergeableBin bin, Vector v a)

=> CutDirection

On which side bins should be discarded

-> Int

Number of bins to join

-> (a -> a -> a)

Accumulation function

-> Histogram v bin a

-> Histogram v bin a

Rebin histogram by joining n adjacent bins.

rebinFold

Arguments

:: (MergeableBin bin, Vector v a, Vector v b)

=> CutDirection

On which side bins should be discarded

-> Int

Number of bins to join

-> (b -> a -> b)

Accumulation function

-> b

Initial value

-> Histogram v bin a

-> Histogram v bin b

Rebin histogram by joining n adjacent bins.

2D histograms

Data in 2D histograms is stored in row major order. This in fact is dictated by the implementation of Bin2D. So indices of the bin are arranged in the following pattern:

 0  1  2  3
 4  5  6  7
 8  9 10 11

Functions from AlongX family work with histogram slices along the X axis (as the name suggests) which are contigous, and therefore are generally faster than those from the AlongY family.

sliceAlongX

Arguments

:: (Vector v a, Bin bX, Bin bY)

=> Histogram v (Bin2D bX bY) a

2D histogram

-> HistIndex bY

Position along Y axis

-> Histogram v bX a

Get slice of 2D histogram along the X axis. This function is faster than sliceAlongY since no array reallocations are required.

sliceAlongY

Arguments

:: (Vector v a, Bin bX, Bin bY)

=> Histogram v (Bin2D bX bY) a

2D histogram

-> HistIndex bX

Position along X axis

-> Histogram v bY a

Get slice of 2D histogram along X axis

listSlicesAlongX :: (Vector v a, Bin bX, Bin bY) => Histogram v (Bin2D bX bY) a -> [(BinValue bY, Histogram v bX a)]

Slice 2D histogram along Y axis. This function is fast because it does not require reallocations.

listSlicesAlongY :: (Vector v a, Bin bX, Bin bY) => Histogram v (Bin2D bX bY) a -> [(BinValue bX, Histogram v bY a)]

Slice 2D histogram along X axis.

Reducing along axis

reduceX

Arguments

:: (Vector v a, Vector v b, Bin bX, Bin bY)

=> (Histogram v bX a -> b)

Function to reduce single slice along X axis

-> Histogram v (Bin2D bX bY) a

2D histogram

-> Histogram v bY b

Reduce along X axis. Information about under/overlows is lost.

breduceX

Arguments

:: (Vector v a, Vector v b, Bin bX, Bin bY)

=> (BinValue bY -> Histogram v bX a -> b)

Function to reduce single slice along X axis

-> Histogram v (Bin2D bX bY) a

2D histogram

-> Histogram v bY b

Reduce along X axis. Information about under/overlows is lost.

reduceY

Arguments

:: (Vector v a, Vector v b, Bin bX, Bin bY)

=> (Histogram v bY a -> b)

Function to reduce histogram along Y axis

-> Histogram v (Bin2D bX bY) a

2D histogram

-> Histogram v bX b

Reduce along Y axis. Information about under/overflows is lost.

breduceY

Arguments

:: (Vector v a, Vector v b, Bin bX, Bin bY)

=> (BinValue bX -> Histogram v bY a -> b)

Function to reduce histogram along Y axis

-> Histogram v (Bin2D bX bY) a

2D histogram

-> Histogram v bX b

Reduce along Y axis. Information about under/overflows is lost.

Lift histogram transform to 2D

liftX :: (Bin bX, Bin bY, Bin bX', BinEq bX', Vector v a, Vector v b) => (Histogram v bX a -> Histogram v bX' b) -> Histogram v (Bin2D bX bY) a -> Histogram v (Bin2D bX' bY) b

Transform X slices of histogram.

liftY :: (Bin bX, Bin bY, Bin bY', BinEq bY', Vector v a, Vector v b, Vector v Int) => (Histogram v bY a -> Histogram v bY' b) -> Histogram v (Bin2D bX bY) a -> Histogram v (Bin2D bX bY') b

Transform Y slices of histogram.