How to: Create Boxplot Diagrams

Article
09/12/2011

Applies to: Functional Programming

Authors: Tomas Petricek and Jon Skeet

Referenced Image

Get this book in Print, PDF, ePub and Kindle at manning.com. Use code “MSDN37b” to save 37%.

This topic contains the following sections.

Introduction
Using an FSharpChart
Using .NET Chart Controls
Running the Code
See Also

Introduction

Summary: This article shows how to create boxplot diagrams in F#. It looks at how to create a single boxplot from six statistics about an observation set as well as how to automatically create boxplots from observations.

This article is associated with Real World Functional Programming: With Examples in F# and C# by Tomas Petricek with Jon Skeet from Manning Publications (ISBN 9781933988924, copyright Manning Publications 2009, all rights reserved). No part of these chapters may be reproduced, stored in a retrieval system, or transmitted in any form or by any means—electronic, electrostatic, mechanical, photocopying, recording, or otherwise—without the prior written permission of the publisher, except in the case of brief quotations embodied in critical articles or reviews.

This article looks at how to create boxplot charts from F#. It presents two versions of the example. The first one uses the FSharpChart library, which is available as a free download, and the second uses the .NET Chart Controls directly. For more information about loading the two libraries from F#, refer to the Running the Code section at the end of the page.

When creating boxplot charts, it is either possible to specify 6 values that define the boxplot data or it is possible to specify individual values and let the library generate the boxplot diagram automatically. Figure 1 shows a chart series showing three boxplot diagrams calculated from randomly generated data.

Figure 1. Three BoxPlot diagrams calculated form randomly generated data

Referenced Image

Using an FSharpChart

A boxplot diagram shows six basic statistics about a set of observations. It displays the dataset' minimum and maximum, the upper and lower quartiles, the average value. and the median. When the F# script calculates these six statistics, the values can be passed to the function FSharpChart.BoxPlot as a six-element tuple (or a list of such tuples to draw multiple boxplots).

Another alternative when creating a boxplot is to let the Chart Controls library calculate the boxplot statistics automatically. To do that, the FSharpChart.BoxPlot function can be called with a list of arrays as an argument. Each array in the list corresponds to a single set of observations and it will be used to calculate a single boxplot.

The following three examples demonstrate both of the options. They also show how to use custom properties of the BoxPlot chart to hide the median and average values and to show unusual observations:

// Create single box plot using 6 values:
// Lower & Upper whisker, Lower & Upper box, Average and Median
FSharpChart.BoxPlot [ (-12.7, 11.6, -8.3, 6.4, -2.5, -1.6) ]

// Create two box plots using explicitly specified values
FSharpChart.BoxPlot 
  ( [ (-12.7, 11.6, -8.3, 6.4, 0.0, 0.0);
      (-6.7, 11.6, -5.0, 5.4, 0.0, 0.0) ],
    BoxPlotShowMedian = false, BoxPlotShowAverage = false)

// Calculate box plots automatically for three generated data series
let rnd = new Random()
FSharpChart.BoxPlot
  ( [ [| for i in 0 .. 20 -> float (rnd.Next 20) |]
      [| for i in 0 .. 20 -> float (rnd.Next 15 + 2) |]
      [| for i in 0 .. 20 -> float (rnd.Next 10 + 5) |] ],
    BoxPlotShowUnusualValues = true, BoxPlotShowMedian = false,
    BoxPlotShowAverage = false, BoxPlotWhiskerPercentile = 10)

The first snippet calls the FSharpChart.BoxPlot function with a list containing a single six-element tuple. This creates a single boxplot diagram showing all six statistics. The second snippet creates two boxplot diagrams. In this example, the average value and the median are not shown as part of the boxplot. The call uses the value 0.0 as a placeholder for these statistics. The lines in the boxplot diagram have to be hidden explicitly by setting BoxPlotShowMedian and BoxPlotShowAverage to false.

Finally, the last example demonstrates how to calculate boxplot diagrams automatically from (randomly generated) data. This can be done by specifying the data as a list of arrays that contain values of individual observations. It is also possible to set several custom properties to configure the boxplot diagram. When BoxPlotShowUnusualValues is true, the boxplot displays unusual values using points, as shown in Figure 1.

Using .NET Chart Controls

This section shows how to create charts using .NET Chart Controls. The following example demonstrates how to create a single boxplot diagram by explicitly specifying six statistics about an observation set. When constructing the chart, the type of the chart can be specified using the ChartType property of the Series object. To create a boxplot chart, the property should be set to the SeriesChartType.BoxPlot option.

// Create a chart containing a default area and show it on a form
let chart = new Chart(Dock = DockStyle.Fill)
let form = new Form(Visible = true, Width = 700, Height = 500)
chart.ChartAreas.Add(new ChartArea("MainArea"))
form.Controls.Add(chart)

// Create series and add it to the chart
let series = new Series(ChartType = SeriesChartType.BoxPlot)
chart.Series.Add(series)

// Add data to the series in a loop
[| -12.7; 11.6; -8.3; 6.4; -2.5; -1.6 |]
|> Array.map box |> series.Points.AddY |> ignore

After initializing the list, the snippet constructs the user interface elements. The snippet displays the chart in a new window. It creates a Form, the Chart control, and then adds the control to the form. Then, it constructs a new series and specify the type of the chart that it represents.

This example adds only a single data point to create a single boxplot diagram. This is done using the AddY method of the Points collection. When specifying six boxplot statistics, the method expects an array of type obj[]. To convert the numeric values to an array of objects, the snippet creates an array containing float values and then boxes all of the numbers to objects using the box function.

Running the Code

This section reviews the prerequisites needed to run the two examples discussed above. Both of the approaches build on top of the Microsoft Charting Library, which is available as part of the .NET 4.0 framework and can be downloaded separately for .NET 3.5.

Using the FSharpChart Library

The F# Charting library is available as a free download. The easiest way to use the library from F# Interactive is to download the library source code (FSharpChart.fsx) and load it in F# Interactive using the #load command:

#load "FSharpChart.fsx"

open System
open System.Drawing
open MSDN.FSharp.Charting

This snippet opens the namespaces that is needed when working with the library (the above examples assume these namespaces are opened). The namespace Samples.Charting contains the F# charting functionality. After writing the above lines, charts can be created using the FSharpChart type.

When loading the FSharpChart library in F# Interactive using the FSharpChart.fsx script file, it is not necessary to explicitly load the .NET Chart Controls assembly (System.Windows.Forms.DataVisualization.dll) because it is automatically referenced by the library script.
When creating a chart in a Windows Forms application, it is easier to reference the compiled version of the FSharpChart library (which can be downloaded as part of the sample source code at the end of the article). The library name is Samples.Charting.dll and it needs to be referenced together with the .NET Chart Controls assembly System.Windows.Forms.DataVisualization.dll. This can be done using the "Add Reference" command in Solution Explorer in Visual Studio.

Using .NET Chart Controls

When creating a chart from an F# script using F# Interactive, the script needs to reference the Microsoft Chart Controls assembly for Windows Forms. This is done by adding the following lines to an F# Script File (e.g., Script.fsx):

#r "System.Windows.Forms.DataVisualization.dll"

open System
open System.Drawing
open System.Windows.Forms
open System.Windows.Forms.DataVisualization.Charting

The code snippets in the first sections don't include these import declarations. In order to compile the code (as a standalone application), the following step is needed as well:

When creating a chart in a Windows Forms application or a library, the project needs to reference the .NET Chart Controls assembly using the "Add Reference" command in Solution Explorer in Visual Studio. The name of the assembly is System.Windows.Forms.DataVisualization.dll.

How to: Create Boxplot Diagrams

Introduction

Using an FSharpChart

Using .NET Chart Controls

Running the Code

Using the FSharpChart Library

Using .NET Chart Controls

See Also

Additional resources