From c27265a15f8572519cc62a8a57429d23614c513a Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Thu, 4 Feb 2021 11:23:34 +0100 Subject: [PATCH] Switch array-like (M, N) to (M, N) array-like. Also use "array" instead of "array-like" for return types if appropriate. Some instances were left unchanged as they may need more editing anyways. --- doc/devel/documenting_mpl.rst | 11 ++++++----- examples/lines_bars_and_markers/hat_graph.py | 2 +- lib/matplotlib/axes/_axes.py | 16 ++++++++-------- lib/matplotlib/backend_bases.py | 16 +++++----------- lib/matplotlib/bezier.py | 12 ++++++------ lib/matplotlib/collections.py | 6 +----- lib/matplotlib/colors.py | 20 +++++++++----------- lib/matplotlib/contour.py | 2 +- lib/matplotlib/path.py | 13 +++++-------- lib/matplotlib/pyplot.py | 2 +- lib/matplotlib/stackplot.py | 7 +++---- lib/matplotlib/tri/triangulation.py | 10 +++++----- lib/matplotlib/tri/tricontour.py | 6 +++--- lib/matplotlib/tri/triinterpolate.py | 4 ++-- lib/matplotlib/tri/trirefine.py | 2 +- lib/matplotlib/tri/tritools.py | 2 +- lib/mpl_toolkits/axes_grid1/axes_rgb.py | 10 +++------- lib/mpl_toolkits/mplot3d/art3d.py | 2 +- lib/mpl_toolkits/mplot3d/axes3d.py | 3 +-- 19 files changed, 63 insertions(+), 83 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index beb0ea23dc8c..0bd0816a631a 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -462,8 +462,9 @@ 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``. @@ -471,9 +472,9 @@ 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.:: diff --git a/examples/lines_bars_and_markers/hat_graph.py b/examples/lines_bars_and_markers/hat_graph.py index 11640850f3e2..4c29f6f85625 100644 --- a/examples/lines_bars_and_markers/hat_graph.py +++ b/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). diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 592dd0d5adaf..1b0c881245af 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/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 diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py index 6e3ec46eca72..658b769d8874 100644 --- a/lib/matplotlib/backend_bases.py +++ b/lib/matplotlib/backend_bases.py @@ -297,16 +297,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 @@ -317,12 +313,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. """ @@ -502,7 +496,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` diff --git a/lib/matplotlib/bezier.py b/lib/matplotlib/bezier.py index 0b1bdcdb1acb..32889edc8fbd 100644 --- a/lib/matplotlib/bezier.py +++ b/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 diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py index f7cf3f2a804c..7ae6a867ba93 100644 --- a/lib/matplotlib/collections.py +++ b/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 diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py index 2835d3d3c5ba..943008f92afc 100644 --- a/lib/matplotlib/colors.py +++ b/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 diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index a27d826a7ef3..00db07ab5bb8 100644 --- a/lib/matplotlib/contour.py +++ b/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 diff --git a/lib/matplotlib/path.py b/lib/matplotlib/path.py index 0ba00f5b3308..475db80c42ef 100644 --- a/lib/matplotlib/path.py +++ b/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. diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 8f8f9544677e..39b28ab11346 100644 --- a/lib/matplotlib/pyplot.py +++ b/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 diff --git a/lib/matplotlib/stackplot.py b/lib/matplotlib/stackplot.py index 9d476d7cf8e3..9e8317ec987f 100644 --- a/lib/matplotlib/stackplot.py +++ b/lib/matplotlib/stackplot.py @@ -4,8 +4,8 @@ http://stackoverflow.com/questions/2225995/how-can-i-create-stacked-line-graph-with-matplotlib (http://stackoverflow.com/users/66549/doug) - """ + import numpy as np from matplotlib import _api @@ -21,10 +21,9 @@ def stackplot(axes, x, *args, Parameters ---------- - x : array-like (N) - - y : 2D array (M, N) or sequence of array-like (N) + x : (N,) array-like + y : (M, N) array-like The data is assumed to be unstacked. Each of the following calls is legal:: diff --git a/lib/matplotlib/tri/triangulation.py b/lib/matplotlib/tri/triangulation.py index f207ee26d52a..24e99634a466 100644 --- a/lib/matplotlib/tri/triangulation.py +++ b/lib/matplotlib/tri/triangulation.py @@ -9,22 +9,22 @@ class Triangulation: Parameters ---------- - x, y : array-like of shape (npoints) + x, y : (npoints,) array-like Coordinates of grid points. - triangles : int array-like of shape (ntri, 3), optional + triangles : (ntri, 3) array-like of int, optional For each triangle, the indices of the three points that make up the triangle, ordered in an anticlockwise manner. If not specified, the Delaunay triangulation is calculated. - mask : bool array-like of shape (ntri), optional + mask : (ntri,) array-like of bool, optional Which triangles are masked out. Attributes ---------- - triangles : int array-like of shape (ntri, 3) + triangles : (ntri, 3) array of int For each triangle, the indices of the three points that make up the triangle, ordered in an anticlockwise manner. If you want to take the *mask* into account, use `get_masked_triangles` instead. - mask : bool array of shape (ntri, 3) + mask : (ntri, 3) array of bool Masked out triangles. is_delaunay : bool Whether the Triangulation is a calculated Delaunay diff --git a/lib/matplotlib/tri/tricontour.py b/lib/matplotlib/tri/tricontour.py index e236f7dfe687..dc7c803e61e7 100644 --- a/lib/matplotlib/tri/tricontour.py +++ b/lib/matplotlib/tri/tricontour.py @@ -153,15 +153,15 @@ def _contour_args(self, args, kwargs): x, y : array-like, optional The coordinates of the values in *Z*. -triangles : int array-like of shape (ntri, 3), optional +triangles : (ntri, 3) array-like of int, optional For each triangle, the indices of the three points that make up the triangle, ordered in an anticlockwise manner. If not specified, the Delaunay triangulation is calculated. -mask : bool array-like of shape (ntri), optional +mask : (ntri,) array-like of bool, optional Which triangles are masked out. -Z : array-like(N, M) +Z : 2D array-like The height values over which the contour is drawn. levels : int or array-like, optional diff --git a/lib/matplotlib/tri/triinterpolate.py b/lib/matplotlib/tri/triinterpolate.py index a00cb2e87e4d..9c8311892b2a 100644 --- a/lib/matplotlib/tri/triinterpolate.py +++ b/lib/matplotlib/tri/triinterpolate.py @@ -242,7 +242,7 @@ class LinearTriInterpolator(TriInterpolator): ---------- triangulation : `~matplotlib.tri.Triangulation` The triangulation to interpolate over. - z : array-like of shape (npoints,) + z : (npoints,) array-like Array of values, defined at grid points, to interpolate between. trifinder : `~matplotlib.tri.TriFinder`, optional If this is not specified, the Triangulation's default TriFinder will @@ -305,7 +305,7 @@ class CubicTriInterpolator(TriInterpolator): ---------- triangulation : `~matplotlib.tri.Triangulation` The triangulation to interpolate over. - z : array-like of shape (npoints,) + z : (npoints,) array-like Array of values, defined at grid points, to interpolate between. kind : {'min_E', 'geom', 'user'}, optional Choice of the smoothing algorithm, in order to compute diff --git a/lib/matplotlib/tri/trirefine.py b/lib/matplotlib/tri/trirefine.py index 7ba66d0ea5c6..674ee211cf46 100644 --- a/lib/matplotlib/tri/trirefine.py +++ b/lib/matplotlib/tri/trirefine.py @@ -136,7 +136,7 @@ def refine_field(self, z, triinterpolator=None, subdiv=3): Parameters ---------- - z : array-like of length ``n_points`` + z : (npoints,) array-like Values of the field to refine, defined at the nodes of the encapsulated triangulation. (``n_points`` is the number of points in the initial triangulation) diff --git a/lib/matplotlib/tri/tritools.py b/lib/matplotlib/tri/tritools.py index bda8f7c0248f..11b500fcdd8f 100644 --- a/lib/matplotlib/tri/tritools.py +++ b/lib/matplotlib/tri/tritools.py @@ -143,7 +143,7 @@ def get_flat_tri_mask(self, min_circle_ratio=0.01, rescale=True): Returns ------- - bool array-like + array of bool Mask to apply to encapsulated triangulation. All the initially masked triangles remain masked in the *new_mask*. diff --git a/lib/mpl_toolkits/axes_grid1/axes_rgb.py b/lib/mpl_toolkits/axes_grid1/axes_rgb.py index f111798ae6df..b8cdf4dde7f1 100644 --- a/lib/mpl_toolkits/axes_grid1/axes_rgb.py +++ b/lib/mpl_toolkits/axes_grid1/axes_rgb.py @@ -134,14 +134,10 @@ def imshow_rgb(self, r, g, b, **kwargs): Parameters ---------- - r : array-like - The red array - g : array-like - The green array - b : array-like - The blue array + r, g, b : array-like + The red, green, and blue arrays. kwargs : imshow kwargs - kwargs get unpacked into the imshow calls for the four images + kwargs get unpacked into the imshow calls for the four images. Returns ------- diff --git a/lib/mpl_toolkits/mplot3d/art3d.py b/lib/mpl_toolkits/mplot3d/art3d.py index 6c7a97b75cc1..8eb86ed682fa 100644 --- a/lib/mpl_toolkits/mplot3d/art3d.py +++ b/lib/mpl_toolkits/mplot3d/art3d.py @@ -763,7 +763,7 @@ def __init__(self, verts, *args, zsort='average', **kwargs): """ Parameters ---------- - verts : list of array-like Nx3 + verts : list of (N, 3) array-like Each element describes a polygon as a sequence of ``N_i`` points ``(x, y, z)``. zsort : {'average', 'min', 'max'}, default: 'average' diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py index abc65e234f65..14d2b9f4a89d 100644 --- a/lib/mpl_toolkits/mplot3d/axes3d.py +++ b/lib/mpl_toolkits/mplot3d/axes3d.py @@ -1765,9 +1765,8 @@ def _generate_normals(self, polygons): Returns ------- - normals : (..., 3) array-like + normals : (..., 3) array A normal vector estimated for the polygon. - """ if isinstance(polygons, np.ndarray): # optimization: polygons all have the same number of points, so can