Skip to content

Commit 7b579a6

Browse files
jklymakjklymak
committed
DOC: organize figure API
1 parent 14a0c5b commit 7b579a6

File tree

11 files changed

+348
-31
lines changed

11 files changed

+348
-31
lines changed

‎doc/api/figure_api.rst

Lines changed: 308 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,311 @@
55
.. currentmodule:: matplotlib.figure
66

77
.. automodule:: matplotlib.figure
8-
:members:
9-
:inherited-members:
8+
:no-members:
9+
:no-undoc-members:
10+
11+
The Figure class
12+
================
13+
.. autosummary::
14+
:toctree: _as_gen
15+
:template: autosummary_class_only.rst
16+
:nosignatures:
17+
18+
Figure
19+
20+
21+
Adding Axes and SubFigures
22+
==========================
23+
24+
.. autosummary::
25+
:toctree: _as_gen
26+
:template: autosummary.rst
27+
:nosignatures:
28+
29+
Figure.add_axes
30+
Figure.add_subplot
31+
Figure.subplots
32+
Figure.subplot_mosaic
33+
Figure.add_gridspec
34+
Figure.get_axes
35+
Figure.axes
36+
Figure.delaxes
37+
Figure.subfigures
38+
Figure.add_subfigure
39+
40+
Saving
41+
======
42+
43+
.. autosummary::
44+
:toctree: _as_gen
45+
:template: autosummary.rst
46+
:nosignatures:
47+
48+
Figure.savefig
49+
50+
51+
Annotating
52+
==========
53+
54+
.. autosummary::
55+
:toctree: _as_gen
56+
:template: autosummary.rst
57+
:nosignatures:
58+
59+
Figure.colorbar
60+
Figure.legend
61+
Figure.text
62+
Figure.suptitle
63+
Figure.get_suptitle
64+
Figure.supxlabel
65+
Figure.get_supxlabel
66+
Figure.supylabel
67+
Figure.get_supylabel
68+
Figure.align_labels
69+
Figure.align_xlabels
70+
Figure.align_ylabels
71+
Figure.autofmt_xdate
72+
73+
74+
Figure geometry
75+
===============
76+
77+
.. autosummary::
78+
:toctree: _as_gen
79+
:template: autosummary.rst
80+
:nosignatures:
81+
82+
Figure.set_size_inches
83+
Figure.get_size_inches
84+
Figure.set_figheight
85+
Figure.get_figheight
86+
Figure.set_figwidth
87+
Figure.get_figwidth
88+
Figure.dpi
89+
Figure.set_dpi
90+
Figure.set_dpi
91+
92+
Subplot layout
93+
==============
94+
95+
.. autosummary::
96+
:toctree: _as_gen
97+
:template: autosummary.rst
98+
:nosignatures:
99+
100+
Figure.subplots_adjust
101+
Figure.set_layout_engine
102+
Figure.get_layout_engine
103+
104+
Discouraged or deprecated
105+
-------------------------
106+
107+
.. autosummary::
108+
:toctree: _as_gen
109+
:template: autosummary.rst
110+
:nosignatures:
111+
112+
Figure.tight_layout
113+
Figure.set_tight_layout
114+
Figure.get_tight_layout
115+
Figure.set_constrained_layout
116+
Figure.get_constrained_layout
117+
Figure.set_constrained_layout_pads
118+
Figure.get_constrained_layout_pads
119+
120+
121+
Interacting
122+
===========
123+
124+
.. seealso::
125+
126+
- :ref:`event-handling`
127+
128+
.. autosummary::
129+
:toctree: _as_gen
130+
:template: autosummary.rst
131+
:nosignatures:
132+
133+
Figure.ginput
134+
Figure.add_axobserver
135+
Figure.waitforbuttonpress
136+
Figure.pick
137+
138+
Modifying appearance
139+
====================
140+
141+
.. autosummary::
142+
:toctree: _as_gen
143+
:template: autosummary.rst
144+
:nosignatures:
145+
146+
Figure.set_frameon
147+
Figure.get_frameon
148+
Figure.set_linewidth
149+
Figure.get_linewidth
150+
Figure.set_facecolor
151+
Figure.get_facecolor
152+
Figure.set_edgecolor
153+
Figure.get_edgecolor
154+
155+
Adding and getting Artists
156+
==========================
157+
158+
.. autosummary::
159+
:toctree: _as_gen
160+
:template: autosummary.rst
161+
:nosignatures:
162+
163+
Figure.add_artist
164+
Figure.get_children
165+
Figure.figimage
166+
167+
Getting and modifying state
168+
===========================
169+
170+
.. seealso::
171+
172+
- :ref:`interactive_figures`
173+
174+
.. autosummary::
175+
:toctree: _as_gen
176+
:template: autosummary.rst
177+
:nosignatures:
178+
179+
Figure.clear
180+
Figure.gca
181+
Figure.sca
182+
Figure.get_tightbbox
183+
Figure.get_window_extent
184+
Figure.show
185+
Figure.set_canvas
186+
Figure.draw
187+
Figure.draw_without_rendering
188+
Figure.draw_artist
189+
190+
SubFigure
191+
=========
192+
193+
Matplotlib has the concept of a `~.SubFigure`, which is a logical figure inside
194+
a parent `~.Figure`. It has many of the same methods as the parent. See
195+
:ref:`nested_axes_layouts`.
196+
197+
.. plot::
198+
199+
fig = plt.figure(layout='constrained', figsize=(4, 2.5), facecolor='lightgoldenrodyellow')
200+
201+
# Make two subfigures, left ones more narrow than right ones:
202+
sfigs = fig.subfigures(1, 2, width_ratios=[0.8, 1])
203+
sfigs[0].set_facecolor('khaki')
204+
sfigs[1].set_facecolor('lightsalmon')
205+
206+
# Add subplots to left subfigure:
207+
lax = sfigs[0].subplots(2, 1)
208+
sfigs[0].suptitle('Left subfigure')
209+
210+
# Add subplots to right subfigure:
211+
rax = sfigs[1].subplots(1, 2)
212+
sfigs[1].suptitle('Right subfigure')
213+
214+
# suptitle for the main figure:
215+
fig.suptitle('Figure')
216+
217+
SubFigure class
218+
---------------
219+
220+
.. autosummary::
221+
:toctree: _as_gen
222+
:template: autosummary_class_only.rst
223+
:nosignatures:
224+
225+
SubFigure
226+
227+
Adding Axes and SubFigures
228+
--------------------------
229+
.. autosummary::
230+
:toctree: _as_gen
231+
:template: autosummary.rst
232+
:nosignatures:
233+
234+
SubFigure.add_axes
235+
SubFigure.add_subplot
236+
SubFigure.subplots
237+
SubFigure.subplot_mosaic
238+
SubFigure.add_gridspec
239+
SubFigure.delaxes
240+
SubFigure.add_subfigure
241+
SubFigure.subfigures
242+
243+
Annotating
244+
----------
245+
246+
.. autosummary::
247+
:toctree: _as_gen
248+
:template: autosummary.rst
249+
:nosignatures:
250+
251+
SubFigure.colorbar
252+
SubFigure.legend
253+
SubFigure.text
254+
SubFigure.suptitle
255+
SubFigure.get_suptitle
256+
SubFigure.supxlabel
257+
SubFigure.get_supxlabel
258+
SubFigure.supylabel
259+
SubFigure.get_supylabel
260+
SubFigure.align_labels
261+
SubFigure.align_xlabels
262+
SubFigure.align_ylabels
263+
264+
Adding and getting Artists
265+
--------------------------
266+
267+
.. autosummary::
268+
:toctree: _as_gen
269+
:template: autosummary.rst
270+
:nosignatures:
271+
272+
SubFigure.add_artist
273+
SubFigure.get_children
274+
275+
Modifying appearance
276+
--------------------
277+
278+
.. autosummary::
279+
:toctree: _as_gen
280+
:template: autosummary.rst
281+
:nosignatures:
282+
283+
SubFigure.set_frameon
284+
SubFigure.get_frameon
285+
SubFigure.set_linewidth
286+
SubFigure.get_linewidth
287+
SubFigure.set_facecolor
288+
SubFigure.get_facecolor
289+
SubFigure.set_edgecolor
290+
SubFigure.get_edgecolor
291+
292+
Passthroughs
293+
------------
294+
295+
.. autosummary::
296+
:toctree: _as_gen
297+
:template: autosummary.rst
298+
:nosignatures:
299+
300+
SubFigure.set_dpi
301+
SubFigure.get_dpi
302+
303+
304+
Helper classes
305+
==============
306+
307+
FigureBase
308+
----------
309+
310+
.. autoclass:: FigureBase
311+
312+
SubplotParams
313+
-------------
314+
315+
.. autoclass:: SubplotParams

‎doc/api/prev_api_changes/api_changes_3.4.2.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Behaviour changes
77
Rename first argument to ``subplot_mosaic``
88
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99

10-
Both `.FigureBase.subplot_mosaic`, and `.pyplot.subplot_mosaic` have had the
10+
Both `.Figure.subplot_mosaic`, and `.pyplot.subplot_mosaic` have had the
1111
first position argument renamed from *layout* to *mosaic*. This is because we
1212
are considering to consolidate *constrained_layout* and *tight_layout* keyword
1313
arguments in the Figure creation functions of `.pyplot` into a single *layout*

‎doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Behaviour changes
44
First argument to ``subplot_mosaic`` renamed
55
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66

7-
Both `.FigureBase.subplot_mosaic`, and `.pyplot.subplot_mosaic` have had the
7+
Both `.Figure.subplot_mosaic`, and `.pyplot.subplot_mosaic` have had the
88
first positional argument renamed from *layout* to *mosaic*. As we have
99
consolidated the *constrained_layout* and *tight_layout* keyword arguments in
1010
the Figure creation functions of `.pyplot` into a single *layout* keyword

‎doc/users/prev_whats_new/whats_new_3.4.0.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -634,8 +634,8 @@ supxlabel and supylabel
634634
-----------------------
635635

636636
It is possible to add x- and y-labels to a whole figure, analogous to
637-
`.FigureBase.suptitle` using the new `.FigureBase.supxlabel` and
638-
`.FigureBase.supylabel` methods.
637+
`.Figure.suptitle` using the new `.Figure.supxlabel` and
638+
`.Figure.supylabel` methods.
639639

640640
.. plot::
641641

‎galleries/examples/subplots_axes_and_figures/figure_title.py

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,10 @@
55
66
Each axes can have a title (or actually three - one each with *loc* "left",
77
"center", and "right"), but is sometimes desirable to give a whole figure
8-
(or `.SubFigure`) an overall title, using `.FigureBase.suptitle`.
8+
(or `.SubFigure`) an overall title, using `.Figure.suptitle`.
99
10-
We can also add figure-level x- and y-labels using `.FigureBase.supxlabel` and
11-
`.FigureBase.supylabel`.
10+
We can also add figure-level x- and y-labels using `.Figure.supxlabel` and
11+
`.Figure.supylabel`.
1212
"""
1313

1414
import matplotlib.pyplot as plt
@@ -31,8 +31,8 @@
3131
fig.suptitle('Different types of oscillations', fontsize=16)
3232

3333
# %%
34-
# A global x- or y-label can be set using the `.FigureBase.supxlabel` and
35-
# `.FigureBase.supylabel` methods.
34+
# A global x- or y-label can be set using the `.Figure.supxlabel` and
35+
# `.Figure.supylabel` methods.
3636

3737

3838
with get_sample_data('Stocks.csv') as file:

‎galleries/examples/subplots_axes_and_figures/gridspec_nested.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
set the position for a nested grid of subplots.
88
99
Note that the same functionality can be achieved more directly with
10-
`~.FigureBase.subfigures`; see
10+
`~.Figure.subfigures`; see
1111
:doc:`/gallery/subplots_axes_and_figures/subfigures`.
1212
1313
"""

‎galleries/users_explain/axes/arranging_axes.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,8 @@ def annotate_axes(ax, text, fontsize=18):
228228
fig.suptitle('plt.subplot_mosaic()')
229229

230230
# %%
231+
# .. _nested_axes_layouts:
232+
#
231233
# Nested Axes layouts
232234
# -------------------
233235
#

0 commit comments

Comments
 (0)