ENH: cbook.boxplot_stats can now set the whiskers to -range- (min/max) or specified percentiles. If IQR is zero, min/max are used

phobson · phobson · commit 7cf8b357c80c · 2014-01-12T20:30:07.000-08:00
diff --git a/lib/matplotlib/cbook.py b/lib/matplotlib/cbook.py
@@ -1860,12 +1860,17 @@ 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 (default = 1.5)
-        Determines the reach of the whiskers past the first and third
-        quartiles (e.g., Q3 + whis*IQR). Beyond the whiskers, data are
-        considers outliers and are plotted as individual points. Set
-        this to an unreasonably high value to force the whiskers to
-        show the min and max data. (IQR = interquartile range, Q3-Q1)
+    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). Beyond the whiskers, data are
+        considers outliers and are plotted as individual points. Set this
+        to an unreasonably high value to force the whiskers to show the min
+        and max data. (IQR = interquartile range, Q3-Q1). Alternatively, set
+        this to an ascending sequence of percentile (e.g., [5, 95]) to set
+        the whiskers at specific percentiles of the data. Finally, can be the
+        string 'range' to force the whiskers to the min and max of the data.
+        In the edge case that the 25th and 75th percentiles are equivalent,
+        `whis` will be automatically set to 'range'
 
     bootstrap : int or None (default)
         Number of times the confidence intervals around the median should
@@ -1968,22 +1973,38 @@ def _compute_conf_interval(data, med, iqr, bootstrap):
 
         # interquartile range
         stats['iqr'] = stats['q3'] - stats['q1']
+        if stats['iqr'] == 0:
+            whis = 'range'
 
         # conf. interval around median
         stats['cilo'], stats['cihi'] = _compute_conf_interval(
             x, stats['med'], stats['iqr'], bootstrap
         )
 
-        # highest non-outliers
-        hival = stats['q3'] + whis * stats['iqr']
+        # lowest/highest non-outliers
+        if np.isscalar(whis):
+            if np.isreal(whis):
+                loval = stats['q1'] - whis * stats['iqr']
+                hival = stats['q3'] + whis * stats['iqr']
+            elif whis in ['range', 'limit', 'limits', 'min/max']:
+                loval = np.min(x)
+                hival = np.max(x)
+            else:
+                whismsg = 'whis must be a float, valid string, or '\
+                          'list of percentiles'
+                raise ValueError(whismsg)
+        else:
+            loval = np.percentile(x, whis[0])
+            hival = np.percentile(x, whis[1])
+
+        # get high extreme
         wiskhi = np.compress(x <= hival, x)
         if len(wiskhi) == 0 or np.max(wiskhi) < stats['q3']:
             stats['whishi'] = stats['q3']
         else:
             stats['whishi'] = max(wiskhi)
 
         # get low extreme
-        loval = stats['q1'] - whis * stats['iqr']
         wisklo = np.compress(x >= loval, x)
         if len(wisklo) == 0 or np.min(wisklo) > stats['q1']:
             stats['whislo'] = stats['q1']
diff --git a/lib/matplotlib/tests/test_cbook.py b/lib/matplotlib/tests/test_cbook.py
@@ -101,7 +101,7 @@ def setup(self):
         self.nrows = 37
         self.ncols = 4
         self.data = np.random.lognormal(size=(self.nrows, self.ncols),
-                                            mean=1.5, sigma=1.75)
+                                        mean=1.5, sigma=1.75)
         self.known_keys = sorted([
             'mean', 'med', 'q1', 'q3', 'iqr',
             'cilo', 'cihi', 'whislo', 'whishi',
@@ -140,6 +140,17 @@ def setup(self):
             'label': 'Test1'
         }
 
+        self.known_res_percentiles = {
+            'whislo':   0.1933685896907924,
+            'whishi':  42.232049135969874
+        }
+
+        self.known_res_range = {
+            'whislo': 0.042143774965502923,
+            'whishi': 92.554670752188699
+
+        }
+
     def test_form_main_list(self):
         assert_true(isinstance(self.std_results, list))
 
@@ -175,7 +186,7 @@ def test_results_bootstrapped(self):
                 self.known_bootstrapped_ci[key]
             )
 
-    def test_results_whiskers(self):
+    def test_results_whiskers_float(self):
         results = cbook.boxplot_stats(self.data, whis=3)
         res = results[0]
         for key in list(self.known_whis3_res.keys()):
@@ -189,6 +200,34 @@ def test_results_whiskers(self):
                 self.known_whis3_res[key]
             )
 
+    def test_results_whiskers_range(self):
+        results = cbook.boxplot_stats(self.data, whis='range')
+        res = results[0]
+        for key in list(self.known_res_range.keys()):
+            if key != 'fliers':
+                assert_statement = assert_approx_equal
+            else:
+                assert_statement = assert_array_almost_equal
+
+            assert_statement(
+                res[key],
+                self.known_res_range[key]
+            )
+
+    def test_results_whiskers_percentiles(self):
+        results = cbook.boxplot_stats(self.data, whis=[5, 95])
+        res = results[0]
+        for key in list(self.known_res_percentiles.keys()):
+            if key != 'fliers':
+                assert_statement = assert_approx_equal
+            else:
+                assert_statement = assert_array_almost_equal
+
+            assert_statement(
+                res[key],
+                self.known_res_percentiles[key]
+            )
+
     def test_results_withlabels(self):
         labels = ['Test1', 2, 3, 4]
         results = cbook.boxplot_stats(self.data, labels=labels)
