9
9
.. toctree ::
10
10
11
11
12
- When working with data it is often invaluable to be able to interact
13
- with your plots. In many cases the built in pan/zoom and mouse-location
14
- tools are sufficient, but you can also use the Matplotlib event system
15
- to build customized data exploration tools.
12
+ When working with data, interactivity can be invaluable. The pan/zoom and
13
+ mouse-location tools built into the Matplotlib GUI windows are often sufficient, but
14
+ you can also use the event system to build customized data exploration tools.
16
15
17
16
Matplotlib ships with :ref: `backends <what-is-a-backend >` binding to
18
17
several GUI toolkits (Qt, Tk, Wx, GTK, macOS, JavaScript) and third party
19
18
packages provide bindings to `kivy
20
19
<https://github.com/kivy-garden/garden.matplotlib> `__ and `Jupyter Lab
21
- <https://github.com/matplotlib/ipympl> `__. For the figures to be
22
- "live" the GUI event loop will need to be integrated with your prompt. The
23
- simplest way is to use IPython (see :ref: `below <ipython-pylab >`).
20
+ <https://github.com/matplotlib/ipympl> `__. For the figures to be interactive,
21
+ the GUI event loop will need to be integrated with your interactive prompt.
22
+ We recommend using IPython (see :ref: `below <ipython-pylab >`).
24
23
25
- The `.pyplot ` module provides functions for explicitly creating
26
- Figures that include interactive tools, a toolbar, a tool-tip, and
27
- :ref: `key bindings <key-event-handling >` ready to go :
24
+ The `.pyplot ` module provides functions for explicitly creating figures
25
+ that include interactive tools, a toolbar, a tool-tip, and
26
+ :ref: `key bindings <key-event-handling >`:
28
27
29
- `.pyplot.figure `
28
+ * `.pyplot.figure `
30
29
Creates a new empty `.figure.Figure ` or selects an existing figure
31
30
32
- `.pyplot.subplots `
31
+ * `.pyplot.subplots `
33
32
Creates a new `.figure.Figure ` and fills it with a grid of `.axes.Axes `
34
33
35
34
`.pyplot ` has a notion of "The Current Figure" which can be accessed
36
35
through `.pyplot.gcf ` and a notion of "The Current Axes" accessed
37
36
through `.pyplot.gca `. Almost all of the functions in `.pyplot ` pass
38
37
through the current `.Figure ` / `.axes.Axes ` (or create one) as
39
- appropriate. Matplotlib keeps a reference to all of the open figures
38
+ appropriate.
39
+
40
+ Matplotlib keeps a reference to all of the open figures
40
41
created this way so they will not be garbage collected. You can close
41
42
and deregister `.Figure `\s from `.pyplot ` individually via
42
43
`.pyplot.close ` or close all open figures via ``plt.close('all') ``.
43
44
44
- For discussion of how the integration of the event loops and Matplotlib's event
45
- system work under the hood see :
45
+
46
+ For more discussion of Matplotlib's event system and integrated event loops, please read :
46
47
47
48
.. toctree ::
48
49
:maxdepth: 1
@@ -67,54 +68,46 @@ loop is properly integrated with the command line (see
67
68
.. highlight :: ipython
68
69
69
70
::
70
-
71
- user@machine:~ $ ipython
72
- Python 3.8.2 (default, Apr 8 2020, 14:31:25)
73
- Type 'copyright', 'credits' or 'license' for more information
74
- IPython 7.13.0 -- An enhanced Interactive Python. Type '?' for help.
75
-
76
71
In [1]: %matplotlib
77
72
Using matplotlib backend: Qt5Agg
78
73
79
74
In [2]: import matplotlib.pyplot as plt
80
75
81
- Calling
76
+ Create a new figure window:
82
77
83
78
::
84
79
85
80
In [3]: fig, ax = plt.subplots()
86
81
87
- will pop open a window for you and
82
+
83
+ Add a line plot of the data to the window:
88
84
89
85
::
90
86
91
87
In [4]: ln, = ax.plot(range(5))
92
88
93
- will show your data in the window. If you change something about the
94
- line, for example the color
89
+ Change the color of the line from blue to orange:
95
90
96
91
::
97
92
98
93
In [5]: ln.set_color('orange')
99
94
100
- it will be reflected immediately. If you wish to disable this behavior
101
- use
95
+ If you wish to disable interactive modification of the plot:
102
96
103
97
::
104
98
105
99
In [6]: plt.ioff()
106
100
107
- and
101
+ If you wish to re-enable interactive "live" modification of the plot:
108
102
109
103
::
110
104
111
105
In [7]: plt.ion()
112
106
113
- re-enable it.
114
107
115
- With recent versions of ``Matplotlib `` and ``IPython `` it is
116
- sufficient to import `matplotlib.pyplot ` and call `.pyplot.ion `, but
117
- using the magic is guaranteed to work regardless of versions.
108
+ In recent versions of ``Matplotlib `` and ``IPython ``, it is
109
+ sufficient to import `matplotlib.pyplot ` and call `.pyplot.ion `.
110
+ Using the `` % `` magic is guaranteed to work in all versions of `` Matplotlib `` and `` IPython `` .
118
111
119
112
120
113
.. highlight :: python
@@ -146,45 +139,43 @@ Interactive mode controls:
146
139
147
140
- whether created figures are automatically shown
148
141
- whether changes to artists automatically trigger re-drawing existing figures
149
- - whether `.pyplot.show ` returns immediately or after all of the
150
- figures have been closed when given no arguments
151
-
142
+ - when `.pyplot.show ` exits: immediately, or after all of the figures have been closed if given no arguments
152
143
153
- If in interactive mode, then :
144
+ Interactive mode:
154
145
155
- - newly created figures will be shown immediately
156
- - figures will automatically redraw on change
157
- - pyplot.show will return immediately by default
146
+ - newly created figures will be displayed immediately
147
+ - figures will automatically redraw when elements are changed
148
+ - ` pyplot.show ` displays the figures and immediately returns to the prompt
158
149
159
- If not in interactive mode then :
150
+ Not in interactive mode:
160
151
161
- - newly created figures and changes to figures will
162
- not be reflected until explicitly asked to be
163
- - pyplot.show runs the GUI event loop and does not return until all of
164
- the plot windows are closed
152
+ - newly created figures and changes to figures are not displayed until
153
+ ` .pyplot.show ` is called again or ` .pyplot.pause ` exits
154
+ - ` pyplot.show ` runs the GUI event loop and does not return until all
155
+ the plot windows are closed
165
156
166
157
167
158
If you are in non-interactive mode (or created figures while in
168
159
non-interactive mode) you may need to explicitly call `.pyplot.show `
169
- to bring the windows onto your screen. If you only want to run the
170
- GUI event loop for a fixed amount of time you can use `.pyplot.pause `.
171
- This will both block the progress of your code ( as if you had called
172
- `time.sleep `) , ensure the current window is shown and if needed
173
- re-drawn, and run the GUI event loop (so the windows are "live" for
174
- interaction ) for the specified period of time.
175
-
176
- Being in "interactive mode" is orthogonal to the GUI event loop being
177
- integrated with your command prompt. If you use ` pyplot.ion `, but
178
- have not arranged for the event loop integration, your figures will
179
- appear but will not be "live" while the prompt is waiting for input.
160
+ to display the windows on your screen. If you only want to run the
161
+ GUI event loop for a fixed amount of time, you can use `.pyplot.pause `.
162
+ This will block the progress of your code as if you had called
163
+ `time.sleep `, ensure the current window is shown and re-drawn if needed,
164
+ and run the GUI event loop (so the windows are "live" for
165
+ interactive modification ) for the specified period of time.
166
+
167
+ The GUI event loop being integrated with your command prompt and
168
+ the figures being in interactive mode are independent of each other.
169
+ If you use ` pyplot.ion ` but have not arranged for the event loop integration,
170
+ your figures will appear but will not be "live" while the prompt is waiting for input.
180
171
You will not be able to pan/zoom and the figure may not even render
181
172
(the window might appear black, transparent, or as a snapshot of the
182
173
desktop under it). Conversely, if you configure the event loop
183
174
integration, displayed figures will be "live" while waiting for input
184
- at the prompt, regardless of pyplot's "interactive mode". In either
185
- case, the figures will be "live" if you use
186
- ``pyplot.show(block=True) ``, ` .pyplot.pause `, or run the the GUI main
187
- loop in some other way.
175
+ at the prompt, regardless of pyplot's "interactive mode".
176
+
177
+ The figures will also be "live" if you use ``pyplot.show(block=True) ``,
178
+ ` .pyplot.pause `, or run the the GUI main loop in some other way.
188
179
189
180
190
181
.. warning ::
@@ -201,7 +192,7 @@ Default UI
201
192
202
193
203
194
The windows created by :mod: `~.pyplot ` have an interactive toolbar with navigation
204
- buttons and a readout of where the cursor is in dataspace . A number of
195
+ buttons and a readout of the data values the cursor is pointing at . A number of
205
196
helpful keybindings are registered by default.
206
197
207
198
@@ -240,8 +231,7 @@ Preserve aspect ratio hold **CONTROL** when panning/zooming with mo
240
231
Other Python prompts
241
232
====================
242
233
243
- If you can not or do not want to use IPython, interactive mode works
244
- in the vanilla python prompt
234
+ Interactive mode works in the default Python prompt:
245
235
246
236
247
237
.. sourcecode :: pycon
@@ -265,11 +255,11 @@ Jupyter Notebooks / Lab
265
255
using an interactive backend. The default backend in notebooks,
266
256
the inline backend, is not. `~ipykernel.pylab.backend_inline `
267
257
renders the figure once and inserts a static image into the
268
- notebook when the cell is executed. The images are static and can
269
- not be panned / zoomed, take user input, or be updated from other
258
+ notebook when the cell is executed. Because the images are static, they
259
+ can not be panned / zoomed, take user input, or be updated from other
270
260
cells.
271
261
272
- To get interactive figures in the 'classic' notebook or jupyter lab
262
+ To get interactive figures in the 'classic' notebook or Jupyter lab,
273
263
use the `ipympl <https://github.com/matplotlib/ipympl >`__ backend
274
264
(must be installed separately) which uses the **ipywidget ** framework.
275
265
If ``ipympl `` is installed use the magic:
@@ -280,25 +270,24 @@ If ``ipympl`` is installed use the magic:
280
270
281
271
to select and enable it.
282
272
283
- If you only need to use the classic notebook you can use
273
+ If you only need to use the classic notebook, you can use
284
274
285
275
.. sourcecode :: ipython
286
276
287
277
%matplotlib notebook
288
278
289
- which uses the `.backend_nbagg ` backend which ships with Matplotlib.
290
- However nbagg does not work in Jupyter Lab.
279
+ which uses the `.backend_nbagg ` backend which is installed by Matplotlib;
280
+ however, nbagg does not work in Jupyter Lab.
291
281
292
- GUIs + jupyter
282
+ GUIs + Jupyter
293
283
~~~~~~~~~~~~~~
294
284
295
- If you are running your jupyter kernel locally you can use one of the
296
- GUI backends. The process running your kernel will show a GUI window
297
- on your desktop adjacent to your web browser. However if you move
298
- that notebook to a remote server the kernel will try to open the GUI
299
- window on *that * computer. Unless you have arranged to forward the
300
- xserver back to your desktop, you not be able to see or interact with
301
- the figure (if it does not raise an exception outright).
285
+ You can also use one of the non-ipympl GUI backends in a Jupyter Notebook.
286
+ If you are running your Jupyter kernel locally, the GUI window will spawn on
287
+ your desktop adjacent to your web browser. If you run your notebook on a remote server,
288
+ the kernel will try to open the GUI window on the remote computer. Unless you have
289
+ arranged to forward the xserver back to your desktop, you will not be able to
290
+ see or interact with the window. It may also raise an exception.
302
291
303
292
304
293
0 commit comments