matplotlib.axes.Axes.bxp#

Axes.bxp(bxpstats, positions=None, *, widths=None, vert=None, orientation='vertical', patch_artist=False, shownotches=False, showmeans=False, showcaps=True, showbox=True, showfliers=True, boxprops=None, whiskerprops=None, flierprops=None, medianprops=None, capprops=None, meanprops=None, meanline=False, manage_ticks=True, zorder=None, capwidths=None, label=None)[source]#

Draw a box and whisker plot from pre-computed statistics.

The box extends from the first quartile q1 to the third quartile q3 of the data, with a line at the median (med). The whiskers extend from whislow to whishi. Flier points are markers past the end of the whiskers. See https://en.wikipedia.org/wiki/Box_plot for reference.

      whislow    q1    med    q3    whishi
                  |-----:-----|
  o      |--------|     :     |--------|    o  o
                  |-----:-----|
flier                                      fliers

Note

This is a low-level drawing function for when you already have the statistical parameters. If you want a boxplot based on a dataset, use boxplot instead.

Parameters:
bxpstatslist of dicts

A list of dictionaries containing stats for each boxplot. Required keys are:

  • med: Median (float).

  • q1, q3: First & third quartiles (float).

  • whislo, whishi: Lower & upper whisker positions (float).

Optional keys are:

  • mean: Mean (float). Needed if showmeans=True.

  • fliers: Data beyond the whiskers (array-like). Needed if showfliers=True.

  • cilo, cihi: Lower & upper confidence intervals about the median. Needed if shownotches=True.

  • label: Name of the dataset (str). If available, this will be used a tick label for the boxplot

positionsarray-like, default: [1, 2, ..., n]

The positions of the boxes. The ticks and limits are automatically set to match the positions.

widthsfloat or array-like, default: None

The widths of the boxes. The default is clip(0.15*(distance between extreme positions), 0.15, 0.5).

capwidthsfloat or array-like, default: None

Either a scalar or a vector and sets the width of each cap. The default is 0.5*(width of the box), see widths.

vertbool, optional

Deprecated since version 3.11: Use orientation instead.

This is a pending deprecation for 3.10, with full deprecation in 3.11 and removal in 3.13. 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.

patch_artistbool, default: False

If False produces boxes with the Line2D artist. If True produces boxes with the Patch artist.

shownotches, showmeans, showcaps, showbox, showfliersbool

Whether to draw the CI notches, the mean value (both default to False), the caps, the box, and the fliers (all three default to True).

boxprops, whiskerprops, capprops, flierprops, medianprops, meanpropsdict, optional

Artist properties for the boxes, whiskers, caps, fliers, medians, and means.

meanlinebool, 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. Not recommended if shownotches is also True. Otherwise, means will be shown as points.

manage_ticksbool, default: True

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

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.

zorderfloat, default: Line2D.zorder = 2

The zorder of the resulting 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: main bodies of the boxplot showing the quartiles, and the median's confidence intervals if enabled.

  • medians: horizontal lines at the median of each box.

  • whiskers: vertical lines up to the last non-outlier data.

  • caps: horizontal lines at the ends of the whiskers.

  • fliers: points representing data beyond the whiskers (fliers).

  • means: points or lines representing the means.

See also

boxplot

Draw a boxplot from data instead of pre-computed statistics.

Examples using matplotlib.axes.Axes.bxp#

Separate calculation and plotting of boxplots

Separate calculation and plotting of boxplots