Graphics.BarChart

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.

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

Arguments

:: 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

Arguments

:: 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

Arguments

:: 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

Fields

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

Arguments

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

Arguments

:: (Measurable a, Read a)

=> CSV

comma separated values to depict

-> BarChart a

Used by writeIntervalChart to create a BarChart from a CSV file.

multiBarIntervalChart

Arguments

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

Measurable Double

Measurable Float

Measurable Int

Measurable Integer

Measurable Ratio

Measurable RunTime

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

Fields

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

Fields

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

Fields

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

Eq RunTime

Num RunTime

Read RunTime

Show RunTime

Measurable RunTime

Progression

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

Eq Ratio

Num Ratio

Read Ratio

Show Ratio

Measurable Ratio