Deprecate boxplot(..., whis="range").

anntzer · anntzer · commit ff7591f5d1cc · 2019-05-29T11:29:49.000+02:00
It's a special-case that needs its own testing and documentation, when
it can be perfectly well folded into `whis=(percentile, percentile)`
(specifically, `whis=(0, 100)`).
diff --git a/doc/api/next_api_changes/2019-05-28-AL.rst b/doc/api/next_api_changes/2019-05-28-AL.rst
@@ -0,0 +1,6 @@
+Deprecations
+````````````
+
+Setting the ``whis`` parameter of `.Axes.boxplot` and `.cbook.boxplot_stats` to
+"range" to mean "the whole data range" is deprecated; set it to (0, 100) (which
+gets interpreted as percentiles) to achieve the same effect.
diff --git a/examples/statistics/boxplot.py b/examples/statistics/boxplot.py
@@ -74,8 +74,8 @@
 axs[0, 1].boxplot(data, flierprops=flierprops, medianprops=medianprops)
 axs[0, 1].set_title('Custom medianprops\nand flierprops', fontsize=fs)
 
-axs[0, 2].boxplot(data, whis='range')
-axs[0, 2].set_title('whis="range"', fontsize=fs)
+axs[0, 2].boxplot(data, whis=(0, 100))
+axs[0, 2].set_title('whis=(0, 100)', fontsize=fs)
 
 axs[1, 0].boxplot(data, meanprops=meanpointprops, meanline=False,
                   showmeans=True)
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -3503,18 +3503,23 @@ 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 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. Alternatively, set
-            this to an ascending sequence of percentile (e.g., [5, 95])
-            to set the whiskers at specific percentiles of the data.
-            Finally, ``whis`` can be the string ``'range'`` to force the
-            whiskers to the min and max of the data.
+            The position of the whiskers.
+
+            If a float, the lower whisker is at position ``Q1 - whis*(Q3-Q1)``,
+            and the upper whisker at position ``Q3 + whis*(Q3-Q1)``, where Q1
+            and Q3 are the first and third quartiles.
+
+            If a pair of floats, they indicate the percentiles at which to
+            draw the whiskers (e.g., (5, 95)).  In particular, setting this to
+            [0, 100] results in whiskers covering the whole range of the data.
+            "range" is a deprecated synonym for (0, 100).
+
+            In the edge case where ``Q1 == Q3``, *whis* is automatically set
+            to [0, 100] (cover the whole range of the data) if *autorange* is
+            True.
+
+            Beyond the whiskers, data are considered outliers and are plotted
+            as individual points.
 
         bootstrap : int, optional
             Specifies whether to bootstrap the confidence intervals
@@ -3567,7 +3572,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
 
         autorange : bool, optional (False)
             When `True` and the data are distributed such that the 25th and
-            75th percentiles are equal, ``whis`` is set to ``'range'`` such
+            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, optional (False)
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -1039,20 +1039,23 @@ def boxplot_stats(X, whis=1.5, bootstrap=None, labels=None,
         Data that will be represented in the boxplots. Should have 2 or
         fewer dimensions.
 
-    whis : float, string, or sequence (default = 1.5)
-        As a float, determines the reach of the whiskers 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 to an
-        ascending sequence of percentiles (e.g., [5, 95]) to set the
-        whiskers at specific percentiles of the data. Finally, `whis`
-        can be the string ``'range'`` to force the whiskers to the
-        minimum and maximum of the data. In the edge case that the 25th
-        and 75th percentiles are equivalent, `whis` can be automatically
-        set to ``'range'`` via the `autorange` option.
+    whis : float or (float, float) (default = 1.5)
+        The position of the whiskers.
+
+        If a float, the lower whisker is at position ``Q1 - whis*(Q3-Q1)``, and
+        the upper whisker at position ``Q3 + whis*(Q3-Q1)``, where Q1 and Q3
+        are the first and third quartiles.
+
+        If a pair of floats, they indicate the percentiles at which to draw the
+        whiskers (e.g., (5, 95)).  In particular, setting this to (0, 100)
+        results in whiskers covering the whole range of the data.  "range" is
+        a deprecated synonym for [0, 100].
+
+        In the edge case where ``Q1 == Q3``, *whis* is automatically set to
+        [0, 100] (cover the whole range of the data) if *autorange* is True.
+
+        Beyond the whiskers, data are considered outliers and are plotted as
+        individual points.
 
     bootstrap : int, optional
         Number of times the confidence intervals around the median
@@ -1064,7 +1067,7 @@ def boxplot_stats(X, whis=1.5, bootstrap=None, labels=None,
 
     autorange : bool, optional (False)
         When `True` and the data are distributed such that the 25th and 75th
-        percentiles are equal, ``whis`` is set to ``'range'`` such that the
+        percentiles are equal, ``whis`` is set to (0, 100) such that the
         whisker ends are at the minimum and maximum of the data.
 
     Returns
@@ -1182,7 +1185,7 @@ def _compute_conf_interval(data, med, iqr, bootstrap):
         # interquartile range
         stats['iqr'] = q3 - q1
         if stats['iqr'] == 0 and autorange:
-            whis = 'range'
+            whis = (0, 100)
 
         # conf. interval around median
         stats['cilo'], stats['cihi'] = _compute_conf_interval(
@@ -1195,14 +1198,17 @@ def _compute_conf_interval(data, med, iqr, bootstrap):
                 loval = q1 - whis * stats['iqr']
                 hival = q3 + whis * stats['iqr']
             elif whis in ['range', 'limit', 'limits', 'min/max']:
+                warn_deprecated(
+                    "3.2", message=f"Setting whis to {whis!r} is deprecated "
+                    "since %(since)s and support for it will be removed "
+                    "%(removal)s; set it to [0, 100] to achieve the same "
+                    "effect.")
                 loval = np.min(x)
                 hival = np.max(x)
             else:
-                raise ValueError('whis must be a float, valid string, or list '
-                                 'of percentiles')
+                raise ValueError('whis must be a float or list of percentiles')
         else:
-            loval = np.percentile(x, whis[0])
-            hival = np.percentile(x, whis[1])
+            loval, hival = np.percentile(x, whis)
 
         # get high extreme
         wiskhi = x[x <= hival]
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -503,6 +503,10 @@ def validate_verbose(s):
 
 def validate_whiskers(s):
     if s == 'range':
+        cbook.warn_deprecated(
+            "3.2", message="Support for setting the boxplot.whiskers rcParam "
+            "to 'range' is deprecated since %(since)s and will be removed "
+            "%(removal)s; set it to 0, 100 instead.")
         return 'range'
     else:
         try:
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -2182,7 +2182,7 @@ def test_bxp_baseline():
                   savefig_kwarg={'dpi': 40},
                   style='default')
 def test_bxp_rangewhis():
-    _bxp_test_helper(stats_kwargs=dict(whis='range'))
+    _bxp_test_helper(stats_kwargs=dict(whis=[0, 100]))
 
 
 @image_comparison(['bxp_precentilewhis.png'],
@@ -2500,7 +2500,7 @@ def test_boxplot_rc_parameters():
 
     rc_axis1 = {
         'boxplot.vertical': False,
-        'boxplot.whiskers': 'range',
+        'boxplot.whiskers': [0, 100],
         'boxplot.patchartist': True,
     }
 
diff --git a/lib/matplotlib/tests/test_cbook.py b/lib/matplotlib/tests/test_cbook.py
@@ -147,7 +147,7 @@ def test_results_whiskers_float(self):
             assert_array_almost_equal(res[key], value)
 
     def test_results_whiskers_range(self):
-        results = cbook.boxplot_stats(self.data, whis='range')
+        results = cbook.boxplot_stats(self.data, whis=[0, 100])
         res = results[0]
         for key, value in self.known_res_range.items():
             assert_array_almost_equal(res[key], value)
