matplotlib.pyplot.boxplot¶

matplotlib.pyplot.
boxplot
(x, notch=None, sym=None, vert=None, 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, labels=None, flierprops=None, medianprops=None, meanprops=None, capprops=None, whiskerprops=None, manage_ticks=True, autorange=False, zorder=None, *, data=None)[source]¶ Make a box and whisker plot.
Make a box and whisker plot for each column of x or each vector in sequence x. The box extends from the lower to upper quartile values of the data, with a line at the median. The whiskers extend from the box to show the range of the data. Flier points are those past the end of the whiskers.
Parameters:  xArray or a sequence of vectors.
The input data.
 notchbool, default: False
Whether to draw a notched box plot (
True
), or a rectangular box plot (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, default: True
If
True
, draws vertical boxes. IfFalse
, draw horizontal boxes. 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*(Q3Q1)
, and the upper whisker at the highest datum belowQ3 + whis*(Q3Q1)
, where Q1 and Q3 are the first and third quartiles. The default value ofwhis = 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 Gaussianbased 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 arraylike, optional
A 1D arraylike of length
len(x)
. Each entry that is notNone
forces the value of the median for the corresponding dataset. For entries that areNone
, the medians are computed by Matplotlib as normal. conf_intervalsarraylike, optional
A 2D arraylike of shape
(len(x), 2)
. Each entry that is not None forces the location of the corresponding notch (which is only drawn if notch isTrue
). For entries that areNone
, the notches are computed by the method specified by the other parameters (e.g., bootstrap). positionsarraylike, 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 arraylike
The widths of the boxes. The default is 0.5, or
0.15*(distance between extreme positions)
, if that is smaller. patch_artistbool, default: False
If
False
produces boxes with the Line2D artist. Otherwise, boxes and drawn with Patch artists. labelssequence, optional
Labels for each dataset (one per dataset).
 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: False
If
True
(and showmeans isTrue
), 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, nonoutlier 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: True
Show the caps on the ends of whiskers.
 showboxbool, default: True
Show the central box.
 showfliersbool, default: True
Show the outliers beyond the caps.
 showmeansbool, default: False
Show the arithmetic means.
 cappropsdict, default: None
The style 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.
Notes
Box plots provide insight into distribution properties of the data. However, they can be challenging to interpret for the unfamiliar reader. The figure below illustrates the different visual features of a box plot.
The whiskers mark the range of the nonoutlier data. The most common definition of nonoutlier is
[Q1  1.5xIQR, Q3 + 1.5xIQR]
, which is also the default in this function. Other whisker meanings can be applied via the whis parameter.See Box plot on Wikipedia for further information.
Violin plots (
violinplot
) add even more detail about the statistical distribution by plotting the kernel density estimation (KDE) as an estimation of the probability density function.Note
In addition to the above described arguments, this function can take a data keyword argument. If such a data argument is given, every other argument can also be string
s
, which is interpreted asdata[s]
(unless this raises an exception).Objects passed as data must support item access (
data[s]
) and membership test (s in data
).