Skip to content

Improve documentation on boxplot and violinplot #27787

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 20, 2024
Merged

Improve documentation on boxplot and violinplot #27787

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 40 additions & 17 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3801,7 +3801,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
in *x*. If a sequence of 1D arrays, a boxplot is drawn for each
array in *x*.

notch : bool, default: False
notch : bool, default: :rc:`boxplot.notch`
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*
Expand All @@ -3823,7 +3823,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
the fliers. If `None`, then the fliers default to 'b+'. More
control is provided by the *flierprops* parameter.

vert : bool, default: True
vert : bool, default: :rc:`boxplot.vertical`
If `True`, draws vertical boxes.
If `False`, draw horizontal boxes.

Expand Down Expand Up @@ -3880,7 +3880,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
The widths of the boxes. The default is 0.5, or ``0.15*(distance
between extreme positions)``, if that is smaller.

patch_artist : bool, default: False
patch_artist : bool, default: :rc:`boxplot.patchartist`
If `False` produces boxes with the Line2D artist. Otherwise,
boxes are drawn with Patch artists.

Expand All @@ -3896,7 +3896,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
75th percentiles are equal, *whis* is set to (0, 100) such
that the whisker ends are at the minimum and maximum of the data.

meanline : bool, default: False
meanline : bool, default: :rc:`boxplot.meanline`
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
Expand Down Expand Up @@ -3931,13 +3931,13 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,

Other Parameters
----------------
showcaps : bool, default: True
showcaps : bool, default: :rc:`boxplot.showcaps`
Show the caps on the ends of whiskers.
showbox : bool, default: True
showbox : bool, default: :rc:`boxplot.showbox`
Show the central box.
showfliers : bool, default: True
showfliers : bool, default: :rc:`boxplot.showfliers`
Show the outliers beyond the caps.
showmeans : bool, default: False
showmeans : bool, default: :rc:`boxplot.showmeans`
Show the arithmetic means.
capprops : dict, default: None
The style of the caps.
Expand All @@ -3958,6 +3958,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,

See Also
--------
.Axes.bxp : Draw a boxplot from pre-computed statistics.
violinplot : Draw an estimate of the probability density function.
"""

Expand Down Expand Up @@ -4086,13 +4087,26 @@ def bxp(self, bxpstats, positions=None, widths=None, vert=True,
meanline=False, manage_ticks=True, zorder=None,
capwidths=None):
"""
Drawing function for box and whisker plots.
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.

.. code-block:: none

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

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.
.. 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 `~.Axes.boxplot` instead.

Parameters
----------
Expand Down Expand Up @@ -4172,9 +4186,9 @@ def bxp(self, bxpstats, positions=None, widths=None, vert=True,
- ``fliers``: points representing data beyond the whiskers (fliers).
- ``means``: points or lines representing the means.

Examples
See Also
--------
.. plot:: gallery/statistics/bxp.py
boxplot : Draw a boxplot from data instead of pre-computed statistics.
"""
# Clamp median line to edge of box by default.
medianprops = {
Expand Down Expand Up @@ -8278,6 +8292,10 @@ def violinplot(self, dataset, positions=None, vert=True, widths=0.5,
to identify the quantile values of each of the violin's
distribution.

See Also
--------
.Axes.violin : Draw a violin from pre-computed statistics.
boxplot : Draw a box and whisker plot.
"""

def _kde_method(X, coords):
Expand All @@ -8298,7 +8316,7 @@ def _kde_method(X, coords):
def violin(self, vpstats, positions=None, vert=True, widths=0.5,
showmeans=False, showextrema=True, showmedians=False):
"""
Drawing function for violin plots.
Draw a violin plot from pre-computed statistics.

Draw a violin plot for each column of *vpstats*. Each filled area
extends to represent the entire data range, with optional lines at the
Expand Down Expand Up @@ -8380,6 +8398,11 @@ def violin(self, vpstats, positions=None, vert=True, widths=0.5,
- ``cquantiles``: A `~.collections.LineCollection` instance created
to identify the quantiles values of each of the violin's
distribution.

See Also
--------
violin :
Draw a violin plot from data instead of pre-computed statistics.
"""

# Statistical quantities to be plotted on the violins
Expand Down