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

Skip to content

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

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