foldl-statistics: Statistical functions from the statistics package implemented as Folds.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

The use of this package allows statistics to be computed using at most two passes over the input data, one to compute a mean and one to compute a further statistic such as variance and nth central moments. All algorithms are the obvious implementation of Bryan O'Sullivan's statistics package imeplemented as Folds from the foldl package.

[Skip to Readme]


Change log
Dependencies base (>=4.7 && <5), containers (>= && <0.7), foldl (>=1.1 && <1.5), hashable (>= && <1.3), math-functions (>=0.1 && <0.4), profunctors (>=5.2 && <5.4), semigroups (>=0.18 && <1.0), unordered-containers (>= && <0.3) [details]
License BSD-3-Clause
Copyright 2016 Data61 (CSIRO)
Author Alex Mason
Category Math, Statistics
Home page
Source repo head: git clone
Uploaded by AlexMason at 2018-09-25T06:48:32Z




Maintainer's Corner

For package maintainers and hackage trustees

Readme for foldl-statistics-

[back to package description]

foldl-statistics Build Status

A reimplementation of the Statistics.Sample module using the foldl package. The intention of this package is to allow these algorithms to be used on a much broader set of data input types, including lists and streaming libraries such as conduit and pipes, and any other type which is Foldable.

All statistics in this package can be computed with no more than two passes over the data - once to compute the mean and once to compute any statistics which require the mean. this is achieved because foldl Folds are Applicative, which means that to compute, for example, the first 4 central moments as well as the count, the following could be used:

import Control.Foldl as F


dataseries :: [Double]
dataseries = ...

    let m = F.fold mean dataseries
       (c2,c3,c4,c5,n) = flip F.fold dataseries $ 
                        (\(c2,c3) (c4,c5) n -> (c2,c3,c4,c5,n)) 
                        <$> centralMoment 2 3 m
                        <*> centralMoment 4 5 m
                        <*> F.length

which traverses the data twice, once to compute the mean m, and once to compute all the central moments and the count concurrently. This brings along with it for free the ability to compute streaming statistics, such as the mean of all data seen so far, using the foldl's scan function.

Where possible, care has been taken to ensure the numerical stability of the computation of statistics.

Several algorithms require the mean of the data to be known before computing the statistic, such as skewness, kurtosis and other centralMoments. There are 'fast' implementations for calculating the variance, unbiased variance and standard deviation, which can be computed without knowing the mean a priori, but which may produce less accurate results.

Performance & Correctness

Benchmarks are included comparing performance to the statistics package. In nearly all cases, the implementations in this package perform better than those in statistics on the same inputs, and in several cases, performing two passes (to compute the mean and another statistic) is faster than the equivalent statistics implementation.

This speed has not come at the cost of correctness; all Folds are tested against their statistics counterparts to ensure the results are identical.

These results can be confirmed by running

stack build --test --bench --benchmark-arguments "--output bench.html"

which will print out the results of the tests against statistics and then run the benchmark (this may take several minutes and is best run on a "quiet" machine which is doing very little other than running the benchmark). The results of the benchmarking are then available in the file bench.html.