10000 cleaned up idioms, restructured the code example, stripped down sme l… · matplotlib/matplotlib@bd5d63a · GitHub
[go: up one dir, main page]

Skip to content

Commit bd5d63a

Browse files
committed
cleaned up idioms, restructured the code example, stripped down sme langauge
1 parent 1f39173 commit bd5d63a

File tree

1 file changed

+65
-76
lines changed

1 file changed

+65
-76
lines changed

doc/users/interactive.rst

Lines changed: 65 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -9,40 +9,41 @@
99
.. toctree::
1010

1111

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.
1615

1716
Matplotlib ships with :ref:`backends <what-is-a-backend>` binding to
1817
several GUI toolkits (Qt, Tk, Wx, GTK, macOS, JavaScript) and third party
1918
packages provide bindings to `kivy
2019
<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>`).
2423

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>`:
2827

29-
`.pyplot.figure`
28+
* `.pyplot.figure`
3029
Creates a new empty `.figure.Figure` or selects an existing figure
3130

32-
`.pyplot.subplots`
31+
* `.pyplot.subplots`
3332
Creates a new `.figure.Figure` and fills it with a grid of `.axes.Axes`
3433

3534
`.pyplot` has a notion of "The Current Figure" which can be accessed
3635
through `.pyplot.gcf` and a notion of "The Current Axes" accessed
3736
through `.pyplot.gca`. Almost all of the functions in `.pyplot` pass
3837
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
4041
created this way so they will not be garbage collected. You can close
4142
and deregister `.Figure`\s from `.pyplot` individually via
4243
`.pyplot.close` or close all open figures via ``plt.close('all')``.
4344

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:
4647

4748
.. toctree::
4849
:maxdepth: 1
@@ -67,54 +68,46 @@ loop is properly integrated with the command line (see
6768
.. highlight:: ipython
6869

6970
::
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-
7671
In [1]: %matplotlib
7772
Using matplotlib backend: Qt5Agg
7873

7974
In [2]: import matplotlib.pyplot as plt
8075

81-
Calling
76+
Create a new figure window:
8277

8378
::
8479

8580
In [3]: fig, ax = plt.subplots()
8681

87-
will pop open a window for you and
82+
83+
Add a line plot of the data to the window:
8884

8985
::
9086

9187
In [4]: ln, = ax.plot(range(5))
9288

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:
9590

9691
::
9792

9893
In [5]: ln.set_color('orange')
9994

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:
10296

10397
::
10498

10599
In [6]: plt.ioff()
106100

107-
and
101+
If you wish to re-enable interactive "live" modification of the plot:
108102

109103
::
110104

111105
In [7]: plt.ion()
112106

113-
re-enable it.
114107

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``.
118111

119112

120113
.. highlight:: python
@@ -146,45 +139,43 @@ Interactive mode controls:
146139

147140
- whether created figures are automatically shown
148141
- 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
152143

153-
If in interactive mode, then:
144+
Interactive mode:
154145

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
158149

159-
If not in interactive mode then:
150+
Not in interactive mode:
160151

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
165156

166157

167158
If you are in non-interactive mode (or created figures while in
168159
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.
180171
You will not be able to pan/zoom and the figure may not even render
181172
(the window might appear black, transparent, or as a snapshot of the
182173
desktop under it). Conversely, if you configure the event loop
183174
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.
188179

189180

190181
.. warning::
@@ -201,7 +192,7 @@ Default UI
201192

202193

203194
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
205196
helpful keybindings are registered by default.
206197

207198

@@ -240,8 +231,7 @@ Preserve aspect ratio hold **CONTROL** when panning/zooming with mo
240231
Other Python prompts
241232
====================
242233

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:
245235

246236

247237
.. sourcecode:: pycon
@@ -265,11 +255,11 @@ Jupyter Notebooks / Lab
265255
using an interactive backend. The default backend in notebooks,
266256
the inline backend, is not. `~ipykernel.pylab.backend_inline`
267257
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
270260
cells.
271261

272-
To get interactive figures in the 'classic' notebook or jupyter lab
262+
To get interactive figures in the 'classic' notebook or Jupyter lab,
273263
use the `ipympl <https://github.com/matplotlib/ipympl>`__ backend
274264
(must be installed separately) which uses the **ipywidget** framework.
275265
If ``ipympl`` is installed use the magic:
@@ -280,25 +270,24 @@ If ``ipympl`` is installed use the magic:
280270

281271
to select and enable it.
282272

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
284274

285275
.. sourcecode:: ipython
D221
286276

287277
%matplotlib notebook
288278

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.
291281

292-
GUIs + jupyter
282+
GUIs + Jupyter
293283
~~~~~~~~~~~~~~
294284

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.
302291

303292

304293

0 commit comments

Comments
 (0)
0