diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 076e719df208..eaf94407e1ea 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -5329,7 +5329,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None, origin=None, extent=None, *, filternorm=True, filterrad=4.0, resample=None, url=None, **kwargs): """ - Display data as an image; i.e. on a 2D regular raster. + Display data as an image, i.e., on a 2D regular raster. The input may either be actual RGB(A) data, or 2D scalar data, which will be rendered as a pseudocolor image. For displaying a grayscale diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py index 718a3974cf4d..0dc84edc2acc 100644 --- a/lib/matplotlib/colorbar.py +++ b/lib/matplotlib/colorbar.py @@ -54,25 +54,26 @@ _log = logging.getLogger(__name__) -make_axes_kw_doc = """ - - ============= ==================================================== - Property Description - ============= ==================================================== - *orientation* vertical or horizontal - *fraction* 0.15; fraction of original axes to use for colorbar - *pad* 0.05 if vertical, 0.15 if horizontal; fraction - of original axes between colorbar and new image axes - *shrink* 1.0; fraction by which to multiply the size of the colorbar - *aspect* 20; ratio of long to short dimensions - *anchor* (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal; - the anchor point of the colorbar axes - *panchor* (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal; - the anchor point of the colorbar parent axes. If - False, the parent axes' anchor will be unchanged - ============= ==================================================== - +_make_axes_param_doc = """ + fraction : float, default: 0.15 + Fraction of original axes to use for colorbar. + shrink : float, default: 1.0 + Fraction by which to multiply the size of the colorbar. + aspect : float, default: 20 + Ratio of long to short dimensions. +""" +_make_axes_other_param_doc = """ + pad : float, default: 0.05 if vertical, 0.15 if horizontal + Fraction of original axes between colorbar and new image axes. + anchor : (float, float), optional + The anchor point of the colorbar axes. + Defaults to (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal. + panchor : (float, float), or *False*, optional + The anchor point of the colorbar parent axes. If *False*, the parent + axes' anchor will be unchanged. + Defaults to (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal. """ +make_axes_kw_doc = _make_axes_param_doc + _make_axes_other_param_doc colormap_kw_doc = """ @@ -1362,7 +1363,7 @@ def remove(self): ax.set_subplotspec(subplotspec) -@docstring.Substitution(make_axes_kw_doc) +@docstring.Substitution(_make_axes_param_doc, _make_axes_other_param_doc) def make_axes(parents, location=None, orientation=None, fraction=0.15, shrink=1.0, aspect=20, **kw): """ @@ -1371,21 +1372,33 @@ def make_axes(parents, location=None, orientation=None, fraction=0.15, The axes is placed in the figure of the *parents* axes, by resizing and repositioning *parents*. - Keyword arguments may include the following (with defaults): + Parameters + ---------- + parents : `~.axes.Axes` or list of `~.axes.Axes` + The Axes to use as parents for placing the colorbar. - location : None or {'left', 'right', 'top', 'bottom'} - The position, relative to *parents*, where the colorbar axes - should be created. If None, the value will either come from the - given ``orientation``, else it will default to 'right'. + location : None or {'left', 'right', 'top', 'bottom'} + The position, relative to *parents*, where the colorbar axes + should be created. If None, the value will either come from the + given ``orientation``, else it will default to 'right'. - orientation : None or {'vertical', 'horizontal'} - The orientation of the colorbar. Typically, this keyword shouldn't - be used, as it can be derived from the ``location`` keyword. + orientation : None or {'vertical', 'horizontal'} + The orientation of the colorbar. Typically, this keyword shouldn't + be used, as it can be derived from the ``location`` keyword. %s - Returns (cax, kw), the child axes and the reduced kw dictionary to be - passed when creating the colorbar instance. + Returns + ------- + cax : `~.axes.Axes` + The child axes. + kw : dict + The reduced keyword dictionary to be passed when creating the colorbar + instance. + + Other Parameters + ---------------- + %s """ locations = ["left", "right", "top", "bottom"] if orientation is not None and location is not None: @@ -1519,7 +1532,7 @@ def make_axes(parents, location=None, orientation=None, fraction=0.15, return cax, kw -@docstring.Substitution(make_axes_kw_doc) +@docstring.Substitution(_make_axes_param_doc, _make_axes_other_param_doc) def make_axes_gridspec(parent, *, fraction=0.15, shrink=1.0, aspect=20, **kw): """ Create a `~.SubplotBase` suitable for a colorbar. @@ -1530,7 +1543,7 @@ def make_axes_gridspec(parent, *, fraction=0.15, shrink=1.0, aspect=20, **kw): This function is similar to `.make_axes`. Primary differences are - `.make_axes_gridspec` only handles the *orientation* keyword - and cannot handle the "location" keyword. + and cannot handle the *location* keyword. - `.make_axes_gridspec` should only be used with a `.SubplotBase` parent. @@ -1538,22 +1551,32 @@ def make_axes_gridspec(parent, *, fraction=0.15, shrink=1.0, aspect=20, **kw): `.SubplotBase`. - `.make_axes` updates the position of the parent. `.make_axes_gridspec` - replaces the ``grid_spec`` attribute of the parent with a new one. + replaces the ``grid_spec`` attribute of the parent with a new one. While this function is meant to be compatible with `.make_axes`, there could be some minor differences. - Keyword arguments may include the following (with defaults): - - *orientation* - 'vertical' or 'horizontal' + Parameters + ---------- + parent : `~.axes.Axes` + The Axes to use as parent for placing the colorbar. %s - All but the first of these are stripped from the input kw set. + Returns + ------- + cax : `~.axes.SubplotBase` + The child axes. + kw : dict + The reduced keyword dictionary to be passed when creating the colorbar + instance. - Returns (cax, kw), the child axes and the reduced kw dictionary to be - passed when creating the colorbar instance. + Other Parameters + ---------------- + orientation : {'vertical', 'horizontal'}, default: 'vertical' + The orientation of the colorbar. + + %s """ orientation = kw.setdefault('orientation', 'vertical') diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py index 05d30f38fc70..266c71fcc438 100644 --- a/lib/matplotlib/dates.py +++ b/lib/matplotlib/dates.py @@ -607,8 +607,12 @@ class IndexDateFormatter(ticker.Formatter): def __init__(self, t, fmt, tz=None): """ - *t* is a sequence of dates (floating point days). *fmt* is a - `~datetime.datetime.strftime` format string. + Parameters + ---------- + t : list of float + A sequence of dates (floating point days). + fmt : str + A `~datetime.datetime.strftime` format string. """ if tz is None: tz = _get_rc_timezone() diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py index 79a3e827ff46..b5c50625a7f6 100644 --- a/lib/matplotlib/legend.py +++ b/lib/matplotlib/legend.py @@ -941,13 +941,21 @@ def set_bbox_to_anchor(self, bbox, transform=None): """ Set the bbox that the legend will be anchored to. - *bbox* can be - - - A `.BboxBase` instance - - A tuple of ``(left, bottom, width, height)`` in the given transform - (normalized axes coordinate if None) - - A tuple of ``(left, bottom)`` where the width and height will be - assumed to be zero. + Parameters + ---------- + bbox : `~matplotlib.transforms.BboxBase` or tuple + The bounding box can be specified in the following ways: + + - A `.BboxBase` instance + - A tuple of ``(left, bottom, width, height)`` in the given + transform (normalized axes coordinate if None) + - A tuple of ``(left, bottom)`` where the width and height will be + assumed to be zero. + - *None*, to remove the bbox anchoring, and use the parent bbox. + + transform : `~matplotlib.transforms.Transform`, optional + A transform to apply to the bounding box. If not specified, this + will use a transform to the bounding box of the parent. """ if bbox is None: self._bbox_to_anchor = None @@ -978,13 +986,16 @@ def _get_anchored_bbox(self, loc, bbox, parentbbox, renderer): Place the *bbox* inside the *parentbbox* according to a given location code. Return the (x, y) coordinate of the bbox. - - loc: a location code in range(1, 11). - This corresponds to the possible values for self._loc, excluding - "best". + Parameters + ---------- + loc : int + A location code in range(1, 11). This corresponds to the possible + values for ``self._loc``, excluding "best". + bbox : `~matplotlib.transforms.Bbox` + bbox to be placed, in display coordinates. + parentbbox : `~matplotlib.transforms.Bbox` + A parent box which will contain the bbox, in display coordinates. - - bbox: bbox to be placed, display coordinate units. - - parentbbox: a parent box which will contain the bbox. In - display coordinates. """ assert loc in range(1, 11) # called only internally @@ -1079,8 +1090,9 @@ def set_draggable(self, state, use_blit=False, update='loc'): Returns ------- - If *state* is ``True`` this returns the `~.DraggableLegend` helper - instance. Otherwise this returns ``None``. + `.DraggableLegend` or *None* + If *state* is ``True`` this returns the `.DraggableLegend` helper + instance. Otherwise this returns *None*. """ if state: if self._draggable is None: diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py index 9d86826d075c..6efb42d0e8ef 100644 --- a/lib/matplotlib/lines.py +++ b/lib/matplotlib/lines.py @@ -1493,8 +1493,12 @@ def process_selected(self, ind, xs, ys): Default "do nothing" implementation of the :meth:`process_selected` method. - *ind* are the indices of the selected vertices. *xs* and *ys* - are the coordinates of the selected vertices. + Parameters + ---------- + ind : list of int + The indices of the selected vertices. + xs, ys : array-like + The coordinates of the selected vertices. """ pass diff --git a/lib/matplotlib/offsetbox.py b/lib/matplotlib/offsetbox.py index 7bcf3f3deabe..c7e5ff9c5ff6 100644 --- a/lib/matplotlib/offsetbox.py +++ b/lib/matplotlib/offsetbox.py @@ -142,10 +142,15 @@ def _get_aligned_offsets(hd_list, height, align="baseline"): *mode*. xdescent is analogous to the usual descent, but along the x-direction. xdescent values are currently ignored. - *hd_list* : list of (width, xdescent) of boxes to be aligned. - *sep* : spacing between boxes - *height* : Intended total length. None if not used. - *align* : align mode. 'baseline', 'top', 'bottom', or 'center'. + Parameters + ---------- + hd_list + List of (height, xdescent) of boxes to be aligned. + height : float or None + Intended total length. If None, the maximum of the heights in *hd_list* + is used. + align : {'baseline', 'left', 'top', 'right', 'bottom', 'center'} + Align mode. """ if height is None: diff --git a/lib/matplotlib/sankey.py b/lib/matplotlib/sankey.py index b11206b9446a..72bc6b205e12 100644 --- a/lib/matplotlib/sankey.py +++ b/lib/matplotlib/sankey.py @@ -45,50 +45,9 @@ def __init__(self, ax=None, scale=1.0, unit='', format='%G', gap=0.25, """ Create a new Sankey instance. - Optional keyword arguments: - - =============== =================================================== - Field Description - =============== =================================================== - *ax* axes onto which the data should be plotted - If *ax* isn't provided, new axes will be created. - *scale* scaling factor for the flows - *scale* sizes the width of the paths in order to - maintain proper layout. The same scale is applied - to all subdiagrams. The value should be chosen - such that the product of the scale and the sum of - the inputs is approximately 1.0 (and the product of - the scale and the sum of the outputs is - approximately -1.0). - *unit* string representing the physical unit associated - with the flow quantities - If *unit* is None, then none of the quantities are - labeled. - *format* a Python number formatting string to be used in - labeling the flow as a quantity (i.e., a number - times a unit, where the unit is given) - *gap* space between paths that break in/break away - to/from the top or bottom - *radius* inner radius of the vertical paths - *shoulder* size of the shoulders of output arrowS - *offset* text offset (from the dip or tip of the arrow) - *head_angle* angle of the arrow heads (and negative of the angle - of the tails) [deg] - *margin* minimum space between Sankey outlines and the edge - of the plot area - *tolerance* acceptable maximum of the magnitude of the sum of - flows - The magnitude of the sum of connected flows cannot - be greater than *tolerance*. - =============== =================================================== - - The optional arguments listed above are applied to all subdiagrams so + The optional arguments listed below are applied to all subdiagrams so that there is consistent alignment and formatting. - If :class:`Sankey` is instantiated with any keyword arguments other - than those explicitly listed above (``**kwargs``), they will be passed - to :meth:`add`, which will create the first subdiagram. - In order to draw a complex Sankey diagram, create an instance of :class:`Sankey` by calling it without any kwargs:: @@ -109,6 +68,48 @@ def __init__(self, ax=None, scale=1.0, unit='', format='%G', gap=0.25, Sankey().add().add... .add().finish() + Other Parameters + ---------------- + ax : `~.axes.Axes` + Axes onto which the data should be plotted. If *ax* isn't + provided, new Axes will be created. + scale : float + Scaling factor for the flows. *scale* sizes the width of the paths + in order to maintain proper layout. The same scale is applied to + all subdiagrams. The value should be chosen such that the product + of the scale and the sum of the inputs is approximately 1.0 (and + the product of the scale and the sum of the outputs is + approximately -1.0). + unit : str + The physical unit associated with the flow quantities. If *unit* + is None, then none of the quantities are labeled. + format : str + A Python number formatting string to be used in labeling the flow + as a quantity (i.e., a number times a unit, where the unit is + given). + gap : float + Space between paths that break in/break away to/from the top or + bottom. + radius : float + Inner radius of the vertical paths. + shoulder : float + Size of the shoulders of output arrows. + offset : float + Text offset (from the dip or tip of the arrow). + head_angle : float + Angle, in degrees, of the arrow heads (and negative of the angle of + the tails). + margin : float + Minimum space between Sankey outlines and the edge of the plot + area. + tolerance : float + Acceptable maximum of the magnitude of the sum of flows. The + magnitude of the sum of connected flows cannot be greater than + *tolerance*. + **kwargs + Any additional keyword arguments will be passed to :meth:`add`, + which will create the first subdiagram. + See Also -------- Sankey.add @@ -168,15 +169,17 @@ def _arc(self, quadrant=0, cw=True, radius=1, center=(0, 0)): Return the codes and vertices for a rotated, scaled, and translated 90 degree arc. - Optional keyword arguments: - - =============== ========================================== - Keyword Description - =============== ========================================== - *quadrant* uses 0-based indexing (0, 1, 2, or 3) - *cw* if True, clockwise - *center* (x, y) tuple of the arc's center - =============== ========================================== + Other Parameters + ---------------- + quadrant : {0, 1, 2, 3}, default: 0 + Uses 0-based indexing (0, 1, 2, or 3). + cw : bool, default: True + If True, the arc vertices are produced clockwise; counter-clockwise + otherwise. + radius : float, default: 1 + The radius of the arc. + center : (float, float), default: (0, 0) + (x, y) tuple of the arc's center. """ # Note: It would be possible to use matplotlib's transforms to rotate, # scale, and translate the arc, but since the angles are discrete,