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

Skip to content

Commit b9d2246

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

File tree

3 files changed

+192
-6
lines changed

3 files changed

+192
-6
lines changed

‎doc/api/figure_api.rst

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