Merge pull request #1 from mwaskom/master

Add explicit warning in swarmplot about gutters (mwaskom#2045)

doc/releases/v0.11.0.txt

@@ -0,0 +1,5 @@
+
+v0.11.0 (Unreleased)
+--------------------
+
+- Added an explicit warning in :func:`swarmplot` when more than 2% of the points are overlap in the "gutters" of the swarm.

seaborn/categorical.py

@@ -1315,6 +1315,15 @@ def add_gutters(self, points, center, width):
         off_high = points > high_gutter
         if off_high.any():
             points[off_high] = high_gutter
+
+        gutter_prop = (off_high + off_low).sum() / len(points)
+        if gutter_prop > .02:
+            msg = (
+                "{:.1%} of the points cannot be placed; you may want "
+                "to decrease the size of the markers or use stripplot."
+            ).format(gutter_prop)
+            warnings.warn(msg, UserWarning)
+
         return points
 
     def swarm_points(self, ax, points, center, width, s, **kws):

seaborn/tests/test_categorical.py

@@ -1780,10 +1780,15 @@ def test_beeswarm(self):
     def test_add_gutters(self):
 
         p = cat._SwarmPlotter(**self.default_kws)
+
+        points = np.zeros(10)
+        assert np.array_equal(points, p.add_gutters(points, 0, 1))
+
         points = np.array([0, -1, .4, .8])
-        points = p.add_gutters(points, 0, 1)
-        npt.assert_array_equal(points,
-                               np.array([0, -.5, .4, .5]))
+        msg = r"50.0% of the points cannot be placed.+$"
+        with pytest.warns(UserWarning, match=msg):
+            new_points = p.add_gutters(points, 0, 1)
+        assert np.array_equal(new_points, np.array([0, -.5, .4, .5]))
 
     def test_swarmplot_vertical(self):