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

Skip to content

Commit c78dc69

Browse files
jklymakjklymak
committed
DOC: organize figure API
1 parent e48bcaa commit c78dc69

File tree

3 files changed

+194
-6
lines changed

3 files changed

+194
-6
lines changed

‎doc/api/figure_api.rst

Lines changed: 187 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,190 @@
44

55
.. currentmodule:: matplotlib.figure
66

7-
.. automodule:: matplotlib.figure
8-
:members:
9-
:inherited-members:
7+
8+
The Figure and SubFigure classes
9+
================================
10+
11+
Every visualization starts with a `~.Figure` class, often instantiated via `pyplot.figure`, `.pyplot.subplots`, or `.pyplot.subplot_mosaic`.
12+
13+
Matplotlib has the concept of a `~.SubFigure`, which is a logical figure inside a parent `~.Figure`. Most common methods are defined in `~.FigureBase`, but there are a few methods that only make sense on the parent `~.Figure`.
14+
15+
.. seealso::
16+
17+
- :ref:`figures_and_backends`
18+
- :ref:`arranging_axes`
19+
20+
.. plot::
21+
22+
fig = plt.figure(layout='constrained', figsize=(4, 2.5), facecolor='lightgoldenrodyellow')
23+
24+
# Make two subfigures, left ones more narrow than right ones:
25+
sfigs = fig.subfigures(1, 2, width_ratios=[0.8, 1])
26+
sfigs[0].set_facecolor('khaki')
27+
sfigs[1].set_facecolor('lightsalmon')
28+
29+
# Add subplots to left subfigure:
30+
lax = sfigs[0].subplots(2, 1)
31+
sfigs[0].suptitle('Left subfigure')
32+
33+
# Add subplots to right subfigure:
34+
rax = sfigs[1].subplots(1, 2)
35+
sfigs[1].suptitle('Right subfigure')
36+
37+
# suptitle for the main figure:
38+
fig.suptitle('Figure')
39+
40+
41+
.. autosummary::
42+
:toctree: _as_gen
43+
:template: autosummary_class_only.rst
44+
:nosignatures:
45+
46+
Figure
47+
SubFigure
48+
FigureBase
49+
SubplotParams
50+
51+
Adding Axes and SubFigures
52+
==========================
53+
54+
.. autosummary::
55+
:toctree: _as_gen
56+
:template: autosummary.rst
57+
:nosignatures:
58+
59+
FigureBase.add_axes
60+
FigureBase.add_subplot
61+
FigureBase.subplots
62+
FigureBase.subplot_mosaic
63+
FigureBase.add_subfigure
64+
FigureBase.subfigures
65+
FigureBase.add_gridspec
66+
SubFigure.axes
67+
Figure.axes
68+
69+
Saving a Figure
70+
===============
71+
72+
.. autosummary::
73+
:toctree: _as_gen
74+
:template: autosummary.rst
75+
:nosignatures:
76+
77+
Figure.savefig
78+
79+
80+
Annotate (Sub)Figure
81+
====================
82+
83+
.. autosummary::
84+
:toctree: _as_gen
85+
:template: autosummary.rst
86+
:nosignatures:
87+
88+
FigureBase.colorbar
89+
FigureBase.legend
90+
FigureBase.suptitle
91+
FigureBase.get_suptitle
92+
FigureBase.supxlabel
93+
FigureBase.get_supxlabel
94+
FigureBase.supylabel
95+
FigureBase.get_supylabel
96+
FigureBase.align_labels
97+
FigureBase.align_xlabels
98+
FigureBase.align_ylabels
99+
100+
Figure geometry and subplot layout
101+
==================================
102+
103+
.. autosummary::
104+
:toctree: _as_gen
105+
:template: autosummary.rst
106+
:nosignatures:
107+
108+
Figure.set_size_inches
109+
Figure.get_size_inches
110+
Figure.set_figheight
111+
Figure.get_figheight
112+
Figure.set_figwidth
113+
Figure.get_figwidth
114+
Figure.set_dpi
115+
Figure.set_dpi
116+
Figure.set_layout_engine
117+
Figure.get_layout_engine
118+
119+
Interact with a Figure
120+
======================
121+
122+
.. seealso::
123+
124+
- :ref:`event-handling`
125+
126+
.. autosummary::
127+
:toctree: _as_gen
128+
:template: autosummary.rst
129+
:nosignatures:
130+
131+
Figure.ginput
132+
Figure.add_axobserver
133+
Figure.waitforbuttonpress
134+
Figure.pick
135+
136+
Modify (Sub)Figure appearance
137+
=============================
138+
139+
.. autosummary::
140+
:toctree: _as_gen
141+
:template: autosummary.rst
142+
:nosignatures:
143+
144+
FigureBase.set_frameon
145+
FigureBase.get_frameon
146+
FigureBase.set_linewidth
147+
FigureBase.get_linewidth
148+
FigureBase.set_facecolor
149+
FigureBase.get_facecolor
150+
FigureBase.set_edgecolor
151+
FigureBase.get_edgecolor
152+
153+
Add and interrogate Artists on a (Sub)Figure
154+
============================================
155+
156+
FigureBase.add_artist
157+
FigureBase.get_children
158+
Figure.figimage
159+
160+
161+
Get and modify (Sub)Figure state
162+
================================
163+
164+
.. seealso::
165+
166+
- :ref:`interactive_figures`
167+
168+
169+
.. autosummary::
170+
:toctree: _as_gen
171+
:template: autosummary.rst
172+
:nosignatures:
173+
174+
Figure.clear
175+
FigureBase.gca
176+
FigureBase.sca
177+
FigureBase.get_tightbbox
178+
FigureBase.get_window_extent
179+
Figure.show
180+
Figure.set_canvas
181+
Figure.draw
182+
Figure.draw_without_rendering
183+
Figure.draw_artist
184+
185+
Other
186+
=====
187+
188+
.. autosummary::
189+
:toctree: _as_gen
190+
:template: autosummary.rst
191+
:nosignatures:
192+
193+
FigureBase.autofmt_xdate

‎galleries/users_explain/figure/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _figures_and_backends:
2+
13
++++++++++++++++++++
24
Figures and backends
35
++++++++++++++++++++

‎lib/matplotlib/figure.py

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1501,8 +1501,7 @@ def align_labels(self, axs=None):
15011501

15021502
def add_gridspec(self, nrows=1, ncols=1, **kwargs):
15031503
"""
1504-
Return a `.GridSpec` that has this figure as a parent. This allows
1505-
complex layout of Axes in the figure.
1504+
Create a low-level `.GridSpec` that has this figure as a parent.
15061505
15071506
Parameters
15081507
----------
@@ -1726,6 +1725,9 @@ def _process_projection_requirements(self, *, axes_class=None, polar=False,
17261725
return projection_class, kwargs
17271726

17281727
def get_default_bbox_extra_artists(self):
1728+
"""
1729+
Return a list of Artists typically used in `.FigureBase.get_tightbbox`.
1730+
"""
17291731
bbox_artists = [artist for artist in self.get_children()
17301732
if (artist.get_visible() and artist.get_in_layout())]
17311733
for ax in self.axes:
@@ -3246,7 +3248,7 @@ def add_axobserver(self, func):
32463248

32473249
def savefig(self, fname, *, transparent=None, **kwargs):
32483250
"""
3249-
Save the current figure.
3251+
Save the current figure as an image or vector graphic to a file.
32503252
32513253
Call signature::
32523254

0 commit comments

Comments
 (0)