diff --git a/doc/_static/FigureInline.png b/doc/_static/FigureInline.png new file mode 100644 index 000000000000..6b7bd42c28f1 Binary files /dev/null and b/doc/_static/FigureInline.png differ diff --git a/doc/_static/FigureNotebook.png b/doc/_static/FigureNotebook.png new file mode 100644 index 000000000000..2d6d11cac3cc Binary files /dev/null and b/doc/_static/FigureNotebook.png differ diff --git a/doc/_static/FigureQtAgg.png b/doc/_static/FigureQtAgg.png new file mode 100644 index 000000000000..8d19e1a309ef Binary files /dev/null and b/doc/_static/FigureQtAgg.png differ diff --git a/doc/users/explain/figures.rst b/doc/users/explain/figures.rst index f5fb3142d297..617281a60f61 100644 --- a/doc/users/explain/figures.rst +++ b/doc/users/explain/figures.rst @@ -34,23 +34,57 @@ using Matplotlib, and what :ref:`Backend ` you are using. Notebooks and IDEs ------------------ +.. figure:: /_static/FigureInline.png + :alt: Image of figure generated in Jupyter Notebook with inline backend. + :width: 400 + + Screenshot of a `Jupyter Notebook `_, with a figure + generated via the default `inline + `_ backend. + + If you are using a Notebook (e.g. `Jupyter `_) or an IDE that renders Notebooks (PyCharm, VSCode, etc), then they have a backend that will render the Matplotlib Figure when a code cell is executed. One thing to be aware of is that the default Jupyter backend (``%matplotlib inline``) will by default trim or expand the figure size to have a tight box around Artists -added to the Figure (see :ref:`saving_figures`, below). +added to the Figure (see :ref:`saving_figures`, below). If you use a backend +other than the default "inline" backend, you will likely need to use an ipython +"magic" like ``%matplotlib notebook`` for the Matplotlib :ref:`notebook +` or ``%matplotlib widget`` for the `ipympl +`_ backend. + +.. figure:: /_static/FigureNotebook.png + :alt: Image of figure generated in Jupyter Notebook with notebook + backend, including a toolbar. + :width: 400 + + Screenshot of a Jupyter Notebook with an interactive figure generated via + the ``%matplotlib notebook`` magic. Users should also try the similar + `widget `_ backend if using `JupyterLab + `_. + + +.. seealso:: + :ref:`interactive_figures`. Standalone scripts and interactive use -------------------------------------- If the user is on a client with a windowing system, there are a number of :ref:`Backends ` that can be used to render the Figure to -the screen, usually using a Python Qt, Tk, or Wx toolkit, though there is a native -MacOS backend as well. These are typically chosen either in the user's -:ref:`matplotlibrc `, or by calling +the screen, usually using a Python Qt, Tk, or Wx toolkit, or the native MacOS +backend. These are typically chosen either in the user's :ref:`matplotlibrc +`, or by calling, for example, ``matplotlib.use('QtAgg')`` at the beginning of a session or script. +.. figure:: /_static/FigureQtAgg.png + :alt: Image of figure generated from a script via the QtAgg backend. + :width: 370 + + Screenshot of a Figure generated via a python script and shown using the + QtAgg backend. + When run from a script, or interactively (e.g. from an `iPython shell `_) the Figure will not be shown until we call ``plt.show()``. The Figure will appear in @@ -64,6 +98,9 @@ Note that if you are on a client that does not have access to a windowing system, the Figure will fallback to being drawn using the "Agg" backend, and cannot be viewed, though it can be :ref:`saved `. +.. seealso:: + :ref:`interactive_figures`. + .. _creating_figures: Creating Figures diff --git a/doc/users/explain/interactive.rst b/doc/users/explain/interactive.rst index 43b6327815f9..83d1ee2835a6 100644 --- a/doc/users/explain/interactive.rst +++ b/doc/users/explain/interactive.rst @@ -3,6 +3,7 @@ .. currentmodule:: matplotlib .. _mpl-shell: +.. _interactive_figures: =================== Interactive figures @@ -12,6 +13,10 @@ When working with data, interactivity can be invaluable. The pan/zoom and mouse-location tools built into the Matplotlib GUI windows are often sufficient, but you can also use the event system to build customized data exploration tools. +.. seealso:: + :ref:`figure_explanation`. + + Matplotlib ships with :ref:`backends ` binding to several GUI toolkits (Qt, Tk, Wx, GTK, macOS, JavaScript) and third party packages provide bindings to `kivy @@ -42,7 +47,9 @@ collected. `.Figure`\s can be closed and deregistered from `.pyplot` individuall `.pyplot.close`; all open `.Figure`\s can be closed via ``plt.close('all')``. -For more discussion of Matplotlib's event system and integrated event loops, please read: +.. seealso:: + + For more discussion of Matplotlib's event system and integrated event loops: - :ref:`interactive_figures_and_eventloops` - :ref:`event-handling-tutorial` @@ -246,6 +253,7 @@ and your figures may not be responsive. Please consult the documentation of your GUI toolkit for details. +.. _jupyter_notebooks_jupyterlab: Jupyter Notebooks / JupyterLab ------------------------------ diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 27b16b17a86b..289273ad2fd6 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -13,8 +13,22 @@ `SubplotParams` Control the default spacing between subplots. -See :ref:`figure_explanation` for narrative on how figures are used in -Matplotlib. +Figures are typically created using pyplot methods `~.pyplot.figure`, +`~.pyplot.subplots`, and `~.pyplot.subplot_mosaic`. + +.. plot:: + :include-source: + + fig, ax = plt.subplots(figsize=(2, 2), facecolor='lightskyblue', + layout='constrained') + fig.suptitle('Figure') + ax.set_title('Axes', loc='left', fontstyle='oblique', fontsize='medium') + +Some situations call for directly instantiating a `~.figure.Figure` class, +usually inside an application of some sort (see :ref:`user_interfaces` for a +list of examples) . More information about Figures can be found at +:ref:`figure_explanation`. + """ from contextlib import ExitStack diff --git a/tutorials/introductory/quick_start.py b/tutorials/introductory/quick_start.py index 2caacc5aee22..818f44847239 100644 --- a/tutorials/introductory/quick_start.py +++ b/tutorials/introductory/quick_start.py @@ -30,7 +30,12 @@ fig, ax = plt.subplots() # Create a figure containing a single axes. ax.plot([1, 2, 3, 4], [1, 4, 2, 3]) # Plot some data on the axes. -############################################################################### +# %% +# +# Note that to get this Figure to display, you may have to call ``plt.show()``, +# depending on your backend. For more details of Figures and backends, see +# :ref:`figure_explanation`. +# # .. _figure_parts: # # Parts of a Figure @@ -53,12 +58,17 @@ # fig = plt.figure() # an empty figure with no Axes # fig, ax = plt.subplots() # a figure with a single Axes # fig, axs = plt.subplots(2, 2) # a figure with a 2x2 grid of Axes +# # a figure with one axes on the left, and two on the right: +# fig, axs = plt.subplot_mosaic([['left', 'right-top'], +# ['left', 'right_bottom]]) # # It is often convenient to create the Axes together with the Figure, but you # can also manually add Axes later on. Note that many # :doc:`Matplotlib backends ` support zooming and # panning on figure windows. # +# For more on Figures, see :ref:`figure_explanation`. +# # :class:`~matplotlib.axes.Axes` # ------------------------------ #