From 97609a8f6c84d0ab42f47943769d9ea89cc530b3 Mon Sep 17 00:00:00 2001 From: Matthias Bussonnier Date: Fri, 6 Jan 2017 14:02:19 +0100 Subject: [PATCH] Clarify the uses of whiskers float parameter. It is not clear (at least to a couple of non-native English speakers) that the whiskers extend to the last data point. More precisely: > "If it's 1.5 times Q3-Q1 it should be symmetric" The code does seem to limit the whisker to the last data point, and that correspond to one of the usage of whiskers described by Wikipedia. So fix docstrings. --- lib/matplotlib/axes/_axes.py | 9 ++++++--- lib/matplotlib/cbook.py | 9 ++++++--- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 9f3bc1b9fe83..b8e8592f6df4 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -3126,9 +3126,12 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None, everything is drawn horizontally. whis : float, sequence, or string (default = 1.5) - As a float, determines the reach of the whiskers past the - first and third quartiles (e.g., Q3 + whis*IQR, - IQR = interquartile range, Q3-Q1). Beyond the whiskers, data + As a float, determines the reach of the whiskers to the beyond the + first and third quartiles. In other words, where IQR is the + interquartile range (`Q3-Q1`), the upper whisker will extend to + last datum less than `Q3 + whis*IQR`). Similarly, the lower whisker + will extend to the first datum greater than `Q1 - whis*IQR`. + Beyond the whiskers, data are considered outliers and are plotted as individual points. Set this to an unreasonably high value to force the whiskers to show the min and max values. Alternatively, set diff --git a/lib/matplotlib/cbook.py b/lib/matplotlib/cbook.py index 41b31a825085..0d9140295cb4 100644 --- a/lib/matplotlib/cbook.py +++ b/lib/matplotlib/cbook.py @@ -1872,9 +1872,12 @@ def boxplot_stats(X, whis=1.5, bootstrap=None, labels=None, fewer dimensions. whis : float, string, or sequence (default = 1.5) - As a float, determines the reach of the whiskers past the first - and third quartiles (e.g., Q3 + whis*IQR, QR = interquartile - range, Q3-Q1). Beyond the whiskers, data are considered outliers + As a float, determines the reach of the whiskers to the beyond the + first and third quartiles. In other words, where IQR is the + interquartile range (`Q3-Q1`), the upper whisker will extend to last + datum less than `Q3 + whis*IQR`). Similarly, the lower whisker will + extend to the first datum greater than `Q1 - whis*IQR`. + Beyond the whiskers, data are considered outliers and are plotted as individual points. This can be set this to an ascending sequence of percentile (e.g., [5, 95]) to set the whiskers at specific percentiles of the data. Finally, `whis`