diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py index e2f47481b821..9d1181c0b41f 100644 --- a/lib/matplotlib/colorbar.py +++ b/lib/matplotlib/colorbar.py @@ -152,7 +152,7 @@ default to the current image. cax : :class:`~matplotlib.axes.Axes` object, optional - Axis into which the colorbar will be drawn + Axes into which the colorbar will be drawn. ax : :class:`~matplotlib.axes.Axes`, list of Axes, optional Parent axes from which space for a new colorbar axes will be stolen. diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 7d72a291d949..683100657508 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -7,7 +7,7 @@ control the default spacing of the subplots :class:`Figure` - top level container for all plot elements + Top level container for all plot elements. """ @@ -154,7 +154,6 @@ def current_key_axes(self): Return a tuple of ``(key, axes)`` for the active axes. If no axes exists on the stack, then returns ``(None, None)``. - """ if not len(self._elements): return self._default, self._default @@ -171,48 +170,44 @@ def __contains__(self, a): class SubplotParams(object): """ - A class to hold the parameters for a subplot + A class to hold the parameters for a subplot. """ def __init__(self, left=None, bottom=None, right=None, top=None, wspace=None, hspace=None): """ - All dimensions are fraction of the figure width or height. - All values default to their rc params - - The following attributes are available + All dimensions are fractions of the figure width or height. + Defaults are given by :rc:`figure.subplot.[name]`. - left : 0.125 - The left side of the subplots of the figure + Parameters + ---------- + left : float + The left side of the subplots of the figure. - right : 0.9 - The right side of the subplots of the figure + right : float + The right side of the subplots of the figure. - bottom : 0.1 - The bottom of the subplots of the figure + bottom : float + The bottom of the subplots of the figure. - top : 0.9 - The top of the subplots of the figure + top : float + The top of the subplots of the figure. - wspace : 0.2 + wspace : float The amount of width reserved for space between subplots, - expressed as a fraction of the average axis width + expressed as a fraction of the average axis width. - hspace : 0.2 + hspace : float The amount of height reserved for space between subplots, - expressed as a fraction of the average axis height + expressed as a fraction of the average axis height. """ - self.validate = True self.update(left, bottom, right, top, wspace, hspace) def update(self, left=None, bottom=None, right=None, top=None, wspace=None, hspace=None): """ - Update the current values. If any kwarg is None, default to - the current value, if set, otherwise to rc - + Update the dimensions of the passed parameters. *None* means unchanged. """ - thisleft = getattr(self, 'left', None) thisright = getattr(self, 'right', None) thistop = getattr(self, 'top', None) @@ -255,8 +250,9 @@ def _update_this(self, s, val): class Figure(Artist): - """ + The top level container for all the plot elements. + The Figure instance supports callbacks through a *callbacks* attribute which is a `.CallbackRegistry` instance. The events you can connect to are 'dpi_changed', and the callback will be called with ``func(fig)`` where @@ -284,12 +280,12 @@ def __repr__(self): ) def __init__(self, - figsize=None, # defaults to rc figure.figsize - dpi=None, # defaults to rc figure.dpi - facecolor=None, # defaults to rc figure.facecolor - edgecolor=None, # defaults to rc figure.edgecolor - linewidth=0.0, # the default linewidth of the frame - frameon=None, # whether or not to draw the figure frame + figsize=None, + dpi=None, + facecolor=None, + edgecolor=None, + linewidth=0.0, + frameon=None, subplotpars=None, # default to rc tight_layout=None, # default to rc figure.autolayout constrained_layout=None, # default to rc @@ -298,34 +294,35 @@ def __init__(self, """ Parameters ---------- - figsize : 2-tuple of floats - ``(width, height)`` tuple in inches + figsize : 2-tuple of floats, default: :rc:`figure.figsize` + Figure dimension ``(width, height)`` in inches. - dpi : float - Dots per inch + dpi : float, default: :rc:`figure.dpi` + Dots per inch. - facecolor - The figure patch facecolor; defaults to rc ``figure.facecolor`` + facecolor : default: :rc:`figure.facecolor` + The figure patch facecolor. - edgecolor - The figure patch edge color; defaults to rc ``figure.edgecolor`` + edgecolor : default: :rc:`figure.edgecolor` + The figure patch edge color. linewidth : float - The figure patch edge linewidth; the default linewidth of the frame + The linewidth of the frame (i.e. the edge linewidth of the figure + patch). - frameon : bool - If ``False``, suppress drawing the figure frame + frameon : bool, default: :rc:`figure.frameon` + If ``False``, suppress drawing the figure frame. subplotpars : :class:`SubplotParams` - Subplot parameters, defaults to rc + Subplot parameters. If not given, the default subplot + parameters :rc:`figure.subplot.*` are used. - tight_layout : bool - If ``False`` use *subplotpars*; if ``True`` adjust subplot + tight_layout : bool or dict, default: :rc:`figure.autolayout` + If ``False`` use *subplotpars*. If ``True`` adjust subplot parameters using `.tight_layout` with default padding. - When providing a dict containing the keys - ``pad``, ``w_pad``, ``h_pad``, and ``rect``, the default - `.tight_layout` paddings will be overridden. - Defaults to rc ``figure.autolayout``. + When providing a dict containing the keys ``pad``, ``w_pad``, + ``h_pad``, and ``rect``, the default `.tight_layout` paddings + will be overridden. constrained_layout : bool If ``True`` use constrained layout to adjust positioning of plot @@ -334,7 +331,7 @@ def __init__(self, :doc:`/tutorials/intermediate/constrainedlayout_guide` for examples. (Note: does not work with :meth:`.subplot` or :meth:`.subplot2grid`.) - Defaults to rc ``figure.constrained_layout.use``. + Defaults to :rc:`figure.constrained_layout.use`. """ Artist.__init__(self) # remove the non-figure artist _axes property @@ -404,7 +401,7 @@ def __init__(self, self._align_ylabel_grp = cbook.Grouper() @property - @cbook.deprecated("2.1", alternative="Figure.patch") + @cbook.deprecated("2.1", alternative="`.Figure.patch`") def figurePatch(self): return self.patch @@ -462,7 +459,12 @@ def show(self, warn=True): def _get_axes(self): return self._axstack.as_list() - axes = property(fget=_get_axes, doc="Read-only: list of axes in Figure") + axes = property(fget=_get_axes, + doc="List of axes in the Figure. You can access the " + "axes in the Figure through this list. " + "Do not modify the list itself. Instead, use " + "`~Figure.add_axes`, `~.Figure.subplot` or " + "`~.Figure.delaxes` to add or remove an axes.") def _get_dpi(self): return self._dpi @@ -482,12 +484,10 @@ def _set_dpi(self, dpi, forward=True): self.set_size_inches(w, h, forward=forward) self.callbacks.process('dpi_changed', self) - dpi = property(_get_dpi, _set_dpi) + dpi = property(_get_dpi, _set_dpi, doc="The resolution in dots per inch.") def get_tight_layout(self): - """ - Return whether and how `.tight_layout` is called when drawing. - """ + """Return whether `.tight_layout` is called when drawing.""" return self._tight def set_tight_layout(self, tight): @@ -517,7 +517,7 @@ def get_constrained_layout(self): """ Return a boolean: True means constrained layout is being used. - See :doc:`/tutorials/intermediate/constrainedlayout_guide` + See :doc:`/tutorials/intermediate/constrainedlayout_guide`. """ return self._constrained @@ -533,7 +533,7 @@ def set_constrained_layout(self, constrained): ACCEPTS: [True | False | dict | None ] - See :doc:`/tutorials/intermediate/constrainedlayout_guide` + See :doc:`/tutorials/intermediate/constrainedlayout_guide`. """ self._constrained_layout_pads = dict() self._constrained_layout_pads['w_pad'] = None @@ -555,7 +555,7 @@ def set_constrained_layout_pads(self, **kwargs): Set padding for ``constrained_layout``. Note the kwargs can be passed as a dictionary ``fig.set_constrained_layout(**paddict)``. - See :doc:`/tutorials/intermediate/constrainedlayout_guide` + See :doc:`/tutorials/intermediate/constrainedlayout_guide`. Parameters ---------- @@ -593,7 +593,7 @@ def get_constrained_layout_pads(self, relative=False): Returns a list of `w_pad, h_pad` in inches and `wspace` and `hspace` as fractions of the subplot. - See :doc:`/tutorials/intermediate/constrainedlayout_guide` + See :doc:`/tutorials/intermediate/constrainedlayout_guide`. Parameters ---------- @@ -626,17 +626,17 @@ def autofmt_xdate(self, bottom=0.2, rotation=30, ha='right', which=None): Parameters ---------- bottom : scalar - The bottom of the subplots for :meth:`subplots_adjust` + The bottom of the subplots for :meth:`subplots_adjust`. rotation : angle in degrees - The rotation of the xtick labels + The rotation of the xtick labels. ha : string - The horizontal alignment of the xticklabels + The horizontal alignment of the xticklabels. which : {None, 'major', 'minor', 'both'} - Selects which ticklabels to rotate (default is None which works - same as major) + Selects which ticklabels to rotate. Default is None which works + the same as major. """ allsubplots = all(hasattr(ax, 'is_last_row') for ax in self.axes) if len(self.axes) == 1: @@ -675,7 +675,9 @@ def contains(self, mouseevent): """ Test whether the mouse event occurred on the figure. - Returns True, {}. + Returns + ------- + bool, {} """ if callable(self._contains): return self._contains(self, mouseevent) @@ -684,7 +686,7 @@ def contains(self, mouseevent): def get_window_extent(self, *args, **kwargs): """ - Return figure bounding box in display space; arguments are ignored. + Return the figure bounding box in display space. Arguments are ignored. """ return self.bbox @@ -783,71 +785,74 @@ def hold(self, b=None): else: self._hold = b - def figimage(self, X, - xo=0, - yo=0, - alpha=None, - norm=None, - cmap=None, - vmin=None, - vmax=None, - origin=None, - resize=False, - **kwargs): + def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None, + vmin=None, vmax=None, origin=None, resize=False, **kwargs): """ - Adds a non-resampled image to the figure. + Add a non-resampled image to the figure. - call signatures:: + The image is attached to the lower or upper left corner depending on + *origin*. - figimage(X, **kwargs) + Parameters + ---------- + X + The image data. This is an array of one of the following shapes: - adds a non-resampled array *X* to the figure. + - MxN: luminance (grayscale) values + - MxNx3: RGB values + - MxNx4: RGBA values - :: + xo, yo : int + The *x*/*y* image offset in pixels. + + alpha : None or float + The alpha blending value. + + norm : :class:`matplotlib.colors.Normalize` + A :class:`.Normalize` instance to map the luminance to the + interval [0, 1]. + + cmap : str or :class:`matplotlib.colors.Colormap` + The colormap to use. Default: :rc:`image.cmap`. + + vmin, vmax : scalar + If *norm* is not given, these values set the data limits for the + colormap. + + origin : {'upper', 'lower'} + Indicates where the [0, 0] index of the array is in the upper left + or lower left corner of the axes. Defaults to :rc:`image.origin`. - figimage(X, xo, yo) - - with pixel offsets *xo*, *yo*, - - *X* must be a float array: - - * If *X* is MxN, assume luminance (grayscale) - * If *X* is MxNx3, assume RGB - * If *X* is MxNx4, assume RGBA - - Optional keyword arguments: - - ========= ========================================================= - Keyword Description - ========= ========================================================= - resize a boolean, True or False. If "True", then re-size the - Figure to match the given image size. - xo or yo An integer, the *x* and *y* image offset in pixels - cmap a :class:`matplotlib.colors.Colormap` instance, e.g., - cm.jet. If *None*, default to the rc ``image.cmap`` - value - norm a :class:`matplotlib.colors.Normalize` instance. The - default is normalization(). This scales luminance -> 0-1 - vmin|vmax are used to scale a luminance image to 0-1. If either - is *None*, the min and max of the luminance values will - be used. Note if you pass a norm instance, the settings - for *vmin* and *vmax* will be ignored. - alpha the alpha blending value, default is *None* - origin [ 'upper' | 'lower' ] Indicates where the [0,0] index of - the array is in the upper left or lower left corner of - the axes. Defaults to the rc image.origin value - ========= ========================================================= + resize : bool + If *True*, resize the figure to match the given image size. + Returns + ------- + :class:`matplotlib.image.FigureImage` + + Other Parameters + ---------------- + **kwargs + Additional kwargs are `.Artist` kwargs passed on to `.FigureImage`. + + Notes + ----- figimage complements the axes image (:meth:`~matplotlib.axes.Axes.imshow`) which will be resampled to fit the current axes. If you want a resampled image to fill the entire figure, you can define an :class:`~matplotlib.axes.Axes` with extent [0,0,1,1]. - An :class:`matplotlib.image.FigureImage` instance is returned. - Additional kwargs are Artist kwargs passed on to - :class:`~matplotlib.image.FigureImage` + Examples:: + + f = plt.figure() + nx = int(f.get_figwidth() * f.dpi) + ny = int(f.get_figheight() * f.dpi) + data = np.random.random((ny, nx)) + f.figimage(data) + plt.show() + """ if not self._hold: @@ -912,13 +917,12 @@ def set_size_inches(self, w, h=None, forward=True): def get_size_inches(self): """ - Returns the current size of the figure in inches (1in == 2.54cm) - as an numpy array. + Returns the current size of the figure in inches. Returns ------- size : ndarray - The size of the figure in inches + The size (width, height) of the figure in inches. See Also -------- @@ -935,24 +939,24 @@ def get_facecolor(self): return self.patch.get_facecolor() def get_figwidth(self): - """Return the figwidth as a float.""" + """Return the figure width as a float.""" return self.bbox_inches.width def get_figheight(self): - """Return the figheight as a float.""" + """Return the figure height as a float.""" return self.bbox_inches.height def get_dpi(self): - """Return the dpi as a float.""" + """Return the resolution in dots per inch as a float.""" return self.dpi def get_frameon(self): - """Get the boolean indicating frameon.""" + """Return whether the figure frame will be drawn.""" return self.frameon def set_edgecolor(self, color): """ - Set the edge color of the Figure rectangle + Set the edge color of the Figure rectangle. ACCEPTS: any matplotlib color - see help(colors) """ @@ -960,7 +964,7 @@ def set_edgecolor(self, color): def set_facecolor(self, color): """ - Set the face color of the Figure rectangle + Set the face color of the Figure rectangle. ACCEPTS: any matplotlib color - see help(colors) """ @@ -968,7 +972,7 @@ def set_facecolor(self, color): def set_dpi(self, val): """ - Set the dots-per-inch of the figure + Set the dots-per-inch of the figure. ACCEPTS: float """ @@ -977,7 +981,7 @@ def set_dpi(self, val): def set_figwidth(self, val, forward=True): """ - Set the width of the figure in inches + Set the width of the figure in inches. ACCEPTS: float """ @@ -985,7 +989,7 @@ def set_figwidth(self, val, forward=True): def set_figheight(self, val, forward=True): """ - Set the height of the figure in inches + Set the height of the figure in inches. ACCEPTS: float """ @@ -1041,18 +1045,20 @@ def fixlist(args): def add_axes(self, *args, **kwargs): """ - Add an axes at position *rect* [*left*, *bottom*, *width*, - *height*] where all quantities are in fractions of figure - width and height. + Add an axes to the figure. + + Call signature:: + + add_axes(rect, projection=None, polar=False, **kwargs) Parameters ---------- rect : sequence of float - A 4-length sequence of [left, bottom, width, height] quantities. + The dimensions [left, bottom, width, height] of the new axes. All + quantities are in fractions of figure width and height. - projection : - ['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \ -'polar' | 'rectilinear'], optional + projection : {None, 'aitoff', 'hammer', 'lambert', 'mollweide', \ +'polar', rectilinear'}, optional The projection type of the axes. polar : boolean, optional @@ -1069,9 +1075,9 @@ def add_axes(self, *args, **kwargs): Examples -------- - A simple example:: + Some simple examples:: - rect = l,b,w,h + rect = l, b, w, h fig.add_axes(rect) fig.add_axes(rect, frameon=False, facecolor='g') fig.add_axes(rect, polar=True) @@ -1146,6 +1152,11 @@ def add_subplot(self, *args, **kwargs): """ Add a subplot. + Call signatures:: + + add_subplot(nrows, ncols, index, **kwargs) + add_subplot(pos, **kwargs) + Parameters ---------- *args @@ -1154,8 +1165,8 @@ def add_subplot(self, *args, **kwargs): integers are R, C, and P in order, the subplot will take the Pth position on a grid with R rows and C columns. - projection : ['aitoff' | 'hammer' | 'lambert' | \ -'mollweide' | 'polar' | 'rectilinear'], optional + projection : {None, 'aitoff', 'hammer', 'lambert', 'mollweide', \ +'polar', rectilinear'}, optional The projection type of the axes. polar : boolean, optional @@ -1491,6 +1502,15 @@ def draw_artist(self, a): a.draw(self._cachedRenderer) def get_axes(self): + """ + Return a list of axes in the Figure. You can access and modify the + axes in the Figure through this list. + + Do not modify the list itself. Instead, use `~Figure.add_axes`, + `~.Figure.subplot` or `~.Figure.delaxes` to add or remove an axes. + + Note: This is equivalent to the property `~.Figure.axes`. + """ return self.axes @docstring.dedent_interpd @@ -1770,7 +1790,7 @@ def _set_artist_props(self, a): @docstring.dedent_interpd def gca(self, **kwargs): """ - Get the current axes, creating one if necessary + Get the current axes, creating one if necessary. The following kwargs are supported for ensuring the returned axes adheres to the given projection etc., and for axes creation if @@ -2194,9 +2214,7 @@ def get_tightbbox(self, renderer): return bbox_inches def init_layoutbox(self): - """ - Initialize the layoutbox for use in constrained_layout. - """ + """Initialize the layoutbox for use in constrained_layout.""" if self._layoutbox is None: self._layoutbox = layoutbox.LayoutBox(parent=None, name='figlb', @@ -2207,7 +2225,7 @@ def execute_constrained_layout(self, renderer=None): """ Use ``layoutbox`` to determine pos positions within axes. - See also set_constrained_layout_pads. + See also `.set_constrained_layout_pads`. """ from matplotlib._constrained_layout import do_constrained_layout @@ -2282,9 +2300,9 @@ def align_xlabels(self, axs=None): Parameters ---------- - axs : list of `~matplotlib.axes.Axes` (None) - Optional list of (or ndarray) `~matplotlib.axes.Axes` to align - the xlabels. Default is to align all axes on the figure. + axs : list of `~matplotlib.axes.Axes` + Optional list of (or ndarray) `.Axes` to align the xlabels. + Default is to align all axes on the figure. See Also -------- @@ -2350,9 +2368,9 @@ def align_ylabels(self, axs=None): Parameters ---------- - axs : list of `~matplotlib.axes.Axes` (None) - Optional list (or ndarray) of `~matplotlib.axes.Axes` to align - the ylabels. Default is to align all axes on the figure. + axs : list of `~matplotlib.axes.Axes` + Optional list (or ndarray) of `.Axes` to align the ylabels. + Default is to align all axes on the figure. See Also -------- @@ -2413,9 +2431,9 @@ def align_labels(self, axs=None): Parameters ---------- - axs : list of `~matplotlib.axes.Axes` (None) - Optional list (or ndarray) of `~matplotlib.axes.Axes` to - align the labels. Default is to align all axes on the figure. + axs : list of `~matplotlib.axes.Axes` + Optional list (or ndarray) of `.Axes` to align the labels. + Default is to align all axes on the figure. See Also --------