From 3f1d8be68b2d986f7f7efbb3d5152bcacbb75e83 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Tue, 13 Feb 2024 22:45:41 +0100 Subject: [PATCH] Improve documentation on boxplot and violinplot --- lib/matplotlib/axes/_axes.py | 57 +++++++++++++++++++++++++----------- 1 file changed, 40 insertions(+), 17 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 711d930a1253..5996713ccc3e 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -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* @@ -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. @@ -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. @@ -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 @@ -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. @@ -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. """ @@ -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 ---------- @@ -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 = { @@ -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): @@ -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 @@ -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