Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Backport PR #26629 on branch v3.8.x (DOC: organize figure API) #26783

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Backport PR #26629 on branch v3.8.x (DOC: organize figure API) #26783

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
303 changes: 301 additions & 2 deletions doc/api/figure_api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are 2 new lines here, before the next section. This spacing is inconsistent in other parts of the code. Some sections have 1 new line before them and some have 2. It would be good if there can be some uniformity.


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
2 changes: 1 addition & 1 deletion doc/api/prev_api_changes/api_changes_3.4.2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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*
Expand Down
2 changes: 1 addition & 1 deletion doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions doc/users/prev_whats_new/whats_new_3.4.0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand Down
10 changes: 5 additions & 5 deletions galleries/examples/subplots_axes_and_figures/figure_title.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion galleries/examples/subplots_axes_and_figures/gridspec_nested.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

"""
Expand Down
2 changes: 2 additions & 0 deletions galleries/users_explain/axes/arranging_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,6 +228,8 @@ def annotate_axes(ax, text, fontsize=18):
fig.suptitle('plt.subplot_mosaic()')

# %%
# .. _nested_axes_layouts:
#
# Nested Axes layouts
# -------------------
#
Expand Down
Loading