improve c kwarg checking (and error messages) in scatter

afvincent · afvincent · commit b1cd0a3d57d8 · 2018-07-10T18:05:34.000-07:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -3792,7 +3792,9 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
             Note that *c* should not be a single numeric RGB or RGBA sequence
             because that is indistinguishable from an array of values to be
             colormapped. If you want to specify the same RGB or RGBA value for
-            all points, use a 2-D array with a single row.
+            all points, use a 2-D array with a single row.  Otherwise, value-
+            matching will have precedence in case of a size matching with *x*
+            and *y*.
 
         marker : `~matplotlib.markers.MarkerStyle`, optional, default: 'o'
             The marker style. *marker* can be either an instance of the class
@@ -3925,29 +3927,58 @@ def scatter(self, x, y, s=None, c=None, marker=None, cmap=None, norm=None,
         # c is an array for mapping.  The potential ambiguity
         # with a sequence of 3 or 4 numbers is resolved in
         # favor of mapping, not rgb or rgba.
+
+        # Convenience vars to track shape mismatch *and* conversion failures.
+        valid_shape = True  # will be put to the test!
+        n_elem = 0  # used only for (some) exceptions
+
         if c_none or co is not None:
             c_array = None
         else:
-            try:
+            try:  # First, does 'c' look suitable for value-mapping?
                 c_array = np.asanyarray(c, dtype=float)
+                n_elem = c_array.shape[0]
                 if c_array.shape in xy_shape:
                     c = np.ma.ravel(c_array)
                 else:
+                    if c_array.shape in ((3,), (4,)):
+                        _log.warning(
+                            "'c' kwarg looks like a **single** numeric RGB or "
+                            "RGBA sequence, which should be avoided as value-"
+                            "mapping will have precedence in case its length "
+                            "matches with 'x' & 'y'.  Please use a 2-D array "
+                            "with a single row if you really want to specify "
+                            "the same RGB or RGBA value for all points.")
                     # Wrong size; it must not be intended for mapping.
+                    valid_shape = False
                     c_array = None
             except ValueError:
                 # Failed to make a floating-point array; c must be color specs.
                 c_array = None
 
         if c_array is None:
-            try:
-                # must be acceptable as PathCollection facecolors
+            try:  # Then is 'c' acceptable as PathCollection facecolors?
                 colors = mcolors.to_rgba_array(c)
+                n_elem = colors.shape[0]
+                if colors.shape[0] not in (1, x.size, y.size):
+                    # NB: remember that a single color is also acceptable.
+                    valid_shape = False
+                    raise ValueError
             except ValueError:
-                # c not acceptable as PathCollection facecolor
-                raise ValueError("c of shape {} not acceptable as a color "
-                                 "sequence for x with size {}, y with size {}"
-                                 .format(c.shape, x.size, y.size))
+                if not valid_shape:  # but at least one conversion succeeded.
+                    raise ValueError(
+                        "'c' kwarg has {nc} elements, which is not acceptable "
+                        "for use with 'x' with size {xs}, 'y' with size {ys}."
+                        .format(nc=n_elem, xs=x.size, ys=y.size)
+                    )
+                # Both the mapping *and* the RGBA conversion failed: pretty
+                # severe failure => one may appreciate a verbose feedback.
+                raise ValueError(
+                    "'c' kwarg must either be valid as mpl color(s) or "
+                    "as numbers to be mapped to colors. "
+                    "Here c = {}."  # <- beware, could be long depending on c.
+                    .format(c)
+                )
         else:
             colors = None  # use cmap, norm after collection is created
 
