boxplot

Syntax

boxplot(data)

boxplot(data, group)

boxplot(data, notch, symbol, orientation, whisker, ...)

boxplot(data, group, notch, symbol, orientation, whisker, ...)

boxplot(data, options)

boxplot(data, group, options)

[s, h] = boxplot(...)

Inputs

data

Input sample. data can be a matrix where each column is a dataset, or, a cell of matrices.

Type: cell | mat

group

If data is a vector, group may be used to group data. group must be a vector with the same length as data.

Type: vector

notch

Controls the notch of the box. The notch displays the confidence interval around the median. Typical values are in range [0, 1]. The default value is 0.

Type: scalar

symbol

The display symbol for the outlier values. The default values are '+' for outliers between whisker*IQR and 2*whisker*IQR and 'o' for outliers > 2*whisker*IQR.

Type: string

orientation

Sets the orientation of the box plot. Valid values are 0 for horizontal and 1 for vertical. Default value is 1.

Type: integer

whisker

Controls the length of the whiskers as a multiplier of IQR. Default value is 1.5.

Type: scalar

options

The following options may be used to change the appearance of the box plot:

'boxstyle'

Specifies the style of the box. Valid values are 'outline' (default) and 'filled'.

Type: string

'boxwidth'

Specifies the box width. Valid values are 'proportional' (default) and 'fixed'..

If 'proportional', the width of each box is proportional to the number of elements in the dataset.

If 'fixed', all boxes have the same width.

Type: string

'capwidths'

Specifies the width of the whisker cap. The width is calculated as 'capwidths'*'widths'/4. Default value is 1.

Type: scalar

'colors'

Specifies the color of each box. Can be a Nx3 matrix or a string.

Type: matrix | string

'labels'

Specifies the name of each group of elements. Must be a cell of strings.

Type: cell

'notch'

Specifies the notch of the box. Valid values are 'on' (notch value is 0.25), 'off' (default) or a scalar value.

Type: scalar | string

'orientation'

Specifies the orientation of the boxes. Valid values are 'horizontal' (or 0) and 'vertical' (or 1, default).

Type: string

'outliertags'

Display or not the outlier index next to the outlier symbol. Valid values are 'on' and 'off' (default).

Type: string

'positions'

Specifies the position of each dataset on the X axis. Must be a vector with length equal to the number of datasets.

Type: vector

'sample_ids'

Specifies a string id for each element. Must be a cell of cells. Each nested cell must be a cell of strings containing the ids of elements in a dataset.

Type: cell

'symbol'

Specifies the outliers symbol. If one symbol is given, for example '^', then the outliers between whisker*IQR and 2*whisker*IQR will be displayed using this symbol. If two symbols are given, for example ['^', 'v'], then the second symbol will be used to display outliers > 2*whisker*IQR.

Type: matrix | string

'whisker'

Specifies the length of the whiskers as a multiplier of IQR. Default value is 1.5.

Type: scalar

'widths'

Specifies a scaling factor for the box widths. Default value is 0.4.

Type: scalar

Outputs

s

A 7xN matrix containing statistics for each dataset. The matrix rows are:

1. Minimum
2. 1st quartile
3. Median
4. 3rd quartile
5. Maximum
6. Lower confidence limit for the median
7. Upper confidence limit for the median

h

A struct with the handles of the graphics object. The struct contains the following fields:

• 'box'
• 'box_fill'
• 'labels'
• 'median'
• 'out_tags'
• 'out_tags2'
• 'outliers'
• 'outliers2'
• 'whisker'

Examples

Simple boxplot example:

clf;
mat = randn(100,4);
[s, h] = boxplot(mat);

Define the datasets using the group parameter:

clf;
mat = randn(400,1);
groups = [ones(1, 50), 2*ones(1, 250), 3*ones(1, 100)];
[s, h] = boxplot(mat, groups, 'capwidths', 2, 'symbol', '^');

Input may be a cell of matrices of different sizes:

clf;
cellIn = {randn(100,1), randn(100,2), randn(300,1)};
% set the notch, symbol, orientation and whisker values
[s, h] = boxplot(cellIn, 0.4, 'x+', 'horizontal', 1.6 );

Customize the box appearance:

clf;
mat = randn(100,10);
[s, h] = boxplot(mat, 'boxstyle', 'filled', 'colors', viridis(10));

Set custom labels on the X axis and display the outlier indices:

clf;
mat = randn(100,4);
[s, h] = boxplot(mat, 'labels', {'A', 'B', 'C', 'D'}, 'outliertags', 'on');

Customize the appearnce of graphic objects after the creation of the box plot:

clf;
mat = randn(100,4);
[s, h] = boxplot(mat);
set(h.whisker,'linestyle','--');

Comments

If there is no axis, one is created first.

The NaN values are not taken into account in the calculations for the box plot.

References:

McGill, R; Tukey, JW & Larsen, WA (1978) Variations of Box Plots. The American Statistician, Vol.32 No. 1, pp.12-16.

Kendall, MG & Stuart, A (1967): The Advanced Theory of Statistics, Vol.1, 2nd ed., Ch14., New York, Hafner Publishing Co.