diff --git a/doc/api/figure_api.rst b/doc/api/figure_api.rst index 1beb0a701b26..84d068f5c3af 100644 --- a/doc/api/figure_api.rst +++ b/doc/api/figure_api.rst @@ -5,5 +5,304 @@ .. currentmodule:: matplotlib.figure .. automodule:: matplotlib.figure - :members: - :inherited-members: + :no-members: + :no-undoc-members: + +The Figure class +================ +.. autosummary:: + :toctree: _as_gen + :template: autosummary_class_only.rst + :nosignatures: + + Figure + + +Adding Axes and SubFigures +========================== + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + Figure.add_axes + Figure.add_subplot + Figure.subplots + Figure.subplot_mosaic + Figure.add_gridspec + Figure.get_axes + Figure.axes + Figure.delaxes + Figure.subfigures + Figure.add_subfigure + +Saving +====== + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + Figure.savefig + + +Annotating +========== + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + Figure.colorbar + Figure.legend + Figure.text + Figure.suptitle + Figure.get_suptitle + Figure.supxlabel + Figure.get_supxlabel + Figure.supylabel + Figure.get_supylabel + Figure.align_labels + Figure.align_xlabels + Figure.align_ylabels + Figure.autofmt_xdate + + +Figure geometry +=============== + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + Figure.set_size_inches + Figure.get_size_inches + Figure.set_figheight + Figure.get_figheight + Figure.set_figwidth + Figure.get_figwidth + Figure.dpi + Figure.set_dpi + Figure.set_dpi + +Subplot layout +============== + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + Figure.subplots_adjust + Figure.set_layout_engine + Figure.get_layout_engine + +Discouraged or deprecated +------------------------- + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + Figure.tight_layout + Figure.set_tight_layout + Figure.get_tight_layout + Figure.set_constrained_layout + Figure.get_constrained_layout + Figure.set_constrained_layout_pads + Figure.get_constrained_layout_pads + +Interactive +=========== + +.. seealso:: + + - :ref:`event-handling` + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + Figure.ginput + Figure.add_axobserver + Figure.waitforbuttonpress + Figure.pick + +Modifying appearance +==================== + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + Figure.set_frameon + Figure.get_frameon + Figure.set_linewidth + Figure.get_linewidth + Figure.set_facecolor + Figure.get_facecolor + Figure.set_edgecolor + Figure.get_edgecolor + +Adding and getting Artists +========================== + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + Figure.add_artist + Figure.get_children + Figure.figimage + +Getting and modifying state +=========================== + +.. seealso:: + + - :ref:`interactive_figures` + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + Figure.clear + Figure.gca + Figure.sca + Figure.get_tightbbox + Figure.get_window_extent + Figure.show + Figure.set_canvas + Figure.draw + Figure.draw_without_rendering + Figure.draw_artist + +.. _figure-api-subfigure: + +SubFigure +========= + +Matplotlib has the concept of a `~.SubFigure`, which is a logical figure inside +a parent `~.Figure`. It has many of the same methods as the parent. See +:ref:`nested_axes_layouts`. + +.. plot:: + + fig = plt.figure(layout='constrained', figsize=(4, 2.5), facecolor='lightgoldenrodyellow') + + # Make two subfigures, left ones more narrow than right ones: + sfigs = fig.subfigures(1, 2, width_ratios=[0.8, 1]) + sfigs[0].set_facecolor('khaki') + sfigs[1].set_facecolor('lightsalmon') + + # Add subplots to left subfigure: + lax = sfigs[0].subplots(2, 1) + sfigs[0].suptitle('Left subfigure') + + # Add subplots to right subfigure: + rax = sfigs[1].subplots(1, 2) + sfigs[1].suptitle('Right subfigure') + + # suptitle for the main figure: + fig.suptitle('Figure') + +SubFigure class +--------------- + +.. autosummary:: + :toctree: _as_gen + :template: autosummary_class_only.rst + :nosignatures: + + SubFigure + +Adding Axes and SubFigures +-------------------------- +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + SubFigure.add_axes + SubFigure.add_subplot + SubFigure.subplots + SubFigure.subplot_mosaic + SubFigure.add_gridspec + SubFigure.delaxes + SubFigure.add_subfigure + SubFigure.subfigures + +Annotating +---------- + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + SubFigure.colorbar + SubFigure.legend + SubFigure.text + SubFigure.suptitle + SubFigure.get_suptitle + SubFigure.supxlabel + SubFigure.get_supxlabel + SubFigure.supylabel + SubFigure.get_supylabel + SubFigure.align_labels + SubFigure.align_xlabels + SubFigure.align_ylabels + +Adding and getting Artists +-------------------------- + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + SubFigure.add_artist + SubFigure.get_children + +Modifying appearance +-------------------- + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + SubFigure.set_frameon + SubFigure.get_frameon + SubFigure.set_linewidth + SubFigure.get_linewidth + SubFigure.set_facecolor + SubFigure.get_facecolor + SubFigure.set_edgecolor + SubFigure.get_edgecolor + +Passthroughs +------------ + +.. autosummary:: + :toctree: _as_gen + :template: autosummary.rst + :nosignatures: + + SubFigure.set_dpi + SubFigure.get_dpi + + +FigureBase parent class +======================= + +.. autoclass:: FigureBase diff --git a/doc/api/prev_api_changes/api_changes_3.4.2.rst b/doc/api/prev_api_changes/api_changes_3.4.2.rst index 2de543be37d6..34d760bf0941 100644 --- a/doc/api/prev_api_changes/api_changes_3.4.2.rst +++ b/doc/api/prev_api_changes/api_changes_3.4.2.rst @@ -7,7 +7,7 @@ Behaviour changes Rename first argument to ``subplot_mosaic`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Both `.FigureBase.subplot_mosaic`, and `.pyplot.subplot_mosaic` have had the +Both `.Figure.subplot_mosaic`, and `.pyplot.subplot_mosaic` have had the first position argument renamed from *layout* to *mosaic*. This is because we are considering to consolidate *constrained_layout* and *tight_layout* keyword arguments in the Figure creation functions of `.pyplot` into a single *layout* diff --git a/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst b/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst index 69e38270ca76..278cad0a29c1 100644 --- a/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst +++ b/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst @@ -4,7 +4,7 @@ Behaviour changes First argument to ``subplot_mosaic`` renamed ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Both `.FigureBase.subplot_mosaic`, and `.pyplot.subplot_mosaic` have had the +Both `.Figure.subplot_mosaic`, and `.pyplot.subplot_mosaic` have had the first positional argument renamed from *layout* to *mosaic*. As we have consolidated the *constrained_layout* and *tight_layout* keyword arguments in the Figure creation functions of `.pyplot` into a single *layout* keyword diff --git a/doc/users/prev_whats_new/whats_new_3.4.0.rst b/doc/users/prev_whats_new/whats_new_3.4.0.rst index f90a95c7f126..707b43ab73b9 100644 --- a/doc/users/prev_whats_new/whats_new_3.4.0.rst +++ b/doc/users/prev_whats_new/whats_new_3.4.0.rst @@ -634,8 +634,8 @@ supxlabel and supylabel ----------------------- It is possible to add x- and y-labels to a whole figure, analogous to -`.FigureBase.suptitle` using the new `.FigureBase.supxlabel` and -`.FigureBase.supylabel` methods. +`.Figure.suptitle` using the new `.Figure.supxlabel` and +`.Figure.supylabel` methods. .. plot:: diff --git a/galleries/examples/subplots_axes_and_figures/figure_title.py b/galleries/examples/subplots_axes_and_figures/figure_title.py index bc8a90366d8e..118157f0579c 100644 --- a/galleries/examples/subplots_axes_and_figures/figure_title.py +++ b/galleries/examples/subplots_axes_and_figures/figure_title.py @@ -5,10 +5,10 @@ Each axes can have a title (or actually three - one each with *loc* "left", "center", and "right"), but is sometimes desirable to give a whole figure -(or `.SubFigure`) an overall title, using `.FigureBase.suptitle`. +(or `.SubFigure`) an overall title, using `.Figure.suptitle`. -We can also add figure-level x- and y-labels using `.FigureBase.supxlabel` and -`.FigureBase.supylabel`. +We can also add figure-level x- and y-labels using `.Figure.supxlabel` and +`.Figure.supylabel`. """ import matplotlib.pyplot as plt @@ -31,8 +31,8 @@ fig.suptitle('Different types of oscillations', fontsize=16) # %% -# A global x- or y-label can be set using the `.FigureBase.supxlabel` and -# `.FigureBase.supylabel` methods. +# A global x- or y-label can be set using the `.Figure.supxlabel` and +# `.Figure.supylabel` methods. with get_sample_data('Stocks.csv') as file: diff --git a/galleries/examples/subplots_axes_and_figures/gridspec_nested.py b/galleries/examples/subplots_axes_and_figures/gridspec_nested.py index a2750a0ecb49..bfcb90cdfc4a 100644 --- a/galleries/examples/subplots_axes_and_figures/gridspec_nested.py +++ b/galleries/examples/subplots_axes_and_figures/gridspec_nested.py @@ -7,7 +7,7 @@ set the position for a nested grid of subplots. Note that the same functionality can be achieved more directly with -`~.FigureBase.subfigures`; see +`~.Figure.subfigures`; see :doc:`/gallery/subplots_axes_and_figures/subfigures`. """ diff --git a/galleries/users_explain/axes/arranging_axes.py b/galleries/users_explain/axes/arranging_axes.py index 79b69f4bf3dd..8068d3b92ad3 100644 --- a/galleries/users_explain/axes/arranging_axes.py +++ b/galleries/users_explain/axes/arranging_axes.py @@ -228,6 +228,8 @@ def annotate_axes(ax, text, fontsize=18): fig.suptitle('plt.subplot_mosaic()') # %% +# .. _nested_axes_layouts: +# # Nested Axes layouts # ------------------- # diff --git a/galleries/users_explain/figure/figure_intro.rst b/galleries/users_explain/figure/figure_intro.rst index 745b01566427..5f7db3d0202c 100644 --- a/galleries/users_explain/figure/figure_intro.rst +++ b/galleries/users_explain/figure/figure_intro.rst @@ -197,15 +197,15 @@ common cases. Adding Artists -------------- -The `~.FigureBase` class has a number of methods to add artists to a `~.Figure` or +The `~.Figure` class has a number of methods for adding artists to a `~.Figure` or a `~.SubFigure`. By far the most common are to add Axes of various configurations -(`~.FigureBase.add_axes`, `~.FigureBase.add_subplot`, `~.FigureBase.subplots`, -`~.FigureBase.subplot_mosaic`) and subfigures (`~.FigureBase.subfigures`). Colorbars -are added to Axes or group of Axes at the Figure level (`~.FigureBase.colorbar`). -It is also possible to have a Figure-level legend (`~.FigureBase.legend`). -Other Artists include figure-wide labels (`~.FigureBase.suptitle`, -`~.FigureBase.supxlabel`, `~.FigureBase.supylabel`) and text (`~.FigureBase.text`). -Finally, low-level Artists can be added directly using `~.FigureBase.add_artist` +(`~.Figure.add_axes`, `~.Figure.add_subplot`, `~.Figure.subplots`, +`~.Figure.subplot_mosaic`) and subfigures (`~.Figure.subfigures`). Colorbars +are added to Axes or group of Axes at the Figure level (`~.Figure.colorbar`). +It is also possible to have a Figure-level legend (`~.Figure.legend`). +Other Artists include figure-wide labels (`~.Figure.suptitle`, +`~.Figure.supxlabel`, `~.Figure.supylabel`) and text (`~.Figure.text`). +Finally, low-level Artists can be added directly using `~.Figure.add_artist` usually with care being taken to use the appropriate transform. Usually these include ``Figure.transFigure`` which ranges from 0 to 1 in each direction, and represents the fraction of the current Figure size, or ``Figure.dpi_scale_trans`` diff --git a/galleries/users_explain/figure/index.rst b/galleries/users_explain/figure/index.rst index 4433246e4074..753c24b62a5c 100644 --- a/galleries/users_explain/figure/index.rst +++ b/galleries/users_explain/figure/index.rst @@ -1,3 +1,5 @@ +.. _figures_and_backends: + ++++++++++++++++++++ Figures and backends ++++++++++++++++++++ diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py index 04eaa6cf75df..4a495531d900 100644 --- a/lib/matplotlib/artist.py +++ b/lib/matplotlib/artist.py @@ -506,7 +506,7 @@ def pickable(self): See Also -------- - set_picker, get_picker, pick + .Artist.set_picker, .Artist.get_picker, .Artist.pick """ return self.figure is not None and self._picker is not None @@ -519,7 +519,7 @@ def pick(self, mouseevent): See Also -------- - set_picker, get_picker, pickable + .Artist.set_picker, .Artist.get_picker, .Artist.pickable """ from .backend_bases import PickEvent # Circular import. # Pick self @@ -586,11 +586,11 @@ def get_picker(self): """ Return the picking behavior of the artist. - The possible values are described in `.set_picker`. + The possible values are described in `.Artist.set_picker`. See Also -------- - set_picker, pickable, pick + .Artist.set_picker, .Artist.pickable, .Artist.pick """ return self._picker diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index d37dda204278..c750095aee18 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1438,8 +1438,12 @@ def align_labels(self, axs=None): def add_gridspec(self, nrows=1, ncols=1, **kwargs): """ - Return a `.GridSpec` that has this figure as a parent. This allows - complex layout of Axes in the figure. + Low-level API for creating a `.GridSpec` that has this figure as a parent. + + This is a low-level API, allowing you to create a gridspec and + subsequently add subplots based on the gridspec. Most users do + not need that freedom and should use the higher-level methods + `~.Figure.subplots` or `~.Figure.subplot_mosaic`. Parameters ---------- @@ -1663,6 +1667,9 @@ def _process_projection_requirements(self, *, axes_class=None, polar=False, return projection_class, kwargs def get_default_bbox_extra_artists(self): + """ + Return a list of Artists typically used in `.Figure.get_tightbbox`. + """ bbox_artists = [artist for artist in self.get_children() if (artist.get_visible() and artist.get_in_layout())] for ax in self.axes: @@ -2088,6 +2095,7 @@ class SubFigure(FigureBase): """ Logical figure that can be placed inside a figure. + See :ref:`figure-api-subfigure` for an index of methods on this class. Typically instantiated using `.Figure.add_subfigure` or `.SubFigure.add_subfigure`, or `.SubFigure.subfigures`. A subfigure has the same methods as a figure except for those particularly tied to the size @@ -2299,6 +2307,8 @@ class Figure(FigureBase): """ The top level container for all the plot elements. + See `matplotlib.figure` for an index of class methods. + Attributes ---------- patch @@ -2715,21 +2725,21 @@ def _set_dpi(self, dpi, forward=True): dpi = property(_get_dpi, _set_dpi, doc="The resolution in dots per inch.") def get_tight_layout(self): - """Return whether `.tight_layout` is called when drawing.""" + """Return whether `.Figure.tight_layout` is called when drawing.""" return isinstance(self.get_layout_engine(), TightLayoutEngine) @_api.deprecated("3.6", alternative="set_layout_engine", pending=True) def set_tight_layout(self, tight): """ - Set whether and how `.tight_layout` is called when drawing. + Set whether and how `.Figure.tight_layout` is called when drawing. Parameters ---------- tight : bool or dict with keys "pad", "w_pad", "h_pad", "rect" or None - If a bool, sets whether to call `.tight_layout` upon drawing. + If a bool, sets whether to call `.Figure.tight_layout` upon drawing. If ``None``, use :rc:`figure.autolayout` instead. - If a dict, pass it as kwargs to `.tight_layout`, overriding the + If a dict, pass it as kwargs to `.Figure.tight_layout`, overriding the default paddings. """ if tight is None: @@ -3170,7 +3180,7 @@ def add_axobserver(self, func): def savefig(self, fname, *, transparent=None, **kwargs): """ - Save the current figure. + Save the current figure as an image or vector graphic to a file. Call signature::