Merge pull request matplotlib#19860 from timhoffm/doc-boxplot

Move "howto interpreting box plots" to boxplot docstring

Author: anntzer

doc/faq/howto_faq.rst

@@ -494,25 +494,6 @@ you're all done issuing commands and you want to draw the figure now.
    per script, and harmonized the behavior of interactive mode, across most
    backends.
 
-.. _howto-boxplot_violinplot:
-
-Interpreting box plots and violin plots
----------------------------------------
-
-Tukey's :doc:`box plots </gallery/statistics/boxplot_demo>` (Robert McGill,
-John W. Tukey and Wayne A. Larsen: "The American Statistician" Vol. 32, No. 1,
-Feb., 1978, pp. 12-16) are statistical plots that provide useful information
-about the data distribution such as skewness. However, bar plots with error
-bars are still the common standard in most scientific literature, and thus, the
-interpretation of box plots can be challenging for the unfamiliar reader. The
-figure below illustrates the different visual features of a box plot.
-
-.. figure:: ../_static/boxplot_explanation.png
-
-:doc:`Violin plots </gallery/statistics/violinplot>` are closely related to box
-plots but add useful information such as the distribution of the sample data
-(density trace).  Violin plots were added in Matplotlib 1.4.
-
 .. _how-to-threads:
 
 Working with threads

lib/matplotlib/axes/_axes.py

@@ -3714,6 +3714,28 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
         meanprops : dict, 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.
+
+        .. image:: /_static/boxplot_explanation.png
+           :alt: Illustration of box plot features
+           :scale: 50 %
+
+        The whiskers mark the range of the non-outlier data. The most common
+        definition of non-outlier 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 <https://en.wikipedia.org/wiki/Box_plot>`_ on Wikipedia
+        for further information.
+
+        Violin plots (`~.Axes.violinplot`) add even more detail about the
+        statistical distribution by plotting the kernel density estimation
+        (KDE) as an estimation of the probability density function.
         """
 
         # Missing arguments default to rcParams.