Graphics.BarChart

barchart-0.1.1: Creating Bar Charts in Haskell

Graphics.BarChart

Stability	experimental
Maintainer	Sebastian Fischer <mailto:sebf@informatik.uni-kiel.de>

Contents

Reading from CSV files

Writing images
Creating bar charts
Bar chart representations

Rendering

Creating diagrams

Benchmarking visualisation

Criterion
Progression

Description

This library provides functions and data type for generating bar charts, for example, from CSV files. If the functionality provided by the command-line program is insufficient for your needs, you can use the API provided by this library to draw custom bar charts.

The library provides high-level functions to generate bar-chart values from different types but also exports the underlying datatype and all functions used for rendering such that you have access to all internal details.

Synopsis

writeMultiBarChart :: Config -> FilePath -> [Label] -> IO ()

writeIntervalChart :: Config -> FilePath -> IO ()

writeMultiBarIntervalChart :: Config -> FilePath -> [Label] -> IO ()

data Config = Config {

outFile :: FilePath

outputType :: OutputType

caption :: Label

xLabel :: Label

yLabel :: Label

barColors :: [SomeColor]

dimensions :: (Int, Int)

ratio :: Double

fontSize :: Double

barRatio :: Double

}

type Label = String

multiBarChart :: (Measurable a, Read a) => [Label] -> CSV -> BarChart a

intervalChart :: (Measurable a, Read a) => CSV -> BarChart a

multiBarIntervalChart :: (Measurable a, Read a) => [Label] -> CSV -> BarChart a

class Num a => Measurable a where

size :: a -> Double

data MultiBars a = MultiBars [Label] [(Label, [a])]

parseMultiBars :: Read a => [Label] -> CSV -> MultiBars a

drawMultiBars :: Measurable a => MultiBars a -> BarChart a

newtype Intervals a = Intervals [(Label, (a, a, a))]

parseIntervals :: Read a => CSV -> Intervals a

drawIntervals :: Measurable a => Intervals a -> BarChart a

data MultiBarIntervals a = MBIntervals [Label] [(Label, [(a, a, a)])]

parseMultiBarIntervals :: Read a => [Label] -> CSV -> MultiBarIntervals a

drawMultiBarIntervals :: Measurable a => MultiBarIntervals a -> BarChart a

mergeIntervals :: Num a => [(Label, Intervals a)] -> MultiBarIntervals a

flipMultiBarIntervals :: MultiBarIntervals a -> MultiBarIntervals a

data BarChart a = BarChart {

block_labels :: [Label]

bars :: [Bar a]

}

data Bar a = Bar {

label :: Label

blocks :: [Block a]

}

data Block a

= Value a

| Interval {

mean :: a

lower :: a

upper :: a

}

render :: Measurable a => BarChart a -> IO ()

renderWith :: Measurable a => Config -> BarChart a -> IO ()

conf :: Config

diagram :: Measurable a => Config -> BarChart a -> Diagram

writeCriterionChart :: Config -> FilePath -> IO ()

writeComparisonChart :: Bool -> Config -> [FilePath] -> IO ()

criterionChart :: CSV -> BarChart RunTime

comparisonChart :: Bool -> [(Label, CSV)] -> BarChart RunTime

newtype RunTime = RunTime Double

writeProgressionChart :: Bool -> Config -> FilePath -> [Label] -> IO ()

progressionChart :: Bool -> [Label] -> CSV -> BarChart Ratio

newtype Ratio = Ratio Double

Reading from CSV files

There are three different modes for parsing simple CSV files: treating different values in one row as blocks of one bar, treating them as deviations from a mean value, or both.

Writing images

The following three functions implement these modes parsing the input from a CSV file and producing output in an image file.

writeMultiBarChart

:: Config	where and how to draw the bar chart
-> FilePath	CSV file to read
-> [Label]	if non-empty, used as legend for blocks
-> IO ()
The first column of the CSV file is parsed as names of the bars. The height of each bar corresponds to the sum of all subsequent entries. If there is more than one entry, the bars are split into blocks.

writeIntervalChart

:: Config	where and how to draw the bar chart
-> FilePath	CSV file to read
-> IO ()
The first column of the CSV file is parsed as names of the bars. Three entries following each bar name are parsed as mean, minimum, and maximum value and depicted using an interval next to the bar.

writeMultiBarIntervalChart

:: Config	where and how to draw the bar chart
-> FilePath	CSV file to read
-> [Label]	legend for blocks
-> IO ()
The first column of the CSV file is parsed as names of the bars. The entries following each bar name are parsed as triples of mean, minimum, and maximum value and depicted using an interval next to the bar. The number of subsequent entries must be a multiple of three and each bar is divided into a corresponding number of blocks.

data Config

Specifies how bar charts are rendered

Constructors

Config

outFile :: FilePath	file to which the bar chart is written
outputType :: OutputType	Type of generated file
caption :: Label	Title of the generated chart
xLabel :: Label	Label of the x-axis
yLabel :: Label	label of the y-axis
barColors :: [SomeColor]	Colors for the different blocks of a bar. If there are fewer colors than blocks, then colors are reused in a cyclic fashion.
dimensions :: (Int, Int)	Dimensions of the generated chart. The image will be a bit larger because of additiona space used for labels.
ratio :: Double	Scales the height of the chart. The given ratio is multiplied with the `size` of bars as given by the corresponding `Measurable` instance.
fontSize :: Double	Specifies the size of fonts used for labels.
barRatio :: Double	Value between 0.0 and 1.0 which pecifies the width of bars. Zero means that the bars are lines and 1.0 means that the is no space between bars.

type Label = String

Creating bar charts

The previous functions use the following helper functions to create a BarChart from a CSV file.

multiBarChart

:: (Measurable a, Read a)
=> [Label]	legend for blocks
-> CSV	comma separated values to depict
-> BarChart a
Used by `writeMultiBarChart` to create a `BarChart` from a CSV file.

intervalChart

:: (Measurable a, Read a)
=> CSV	comma separated values to depict
-> BarChart a
Used by `writeIntervalChart` to create a `BarChart` from a CSV file.

multiBarIntervalChart

:: (Measurable a, Read a)
=> [Label]	legend for blocks
-> CSV	comma separated values to depict
-> BarChart a
Used by `writeMultiBarIntervalChart` to create a `BarChart` from \| a CSV file.

class Num a => Measurable a where

Instances of this class can be depicted in bar charts.

Methods

size :: a -> Double

Measures the given value to figure out the correponding height of the bar.

Instances

Bar chart representations

The three different parsing modes are reflected by three data types that can be parsed from a CSV file.

data MultiBars a

Values of this type are drawn as charts where each bar may consist of multiple blocks.

Constructors

MultiBars [Label] [(Label, [a])]

Instances

Show a => Show (MultiBars a)

parseMultiBars :: Read a => [Label] -> CSV -> MultiBars a

Converts a CSV file to be drawn as a chart where each bar may consist of multiple blocks.

drawMultiBars :: Measurable a => MultiBars a -> BarChart a

Converts bars with multiple blocks into their BarChart representation.

newtype Intervals a

Values of this type are drawn as charts where each bar has an associated deviation depicted as an interval next to the bar.

Constructors

Intervals [(Label, (a, a, a))]

Instances

Show a => Show (Intervals a)

parseIntervals :: Read a => CSV -> Intervals a

Converts a CSV file to be drawn as a chart where each bar has an attached deviation depicted as an interval next to the bar.

drawIntervals :: Measurable a => Intervals a -> BarChart a

Converts bars with associated deviation into their BarChart representation.

data MultiBarIntervals a

Values of this type are drawn as charts where each bar may be divided into multiple blocks with an associated deviation depicted as intervals next to them.

Constructors

MBIntervals [Label] [(Label, [(a, a, a)])]

Instances

Show a => Show (MultiBarIntervals a)

parseMultiBarIntervals :: Read a => [Label] -> CSV -> MultiBarIntervals a

Converts a CSV file to be drawn as a chart where each bar may consist of multiple blocks which have an attached deviation depicted as an interval next to them.

drawMultiBarIntervals :: Measurable a => MultiBarIntervals a -> BarChart a

Converts bars with multiple blocks and associated deviations into their BarChart representation.

When you have multiple CSV files representing an interval chart, you can merge them to a single multi-bar interval chart. Such charts can be flipped such that bars and blocks change their roles.

mergeIntervals :: Num a => [(Label, Intervals a)] -> MultiBarIntervals a

Merges several interval charts into a chart where each bar has multiple blocks that represent the different interval charts.

flipMultiBarIntervals :: MultiBarIntervals a -> MultiBarIntervals a

Swaps bars and blocks of a chart that contains both and associated deviations.

Bar charts are represented as values of type BarChart a.

data BarChart a

Bar charts consist of a (possibly empty) list of labels for the diferent blcks of bars and the bars themselves.

Constructors

BarChart

block_labels :: [Label]	Labels of blocks in bars. Drawn as a legend if non-empty.
bars :: [Bar a]	The different bars of the chart.

Instances

Show a => Show (BarChart a)

data Bar a

Represents one bar of a bar chart.

Constructors

Bar

label :: Label	Label written underneath
blocks :: [Block a]	Different blocks of the bar. Simple charts contain only one block per bar.

Instances

Show a => Show (Bar a)

data Block a

Bocks either have a single associated value or a mean value along with minimum and maximum deviation.

Constructors

Value a

Interval

mean :: a
lower :: a
upper :: a

Instances

Show a => Show (Block a)

Rendering

Values of type BarChart a can be rendered to PNG, SVG, PDF, and PS files.

render :: Measurable a => BarChart a -> IO ()

Renders a bar chart as barchart.png according to the default configuration conf.

renderWith :: Measurable a => Config -> BarChart a -> IO ()

Renders a bar chart according to a custom configuration.

conf :: Config

The default configuration generates a PNG file with a chart of size 600x300 pixels. The output file is left unspecified and you should provide one if you use a cstom configuration.

Creating diagrams

Bar charts are rendered by conversion into Diagrams.

diagram :: Measurable a => Config -> BarChart a -> Diagram

This function can be used to embed bar charts into bigger Diagrams.

Benchmarking visualisation

There are special functions for parsing data generated by the benchmarking tools criterion and progression.

Criterion

writeCriterionChart :: Config -> FilePath -> IO ()

Reads a summary file generated by criterion and writes a corresponding bar chart.

writeComparisonChart :: Bool -> Config -> [FilePath] -> IO ()

Reads multiple summary files generated by criterion and creates a bar chart to compare them. If the first argument is True the chart is flipped such that the bars represent different benchmarks rather than summaries.

criterionChart :: CSV -> BarChart RunTime

Used by writeCriterionChart to generate a bar chart from criterion's summary file.

comparisonChart :: Bool -> [(Label, CSV)] -> BarChart RunTime

Used by writeComparisonChart to generate a bar chart from multiple summary files generated by criterion.

newtype RunTime

Wrapper around the Double type used in bar charts for criterion summary files. It has a custom Show instance to produce labels like 10ms or 2h rather than showing the plain Double values.

Constructors

RunTime Double

Instances

writeProgressionChart :: Bool -> Config -> FilePath -> [Label] -> IO ()

Reads the plot.csv file generated by progression and creates a corresponding bar chart.

progressionChart :: Bool -> [Label] -> CSV -> BarChart Ratio

Used by writeProgressionChart to generate a bar chart from progression's plot.csv file.

newtype Ratio

Wrapper around the double type used in bar charts for progression summaries. It has a custom Show instance that shows the Double values as percentages.

Constructors

Ratio Double

Instances

Produced by Haddock version 2.5.0