Copyright	Copyright (c) 2009, Alexey Khudyakov <alexey.skladnoy@gmail.com>
License	BSD3
Maintainer	Alexey Khudyakov <alexey.skladnoy@gmail.com>
Stability	experimental
Safe Haskell	None
Language	Haskell98

Data.Histogram.Generic

Contents

Immutable histograms
- Constructors
- Conversion to other data types
Serialization to strings
Accessors
- Indexing
Transformations
- Type conversion
Folding
- Specialized folds
Slicing & rebinning
2D histograms
- Reducing along axis
Lift histogram transform to 2D

Description

Generic immutable histograms.

Synopsis

Immutable histograms

data Histogram v bin a Source

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 Source

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 Source

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)] Source

Convert histogram data to list.

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

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 Source

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) Source

Read histogram from file.

Accessors

bins :: Histogram v bin a -> bin Source

Histogram bins

histData :: Histogram v bin a -> v a Source

Histogram data as vector

underflows :: Histogram v bin a -> Maybe a Source

Number of underflows

overflows :: Histogram v bin a -> Maybe a Source

Number of overflows

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

Underflows and overflows

Indexing

data HistIndex b Source

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 Source

Convert HistIndex to actual index

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

Index histogtam.

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

Index histogram using bin value

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

Index histogram using vector index

Transformations

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

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 Source

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 Source

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 Source

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) Source

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 Source

Convert between different vector types

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

Convert between binning types using ConvertBin type class.

Folding

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

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 Source

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 Source

Sum contents of all bins

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

Minimal bin content.

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

Minimal bin content using custom comparison.

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

Maximal bin content

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

Maximal bin content using custom comparison.

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

Index of a bin with minimal content

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

Index of a bin with minimal content using custom comparison.

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

Index of a bin with maximal content

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

Index of a bin with maximal content using custom comparison.

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

Value of a bin with minimal content

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

Value bin with minimal content using custom comparison.

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

Value of a bin with maximal content

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

Value of a bin with maximal content using custom comparison.

Slicing & rebinning

slice Source

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 Source

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 Source

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 Source

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 Source

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)] Source

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)] Source

Slice 2D histogram along X axis.

Reducing along axis

reduceX Source

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 Source

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 Source

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 Source

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 Source

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 Source

Transform Y slices of histogram.