Section Navigation

matplotlib.pyplot.boxplot#

matplotlib.pyplot.boxplot(x, *, notch=None, sym=None, vert=None, orientation='vertical', whis=None, positions=None, widths=None, patch_artist=None, bootstrap=None, usermedians=None, conf_intervals=None, meanline=None, showmeans=None, showcaps=None, showbox=None, showfliers=None, boxprops=None, tick_labels=None, flierprops=None, medianprops=None, meanprops=None, capprops=None, whiskerprops=None, manage_ticks=True, autorange=False, zorder=None, capwidths=None, label=None, data=None)[source]#

Draw a box and whisker plot.

The box extends from the first quartile (Q1) to the third quartile (Q3) of the data, with a line at the median. The whiskers extend from the box to the farthest data point lying within 1.5x the inter-quartile range (IQR) from the box. Flier points are those past the end of the whiskers. See https://en.wikipedia.org/wiki/Box_plot for reference.

     Q1-1.5IQR   Q1   median  Q3   Q3+1.5IQR
                  |-----:-----|
  o      |--------|     :     |--------|    o  o
                  |-----:-----|
flier             <----------->            fliers
                       IQR

Parameters:

x1D array or sequence of 1D arrays or 2D array

The input data. Possible values:

1D array: A single box is drawn.
sequence of 1D arrays: A box is drawn for each array in the sequence.
2D array: A box is drawn for each column in the array.

notchbool, default: rcParams["boxplot.notch"] (default: False)

Whether to draw a notched boxplot (True), or a rectangular boxplot (False). The notches represent the confidence interval (CI) around the median. The documentation for bootstrap describes how the locations of the notches are computed by default, but their locations may also be overridden by setting the conf_intervals parameter.

Note

In cases where the values of the CI are less than the lower quartile or greater than the upper quartile, the notches will extend beyond the box, giving it a distinctive "flipped" appearance. This is expected behavior and consistent with other statistical visualization packages.

symstr, optional

The default symbol for flier points. An empty string ('') hides the fliers. If None, then the fliers default to 'b+'. More control is provided by the flierprops parameter.

vertbool, optional

Deprecated since version 3.11: Use orientation instead.

If this is given during the deprecation period, it overrides the orientation parameter.

If True, plots the boxes vertically. If False, plots the boxes horizontally.

orientation{'vertical', 'horizontal'}, default: 'vertical'

If 'horizontal', plots the boxes horizontally. Otherwise, plots the boxes vertically.

Added in version 3.10.

whisfloat or (float, float), default: 1.5

The position of the whiskers.

If a float, the lower whisker is at the lowest datum above Q1 - whis*(Q3-Q1), and the upper whisker at the highest datum below Q3 + whis*(Q3-Q1), where Q1 and Q3 are the first and third quartiles. The default value of whis = 1.5 corresponds to Tukey's original definition of boxplots.

If a pair of floats, they indicate the percentiles at which to draw the whiskers (e.g., (5, 95)). In particular, setting this to (0, 100) results in whiskers covering the whole range of the data.

In the edge case where Q1 == Q3, whis is automatically set to (0, 100) (cover the whole range of the data) if autorange is True.

Beyond the whiskers, data are considered outliers and are plotted as individual points.

bootstrapint, optional

Specifies whether to bootstrap the confidence intervals around the median for notched boxplots. If bootstrap is None, no bootstrapping is performed, and notches are calculated using a Gaussian-based asymptotic approximation (see McGill, R., Tukey, J.W., and Larsen, W.A., 1978, and Kendall and Stuart, 1967). Otherwise, bootstrap specifies the number of times to bootstrap the median to determine its 95% confidence intervals. Values between 1000 and 10000 are recommended.

usermedians1D array-like, optional

A 1D array-like of length len(x). Each entry that is not None forces the value of the median for the corresponding dataset. For entries that are None, the medians are computed by Matplotlib as normal.

conf_intervalsarray-like, optional

A 2D array-like of shape (len(x), 2). Each entry that is not None forces the location of the corresponding notch (which is only drawn if notch is True). For entries that are None, the notches are computed by the method specified by the other parameters (e.g., bootstrap).

positionsarray-like, optional

The positions of the boxes. The ticks and limits are automatically set to match the positions. Defaults to range(1, N+1) where N is the number of boxes to be drawn.

widthsfloat or array-like

The widths of the boxes. The default is 0.5, or 0.15*(distance between extreme positions), if that is smaller.

patch_artistbool, default: rcParams["boxplot.patchartist"] (default: False)

If False produces boxes with the Line2D artist. Otherwise, boxes are drawn with Patch artists.

tick_labelslist of str, optional

The tick labels of each boxplot. Ticks are always placed at the box positions. If tick_labels is given, the ticks are labelled accordingly. Otherwise, they keep their numeric values.

Changed in version 3.9: Renamed from labels, which is also removed in 3.11.

manage_ticksbool, default: True

If True, the tick locations and labels will be adjusted to match the boxplot positions.

autorangebool, default: False

When True and the data are distributed such that the 25th and 75th percentiles are equal, whis is set to (0, 100) such that the whisker ends are at the minimum and maximum of the data.

meanlinebool, default: rcParams["boxplot.meanline"] (default: False)

If True (and showmeans is True), will try to render the mean as a line spanning the full width of the box according to meanprops (see below). Not recommended if shownotches is also True. Otherwise, means will be shown as points.

zorderfloat, default: Line2D.zorder = 2

The zorder of the boxplot.

Returns:

dict

A dictionary mapping each component of the boxplot to a list of the Line2D instances created. That dictionary has the following keys (assuming vertical boxplots):

boxes: the main body of the boxplot showing the quartiles and the median's confidence intervals if enabled.
medians: horizontal lines at the median of each box.
whiskers: the vertical lines extending to the most extreme, non-outlier data points.
caps: the horizontal lines at the ends of the whiskers.
fliers: points representing data that extend beyond the whiskers (fliers).
means: points or lines representing the means.

Other Parameters:

showcapsbool, default: rcParams["boxplot.showcaps"] (default: True)

Show the caps on the ends of whiskers.

showboxbool, default: rcParams["boxplot.showbox"] (default: True)

Show the central box.

showfliersbool, default: rcParams["boxplot.showfliers"] (default: True)

Show the outliers beyond the caps.

showmeansbool, default: rcParams["boxplot.showmeans"] (default: False)

Show the arithmetic means.

cappropsdict, default: None

The style of the caps.

capwidthsfloat or array, default: None

The widths of the caps.

boxpropsdict, default: None

The style of the box.

whiskerpropsdict, default: None

The style of the whiskers.

flierpropsdict, default: None

The style of the fliers.

medianpropsdict, default: None

The style of the median.

meanpropsdict, default: None

The style of the mean.

labelstr or list of str, optional

Legend labels. Use a single string when all boxes have the same style and you only want a single legend entry for them. Use a list of strings to label all boxes individually. To be distinguishable, the boxes should be styled individually, which is currently only possible by modifying the returned artists, see e.g. Boxplots.

In the case of a single string, the legend entry will technically be associated with the first box only. By default, the legend will show the median line (result["medians"]); if patch_artist is True, the legend will show the box Patch artists (result["boxes"]) instead.

Added in version 3.9.

dataindexable object, optional

If given, all parameters also accept a string s, which is interpreted as data[s] if s is a key in data.

Examples using `matplotlib.pyplot.boxplot`#

[]

Boxplots

[]

Artist customization in box plots

[]

Box plots with custom fill colors

[]

Box plot vs. violin plot comparison

matplotlib.pyplot.boxplot#

Examples using matplotlib.pyplot.boxplot#

Examples using `matplotlib.pyplot.boxplot`#