Deprecate support for (n, 1)-shaped error arrays in errorbar().

anntzer · anntzer · commit 4fc30a177ccb · 2019-01-17T21:36:04.000+01:00
errorbar() documents that it supports the following shapes for error
arrays:

    - scalar: Symmetric +/- values for all data points.
    - shape(N,): Symmetric +/-values for each data point.
    - shape(2,N): Separate - and + values for each bar. First row
        contains the lower errors, the second row contains the
        upper errors.
    - *None*: No errorbar.

Actually it also supports (N, 1)-shaped arrays (treating them as shape
(N,)), but this support is broken for N=2 *at least* since Matplotlib
1.5:

    N = 2; errorbar(range(N), range(N), np.arange(N).reshape((N, 1)))
    ...
    ValueError: In safezip, len(args[0])=2 but len(args[1])=1

(This works for other values of N.)

Instead of further maintaining code to handle that case, just deprecate
it (no one has apparently noticed the N=2 bug, suggesting that this
(mis)feature is not much used anyways).
diff --git a/doc/api/next_api_changes/2019-01-18-AL.rst b/doc/api/next_api_changes/2019-01-18-AL.rst
@@ -0,0 +1,6 @@
+Deprecations
+````````````
+
+Support for passing (n, 1)-shaped error arrays to errorbar(), which was not
+documented and did not work for ``n = 2``, is deprecated (pass a 1D array
+instead).
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -3199,6 +3199,12 @@ def extract_err(err, data):
                     or len(b_sh) > 2 or (len(b_sh) == 2 and b_sh[1] != 1)):
                 raise ValueError(
                     "err must be a scalar or a 1D or (2, n) array-like")
+            if len(a_sh) == 2 or len(b_sh) == 2:
+                cbook.warn_deprecated(
+                    "3.1", message="Support for passing a (n, 1)-shaped error "
+                    "array to errorbar() is deprecated since Matplotlib "
+                    "%(since)s and will be removed %(removal)s; pass a 1D "
+                    "array instead.")
             # Using list comprehensions rather than arrays to preserve units.
             low = [v - e for v, e in cbook.safezip(data, a)]
             high = [v + e for v, e in cbook.safezip(data, b)]
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -2899,7 +2899,8 @@ def test_errorbar():
     fig, axs = plt.subplots(nrows=2, ncols=2, sharex=True)
     ax = axs[0, 0]
     # Try a Nx1 shaped error just to check
-    ax.errorbar(x, y, yerr=np.reshape(yerr, (len(y), 1)), fmt='o')
+    with pytest.warns(MatplotlibDeprecationWarning):
+        ax.errorbar(x, y, yerr=np.reshape(yerr, (len(y), 1)), fmt='o')
     ax.set_title('Vert. symmetric')
 
     # With 4 subplots, reduce the number of axis ticks to avoid crowding.
@@ -5248,9 +5249,12 @@ def generate_errorbar_inputs():
 
 @pytest.mark.parametrize('kwargs', generate_errorbar_inputs())
 def test_errorbar_inputs_shotgun(kwargs):
-    ax = plt.gca()
-    eb = ax.errorbar(**kwargs)
-    eb.remove()
+    with warnings.catch_warnings():
+        # (n, 1)-shaped error deprecation already tested by test_errorbar.
+        warnings.simplefilter("ignore", MatplotlibDeprecationWarning)
+        ax = plt.gca()
+        eb = ax.errorbar(**kwargs)
+        eb.remove()
 
 
 @image_comparison(baseline_images=["dash_offset"], remove_text=True)
