Data.Histogram.Generic

Generic immutable histograms.

Immutable histograms

data Histogram v bin a

Immutable histogram. Histogram consists of binning algorithm, optional number of under and overflows, and data. Type parameter 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

Typeable ((* -> *) -> * -> * -> *) Histogram

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

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

(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.

module Data.Histogram.Bin

Constructors

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

Create histogram from binning algorithm and 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 coulde 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 String to histogram. Histogram do not have Read instance because of 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.

Instances

Typeable (* -> *) HistIndex

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 :: (Bin bin, 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 :: (Bin bin, 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 histogram 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 :: (Bin bin, 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 :: (Bin bin, Vector v a, Num a) => Histogram v bin a -> a

Sum contents of all bins

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

Minimal bin content.

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

Minimal bin content using custom comparison.

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

Maximal bin content

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

Maximal bin content using custom comparison.

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

Index of a bin with minimal content

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

Index of a bin with minimal content using custom comparison.

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

Index of a bin with maximal content

maxIndexBy :: (Bin bin, Ord a, 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, Ord a, 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, Ord a, 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 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 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 dictated by implementation of Bin2D. So indices of bin are arranged in following pattern:

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

Function from AlongX family work with histogram slices along X axis (as name suggest) which are contigous and therefor are generally faster than 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 X axis. This function is faster than sliceAlongY since no array reallocations is 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.