Merge pull request matplotlib#25120 from anntzer/mxn

Consistently document shapes as (M, N), not MxN.

Author: tacaswell

examples/lines_bars_and_markers/scatter_custom_symbol.py

@@ -35,8 +35,8 @@
 # %%
 # Using a custom path
 # -------------------
-# Alternatively, one can also pass a custom path of N vertices as a Nx2 array
-# of x, y values as *marker*.
+# Alternatively, one can also pass a custom path of N vertices as a (N, 2)
+# array of x, y values as *marker*.
 
 # unit area ellipse
 rx, ry = 3., 1.
@@ -45,7 +45,7 @@
 verts = np.column_stack([rx / area * np.cos(theta), ry / area * np.sin(theta)])
 
 x, y, s, c = np.random.rand(4, 30)
-s *= 10**2.
+s *= 100
 
 fig, ax = plt.subplots()
 ax.scatter(x, y, s, c, marker=verts)

lib/matplotlib/axes/_base.py

@@ -2495,7 +2495,7 @@ def update_datalim(self, xys, updatex=True, updatey=True):
         ----------
         xys : 2D array-like
             The points to include in the data limits Bbox. This can be either
-            a list of (x, y) tuples or a Nx2 array.
+            a list of (x, y) tuples or a (N, 2) array.
 
         updatex, updatey : bool, default: True
             Whether to update the x/y limits.

lib/matplotlib/colors.py

@@ -1110,8 +1110,8 @@ class ListedColormap(Colormap):
     Parameters
     ----------
     colors : list, array
-        List of Matplotlib color specifications, or an equivalent Nx3 or Nx4
-        floating point array (*N* RGB or RGBA values).
+        Sequence of Matplotlib color specifications (color names or RGB(A)
+        values).
     name : str, optional
         String to identify the colormap.
     N : int, optional
@@ -2370,8 +2370,8 @@ def shade(self, data, cmap, norm=None, blend_mode='overlay', vmin=None,
             "overlay".  Note that for most topographic surfaces,
             "overlay" or "soft" appear more visually realistic. If a
             user-defined function is supplied, it is expected to
-            combine an MxNx3 RGB array of floats (ranging 0 to 1) with
-            an MxNx1 hillshade array (also 0 to 1).  (Call signature
+            combine an (M, N, 3) RGB array of floats (ranging 0 to 1) with
+            an (M, N, 1) hillshade array (also 0 to 1).  (Call signature
             ``func(rgb, illum, **kwargs)``) Additional kwargs supplied
             to this function will be passed on to the *blend_mode*
             function.
@@ -2404,7 +2404,7 @@ def shade(self, data, cmap, norm=None, blend_mode='overlay', vmin=None,
         Returns
         -------
         `~numpy.ndarray`
-            An MxNx4 array of floats ranging between 0-1.
+            An (M, N, 4) array of floats ranging between 0-1.
         """
         if vmin is None:
             vmin = data.min()
@@ -2445,8 +2445,8 @@ def shade_rgb(self, rgb, elevation, fraction=1., blend_mode='hsv',
             defaults to "hsv". Note that for most topographic surfaces,
             "overlay" or "soft" appear more visually realistic. If a
             user-defined function is supplied, it is expected to combine an
-            MxNx3 RGB array of floats (ranging 0 to 1) with an MxNx1 hillshade
-            array (also 0 to 1).  (Call signature
+            (M, N, 3) RGB array of floats (ranging 0 to 1) with an (M, N, 1)
+            hillshade array (also 0 to 1).  (Call signature
             ``func(rgb, illum, **kwargs)``)
             Additional kwargs supplied to this function will be passed on to
             the *blend_mode* function.
@@ -2512,9 +2512,9 @@ def blend_hsv(self, rgb, intensity, hsv_max_sat=None, hsv_max_val=None,
         Parameters
         ----------
         rgb : `~numpy.ndarray`
-            An MxNx3 RGB array of floats ranging from 0 to 1 (color image).
+            An (M, N, 3) RGB array of floats ranging from 0 to 1 (color image).
         intensity : `~numpy.ndarray`
-            An MxNx1 array of floats ranging from 0 to 1 (grayscale image).
+            An (M, N, 1) array of floats ranging from 0 to 1 (grayscale image).
         hsv_max_sat : number, default: 1
             The maximum saturation value that the *intensity* map can shift the
             output image to.
@@ -2531,7 +2531,7 @@ def blend_hsv(self, rgb, intensity, hsv_max_sat=None, hsv_max_val=None,
         Returns
         -------
         `~numpy.ndarray`
-            An MxNx3 RGB array representing the combined images.
+            An (M, N, 3) RGB array representing the combined images.
         """
         # Backward compatibility...
         if hsv_max_sat is None:
@@ -2574,14 +2574,14 @@ def blend_soft_light(self, rgb, intensity):
         Parameters
         ----------
         rgb : `~numpy.ndarray`
-            An MxNx3 RGB array of floats ranging from 0 to 1 (color image).
+            An (M, N, 3) RGB array of floats ranging from 0 to 1 (color image).
         intensity : `~numpy.ndarray`
-            An MxNx1 array of floats ranging from 0 to 1 (grayscale image).
+            An (M, N, 1) array of floats ranging from 0 to 1 (grayscale image).
 
         Returns
         -------
         `~numpy.ndarray`
-            An MxNx3 RGB array representing the combined images.
+            An (M, N, 3) RGB array representing the combined images.
         """
         return 2 * intensity * rgb + (1 - 2 * intensity) * rgb**2
 
@@ -2592,14 +2592,14 @@ def blend_overlay(self, rgb, intensity):
         Parameters
         ----------
         rgb : `~numpy.ndarray`
-            An MxNx3 RGB array of floats ranging from 0 to 1 (color image).
+            An (M, N, 3) RGB array of floats ranging from 0 to 1 (color image).
         intensity : `~numpy.ndarray`
-            An MxNx1 array of floats ranging from 0 to 1 (grayscale image).
+            An (M, N, 1) array of floats ranging from 0 to 1 (grayscale image).
 
         Returns
         -------
         ndarray
-            An MxNx3 RGB array representing the combined images.
+            An (M, N, 3) RGB array representing the combined images.
         """
         low = 2 * intensity * rgb
         high = 1 - 2 * (1 - intensity) * (1 - rgb)

lib/matplotlib/lines.py

@@ -1031,9 +1031,7 @@ def get_path(self):
         return self._path
 
     def get_xydata(self):
-        """
-        Return the *xy* data as a Nx2 numpy array.
-        """
+        """Return the *xy* data as a (N, 2) array."""
         if self._invalidy or self._invalidx:
             self.recache()
         return self._xy

lib/matplotlib/patches.py

@@ -1081,14 +1081,16 @@ def __str__(self):
     @_api.make_keyword_only("3.6", name="closed")
     def __init__(self, xy, closed=True, **kwargs):
         """
-        *xy* is a numpy array with shape Nx2.
-
-        If *closed* is *True*, the polygon will be closed so the
-        starting and ending points are the same.
+        Parameters
+        ----------
+        xy : (N, 2) array
 
-        Valid keyword arguments are:
+        closed : bool, default: True
+            Whether the polygon is closed (i.e., has identical start and end
+            points).
 
-        %(Patch:kwdoc)s
+        **kwargs
+            %(Patch:kwdoc)s
         """
         super().__init__(**kwargs)
         self._closed = closed

lib/matplotlib/path.py

@@ -28,7 +28,7 @@ class Path:
 
     The underlying storage is made up of two parallel numpy arrays:
 
-    - *vertices*: an Nx2 float array of vertices
+    - *vertices*: an (N, 2) float array of vertices
     - *codes*: an N-length uint8 array of path codes, or None
 
     These two arrays always have the same length in the first
@@ -210,9 +210,7 @@ def _update_values(self):
 
     @property
     def vertices(self):
-        """
-        The list of vertices in the `Path` as an Nx2 numpy array.
-        """
+        """The vertices of the `Path` as an (N, 2) array."""
         return self._vertices
 
     @vertices.setter
@@ -684,7 +682,7 @@ def interpolated(self, steps):
     def to_polygons(self, transform=None, width=0, height=0, closed_only=True):
         """
         Convert this path to a list of polygons or polylines.  Each
-        polygon/polyline is an Nx2 array of vertices.  In other words,
+        polygon/polyline is an (N, 2) array of vertices.  In other words,
         each polygon has no ``MOVETO`` instructions or curves.  This
         is useful for displaying in backends that do not support
         compound paths or Bézier curves.

lib/matplotlib/streamplot.py

@@ -57,7 +57,7 @@ def streamplot(axes, x, y, u, v, density=1, linewidth=None, color=None,
         See `~matplotlib.patches.FancyArrowPatch`.
     minlength : float
         Minimum length of streamline in axes coordinates.
-    start_points : Nx2 array
+    start_points : (N, 2) array
         Coordinates of starting points for the streamlines in data coordinates
         (the same coordinates as the *x* and *y* arrays).
     zorder : float

lib/matplotlib/transforms.py

@@ -584,7 +584,7 @@ def count_contains(self, vertices):
 
         Parameters
         ----------
-        vertices : Nx2 Numpy array.
+        vertices : (N, 2) array
         """
         if len(vertices) == 0:
             return 0
@@ -769,7 +769,7 @@ def __init__(self, points, **kwargs):
         Parameters
         ----------
         points : `~numpy.ndarray`
-            A 2x2 numpy array of the form ``[[x0, y0], [x1, y1]]``.
+            A (2, 2) array of the form ``[[x0, y0], [x1, y1]]``.
         """
         super().__init__(**kwargs)
         points = np.asarray(points, float)
@@ -1485,13 +1485,13 @@ def transform(self, values):
         ----------
         values : array
             The input values as NumPy array of length :attr:`input_dims` or
-            shape (N x :attr:`input_dims`).
+            shape (N, :attr:`input_dims`).
 
         Returns
         -------
         array
             The output values as NumPy array of length :attr:`output_dims` or
-            shape (N x :attr:`output_dims`), depending on the input.
+            shape (N, :attr:`output_dims`), depending on the input.
         """
         # Ensure that values is a 2d array (but remember whether
         # we started with a 1d or 2d array).
@@ -1511,8 +1511,8 @@ def transform(self, values):
         elif ndim == 2:
             return res
         raise ValueError(
-            "Input values must have shape (N x {dims}) "
-            "or ({dims}).".format(dims=self.input_dims))
+            "Input values must have shape (N, {dims}) or ({dims},)"
+            .format(dims=self.input_dims))
 
     def transform_affine(self, values):
         """
@@ -1530,13 +1530,13 @@ def transform_affine(self, values):
         ----------
         values : array
             The input values as NumPy array of length :attr:`input_dims` or
-            shape (N x :attr:`input_dims`).
+            shape (N, :attr:`input_dims`).
 
         Returns
         -------
         array
             The output values as NumPy array of length :attr:`output_dims` or
-            shape (N x :attr:`output_dims`), depending on the input.
+            shape (N, :attr:`output_dims`), depending on the input.
         """
         return self.get_affine().transform(values)
 
@@ -1555,13 +1555,13 @@ def transform_non_affine(self, values):
         ----------
         values : array
             The input values as NumPy array of length :attr:`input_dims` or
-            shape (N x :attr:`input_dims`).
+            shape (N, :attr:`input_dims`).
 
         Returns
         -------
         array
             The output values as NumPy array of length :attr:`output_dims` or
-            shape (N x :attr:`output_dims`), depending on the input.
+            shape (N, :attr:`output_dims`), depending on the input.
         """
         return values
 

src/_backend_agg_wrapper.cpp

@@ -459,14 +459,16 @@ PyRendererAgg_draw_gouraud_triangle(PyRendererAgg *self, PyObject *args)
 
     if (points.dim(0) != 3 || points.dim(1) != 2) {
         PyErr_Format(PyExc_ValueError,
-                     "points must be a 3x2 array, got %" NPY_INTP_FMT "x%" NPY_INTP_FMT,
+                     "points must have shape (3, 2), "
+                     "got (%" NPY_INTP_FMT ", %" NPY_INTP_FMT ")",
                      points.dim(0), points.dim(1));
         return NULL;
     }
 
     if (colors.dim(0) != 3 || colors.dim(1) != 4) {
         PyErr_Format(PyExc_ValueError,
-                     "colors must be a 3x4 array, got %" NPY_INTP_FMT "x%" NPY_INTP_FMT,
+                     "colors must have shape (3, 4), "
+                     "got (%" NPY_INTP_FMT ", %" NPY_INTP_FMT ")",
                      colors.dim(0), colors.dim(1));
         return NULL;
     }
@@ -497,24 +499,16 @@ PyRendererAgg_draw_gouraud_triangles(PyRendererAgg *self, PyObject *args)
                           &trans)) {
         return NULL;
     }
-
-    if (points.size() != 0 && (points.dim(1) != 3 || points.dim(2) != 2)) {
-        PyErr_Format(PyExc_ValueError,
-                     "points must be a Nx3x2 array, got %" NPY_INTP_FMT "x%" NPY_INTP_FMT "x%" NPY_INTP_FMT,
-                     points.dim(0), points.dim(1), points.dim(2));
+    if (points.size() && !check_trailing_shape(points, "points", 3, 2)) {
         return NULL;
     }
-
-    if (colors.size() != 0 && (colors.dim(1) != 3 || colors.dim(2) != 4)) {
-        PyErr_Format(PyExc_ValueError,
-                     "colors must be a Nx3x4 array, got %" NPY_INTP_FMT "x%" NPY_INTP_FMT "x%" NPY_INTP_FMT,
-                     colors.dim(0), colors.dim(1), colors.dim(2));
+    if (colors.size() && !check_trailing_shape(colors, "colors", 3, 4)) {
         return NULL;
     }
-
     if (points.size() != colors.size()) {
         PyErr_Format(PyExc_ValueError,
-                     "points and colors arrays must be the same length, got %" NPY_INTP_FMT " and %" NPY_INTP_FMT,
+                     "points and colors arrays must be the same length, got "
+                     "%" NPY_INTP_FMT " points and %" NPY_INTP_FMT "colors",
                      points.dim(0), colors.dim(0));
         return NULL;
     }

src/_path.h

@@ -394,7 +394,7 @@ void get_path_collection_extents(agg::trans_affine &master_transform,
                                  extent_limits &extent)
 {
     if (offsets.size() != 0 && offsets.dim(1) != 2) {
-        throw std::runtime_error("Offsets array must be Nx2");
+        throw std::runtime_error("Offsets array must have shape (N, 2)");
     }
 
     size_t Npaths = paths.size();