Merge pull request matplotlib#19449 from anntzer/arraydoc

Switch array-like (M, N) to (M, N) array-like.

Author: timhoffm

doc/devel/documenting_mpl.rst

@@ -462,18 +462,19 @@ Use ``array-like`` for homogeneous numeric sequences, which could
 typically be a numpy.array. Dimensionality may be specified using ``2D``,
 ``3D``, ``n-dimensional``. If you need to have variables denoting the
 sizes of the dimensions, use capital letters in brackets
-(``array-like (M, N)``). When referring to them in the text they are easier
-read and no special formatting is needed.
+(``(M, N) array-like``). When referring to them in the text they are easier
+read and no special formatting is needed. Use ``array`` instead of
+``array-like`` for return types if the returned object is indeed a numpy array.
 
 ``float`` is the implicit default dtype for array-likes. For other dtypes
 use ``array-like of int``.
 
 Some possible uses::
 
   2D array-like
-  array-like (N)
-  array-like (M, N)
-  array-like (M, N, 3)
+  (N,) array-like
+  (M, N) array-like
+  (M, N, 3) array-like
   array-like of int
 
 Non-numeric homogeneous sequences are described as lists, e.g.::

examples/lines_bars_and_markers/hat_graph.py

@@ -22,7 +22,7 @@ def hat_graph(ax, xlabels, values, group_labels):
         The Axes to plot into.
     xlabels : list of str
         The category names to be displayed on the x-axis.
-    values : array-like (M, N)
+    values : (M, N) array-like
         The data values.
         Rows are the groups (len(group_labels) == M).
         Columns are the categories (len(xlabels) == N).

lib/matplotlib/axes/_axes.py

@@ -3622,7 +3622,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
             95% confidence intervals. Values between 1000 and 10000 are
             recommended.
 
-        usermedians : array-like, optional
+        usermedians : 1D array-like, optional
             A 1D array-like of length ``len(x)``.  Each entry that is not
             `None` forces the value of the median for the corresponding
             dataset.  For entries that are `None`, the medians are computed
@@ -5747,8 +5747,8 @@ def pcolor(self, *args, shading=None, alpha=None, norm=None, cmap=None,
 
         Parameters
         ----------
-        C : array-like
-            A scalar 2D array. The values will be color-mapped.
+        C : 2D array-like
+            The color-mapped values.
 
         X, Y : array-like, optional
             The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -5991,8 +5991,8 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
 
         Parameters
         ----------
-        C : array-like
-            A scalar 2D array. The values will be color-mapped.
+        C : 2D array-like
+            The color-mapped values.
 
         X, Y : array-like, optional
             The coordinates of the corners of quadrilaterals of a pcolormesh::
@@ -6227,7 +6227,7 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
 
         Parameters
         ----------
-        C : array-like(M, N)
+        C : array-like
             The image data. Supported array shapes are:
 
             - (M, N): an image with scalar data. The data is visualized
@@ -7748,7 +7748,7 @@ def spy(self, Z, precision=0, marker=None, markersize=None,
 
         Parameters
         ----------
-        Z : array-like (M, N)
+        Z : (M, N) array-like
             The array to be plotted.
 
         precision : float or 'present', default: 0
@@ -7872,7 +7872,7 @@ def matshow(self, Z, **kwargs):
 
         Parameters
         ----------
-        Z : array-like(M, N)
+        Z : (M, N) array-like
             The matrix to be displayed.
 
         Returns

lib/matplotlib/backend_bases.py

@@ -290,16 +290,12 @@ def draw_gouraud_triangle(self, gc, points, colors, transform):
         ----------
         gc : `.GraphicsContextBase`
             The graphics context.
-
-        points : array-like, shape=(3, 2)
+        points : (3, 2) array-like
             Array of (x, y) points for the triangle.
-
-        colors : array-like, shape=(3, 4)
+        colors : (3, 4) array-like
             RGBA colors for each point of the triangle.
-
         transform : `matplotlib.transforms.Transform`
             An affine transform to apply to the points.
-
         """
         raise NotImplementedError
 
@@ -310,12 +306,10 @@ def draw_gouraud_triangles(self, gc, triangles_array, colors_array,
 
         Parameters
         ----------
-        points : array-like, shape=(N, 3, 2)
+        points : (N, 3, 2) array-like
             Array of *N* (x, y) points for the triangles.
-
-        colors : array-like, shape=(N, 3, 4)
+        colors : (N, 3, 4) array-like
             Array of *N* RGBA colors for each point of the triangles.
-
         transform : `matplotlib.transforms.Transform`
             An affine transform to apply to the points.
         """
@@ -495,7 +489,7 @@ def draw_image(self, gc, x, y, im, transform=None):
             The distance in physical units (i.e., dots or pixels) from the
             bottom side of the canvas.
 
-        im : array-like, shape=(N, M, 4), dtype=np.uint8
+        im : (N, M, 4) array-like of np.uint8
             An array of RGBA pixels.
 
         transform : `matplotlib.transforms.Affine2DBase`

lib/matplotlib/bezier.py

@@ -204,12 +204,12 @@ def __call__(self, t):
 
         Parameters
         ----------
-        t : float (k,) array_like
+        t : (k,) array-like
             Points at which to evaluate the curve.
 
         Returns
         -------
-        float (k, d) array_like
+        (k, d) array
             Value of the curve for each point in *t*.
         """
         t = np.asarray(t)
@@ -246,7 +246,7 @@ def polynomial_coefficients(self):
 
         Returns
         -------
-        float, (n+1, d) array_like
+        (n+1, d) array
             Coefficients after expanding in polynomial basis, where :math:`n`
             is the degree of the bezier curve and :math:`d` its dimension.
             These are the numbers (:math:`C_j`) such that the curve can be
@@ -282,10 +282,10 @@ def axis_aligned_extrema(self):
 
         Returns
         -------
-        dims : int, array_like
+        dims : array of int
             Index :math:`i` of the partial derivative which is zero at each
             interior extrema.
-        dzeros : float, array_like
+        dzeros : array of float
             Of same size as dims. The :math:`t` such that :math:`d/dx_i B(t) =
             0`
         """
@@ -313,7 +313,7 @@ def split_bezier_intersecting_with_closedpath(
 
     Parameters
     ----------
-    bezier : array-like(N, 2)
+    bezier : (N, 2) array-like
         Control points of the Bezier segment. See `.BezierSegment`.
     inside_closedpath : callable
         A function returning True if a given point (x, y) is inside the

lib/matplotlib/collections.py

@@ -537,7 +537,7 @@ def set_offsets(self, offsets):
 
         Parameters
         ----------
-        offsets : array-like (N, 2) or (2,)
+        offsets : (N, 2) or (2,) array-like
         """
         offsets = np.asanyarray(offsets, float)
         if offsets.shape == (2,):  # Broadcast (2,) -> (1, 2) but nothing else.
@@ -1714,15 +1714,11 @@ def __init__(self, widths, heights, angles, units='points', **kwargs):
         ----------
         widths : array-like
             The lengths of the first axes (e.g., major axis lengths).
-
         heights : array-like
             The lengths of second axes.
-
         angles : array-like
             The angles of the first axes, degrees CCW from the x-axis.
-
         units : {'points', 'inches', 'dots', 'width', 'height', 'x', 'y', 'xy'}
-
             The units in which majors and minors are given; 'width' and
             'height' refer to the dimensions of the axes, while 'x' and 'y'
             refer to the *offsets* data units. 'xy' differs from all others in

lib/matplotlib/colors.py

@@ -440,12 +440,12 @@ def _create_lookup_table(N, data, gamma=1.0):
     N : int
         The number of elements of the created lookup table; at least 1.
 
-    data : Mx3 array-like or callable
+    data : (M, 3) array-like or callable
         Defines the mapping :math:`f`.
 
-        If a Mx3 array-like, the rows define values (x, y0, y1). The x values
-        must start with x=0, end with x=1, and all x values be in increasing
-        order.
+        If a (M, 3) array-like, the rows define values (x, y0, y1).  The x
+        values must start with x=0, end with x=1, and all x values be in
+        increasing order.
 
         A value between :math:`x_i` and :math:`x_{i+1}` is mapped to the range
         :math:`y^1_{i-1} \ldots y^0_i` by linear interpolation.
@@ -581,7 +581,7 @@ def __call__(self, X, alpha=None, bytes=False):
             return the RGBA values ``X*100`` percent along the Colormap line.
             For integers, X should be in the interval ``[0, Colormap.N)`` to
             return RGBA values *indexed* from the Colormap with index ``X``.
-        alpha : float, array-like, None
+        alpha : float or array-like or None
             Alpha must be a scalar between 0 and 1, a sequence of such
             floats with shape matching X, or None.
         bytes : bool
@@ -1959,9 +1959,8 @@ def hillshade(self, elevation, vert_exag=1, dx=1, dy=1, fraction=1.):
 
         Parameters
         ----------
-        elevation : array-like
-            A 2D array (or equivalent) of the height values used to generate an
-            illumination map
+        elevation : 2D array-like
+            The height values used to generate an illumination map
         vert_exag : number, optional
             The amount to exaggerate the elevation values by when calculating
             illumination. This can be used either to correct for differences in
@@ -2057,9 +2056,8 @@ def shade(self, data, cmap, norm=None, blend_mode='overlay', vmin=None,
 
         Parameters
         ----------
-        data : array-like
-            A 2D array (or equivalent) of the height values used to generate a
-            shaded map.
+        data : 2D array-like
+            The height values used to generate a shaded map.
         cmap : `~matplotlib.colors.Colormap`
             The colormap used to color the *data* array. Note that this must be
             a `~matplotlib.colors.Colormap` instance.  For example, rather than

lib/matplotlib/contour.py

@@ -1539,7 +1539,7 @@ def _initialize_x_y(self, z):
             If not given, they are assumed to be integer indices, i.e.
             ``X = range(M)``, ``Y = range(N)``.
 
-        Z : array-like(N, M)
+        Z : (M, N) array-like
             The height values over which the contour is drawn.
 
         levels : int or array-like, optional

lib/matplotlib/path.py

@@ -102,14 +102,11 @@ def __init__(self, vertices, codes=None, _interpolation_steps=1,
 
         Parameters
         ----------
-        vertices : array-like
-            The ``(N, 2)`` float array, masked array or sequence of pairs
-            representing the vertices of the path.
-
-            If *vertices* contains masked values, they will be converted
-            to NaNs which are then handled correctly by the Agg
-            PathIterator and other consumers of path data, such as
-            :meth:`iter_segments`.
+        vertices : (N, 2) array-like
+            The path vertices, as an array, masked array or sequence of pairs.
+            Masked values, if any, will be converted to NaNs, which are then
+            handled correctly by the Agg PathIterator and other consumers of
+            path data, such as :meth:`iter_segments`.
         codes : array-like or None, optional
             n-length array integers representing the codes of the path.
             If not None, codes must be the same length as vertices.

lib/matplotlib/pyplot.py

@@ -2368,7 +2368,7 @@ def matshow(A, fignum=None, **kwargs):
 
     Parameters
     ----------
-    A : array-like(M, N)
+    A : 2D array-like
         The matrix to be displayed.
 
     fignum : None or int or False