# Boxplot Plotting

## Introduction

A boxplot is a way of visually summarising the distribution of a set of data. Three components of the boxplot show the following information:

- Box: the upper and lower bounds of the box typically show the 25th and 75th percentiles (interquartile range), although in practice they could represent different percentiles.

- Median line: a line across the box shows the position of the median.

- Whiskers: two vertical lines coming out of the box show the extent of the data which are not considered outliers.

The following diagram shows a sample boxplot:

A Sample Boxplot

Magics allows the user to pass data representing these values in array form, defining several boxplots at the one time. Then all may be plotted with a single action routine, `PBOXPLOT`.

Various parameters exist to control the style and plotting attributes of the boxplots. They start with the prefix BOXPLOT, e.g. BOXPLOT_BOX_COLOUR. These parameters describe the input data and plotting attributes.

A summary of BOXPLOT parameters, error codes and program examples of graph plotting are in later sections.

## Input Data

All input data for boxplot plotting are passed to Magics via arrays. Each array defines the values for one parameter for multiple boxplots. The following FORTRAN listing shows how to pass these arrays to Magics:

        CALL PSET1R('BOXPLOT_POSITIONS',        XARR,   M)
        CALL PSET1R('BOXPLOT_MINIMUM_VALUES',   MINARR, M)
        CALL PSET1R('BOXPLOT_MAXIMUM_VALUES',   MAXARR, M)
        CALL PSET1R('BOXPLOT_MEDIAN_VALUES',    MEDARR, M)
        CALL PSET1R('BOXPLOT_BOX_UPPER_VALUES', UPPARR, M)
        CALL PSET1R('BOXPLOT_BOX_LOWER_VALUES', LOWARR, M)

Note that the first line in this example sets up the list of coordinates at which the data will be plotted. Although it is not strictly data input as such, it is useful to include it here in order to provide a complete piece of code.

## Mapping of X/Y Values

The X and Y values passed by the input arrays are relative to the values of the X and Y axes respectively. The X/Y axis system may be defined by setting the parameters AXIS_MIN_VALUE and AXIS_MAX_VALUE to the required values. Incoming BOXPLOT data should be within the range of the axes. Any part of a boxplot falling outside the current axis limits is not plotted.

## Boxplot Plotting

Once the input data has been set up as described in the previous section, there are only two things left to consider: the positioning of the data plots and the plotting attributes.

As already mentioned in the previous section, the parameter BOXPLOT_POSITIONS is used to set up the coordinates at which the boxplots will be plotted. Note that each boxplot has only one coordinate, as the other is determined by the data values.

The parameters starting with BOXPLOT_BOX change the plotting behaviour of the interquartile range box such as colour and width.

The parameters starting with BOXPLOT_MEDIAN change the plotting behaviour of the median line such as colour and thickness.

The parameters starting with BOXPLOT_WHISKER change the plotting behaviour of the whisker. There are two styles of whisker plotting: line and box. When BOXPLOT_WHISKER is set to `LINE`, the whiskers are drawn as lines and are affected by the parameters starting with BOXPLOT_WHISKER_LINE. When BOXPLOT_WHISKER is set to `BOX`, the whiskers are drawn as filled boxes and are affected by the parameters starting with BOXPLOT_WHISKER_BOX.

## Program Examples

The following examples demonstrate the use of boxplots.