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

Skip to content

Commit 8ab0a65

Browse files
tacaswelltacaswell
committed
DOC: edits from review
1 parent 5a426d6 commit 8ab0a65

2 files changed

Lines changed: 79 additions & 64 deletions

File tree

‎doc/users/interactive.rst‎

Lines changed: 18 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,10 @@
99
.. toctree::
1010

1111

12-
When working with data it is often invaluable to be able to
13-
interact with your plots In many cases the built in pan/zoom
14-
and mouse-location tools are sufficient, but if they are not
15-
you can make use of the Matplotlib event system to build a customized
16-
data exploration tool.
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 a customized data exploration tools.
1716

1817
Matplotlib ships with :ref:`backends <what-is-a-backend>` binding to
1918
several GUI toolkits (Qt, Tk, Wx, Gtk, OSX, js) and third party
@@ -59,7 +58,9 @@ loop is properly integrated with the command line (see
5958
:ref:`interactive mode <controlling-interactive>` use the
6059
``%matplotlib`` magic
6160

62-
.. sourcecode:: ipython
61+
.. highlight:: ipython
62+
63+
::
6364

6465
user@machine:~ $ ipython
6566
Python 3.8.2 (default, Apr 8 2020, 14:31:25)
@@ -75,33 +76,33 @@ loop is properly integrated with the command line (see
7576

7677
Calling
7778

78-
.. sourcecode:: ipython
79+
::
7980

8081
In [3]: fig, ax = plt.subplots()
8182

8283
will pop open a window for you and
8384

84-
.. sourcecode:: ipython
85+
::
8586

8687
In [4]: ln, = ax.plot(range(5))
8788

88-
will show your data in the window. If you
89-
want to change anything about the line, ex the color
89+
will show your data in the window. If you change something about the
90+
line, for example the color
9091

91-
.. sourcecode:: ipython
92+
::
9293

9394
In [5]: ln.set_color('orange')
9495

95-
will be reflected immediately. If you wish to disable this behavior
96-
you can use
96+
it will be reflected immediately. If you wish to disable this behavior
97+
use
9798

98-
.. sourcecode:: ipython
99+
::
99100

100101
In [6]: plt.ioff()
101102

102103
and
103104

104-
.. sourcecode:: ipython
105+
::
105106

106107
In [7]: plt.ion()
107108

@@ -112,7 +113,7 @@ sufficient to import `matplotlib.pyplot` and call `.pyplot.ion`, but
112113
using the magic is guaranteed to work regardless of versions.
113114

114115

115-
116+
.. highlight:: python
116117

117118
.. _controlling-interactive:
118119

@@ -228,7 +229,7 @@ If you can not or do not want to use IPython, interactive mode works
228229
in the vanilla python prompt
229230

230231

231-
.. sourcecode:: python
232+
.. sourcecode:: pycon
232233

233234
>>> import matplotlib.pyplot as plt
234235
>>> plt.ion()
@@ -253,14 +254,6 @@ Jupyter Notebooks / Lab
253254
not be panned / zoomed, take user input, or be updated from other
254255
cells.
255256

256-
Jupyter uses a different architecture than a traditional interactive
257-
terminal. Rather than the user interface running in the same process
258-
as your interpreter, the user interacts with a javascript front end
259-
running in a browser which communicates with a server which in turn
260-
communicates with a kernel that executes your Python. This means
261-
for interactive figures our UI needs to also be written in javascript
262-
and run inside of the jupyter front end.
263-
264257
To get interactive figures in the 'classic' notebook or jupyter lab
265258
use the `ipympl <https://github.com/matplotlib/ipympl>`__ backend
266259
(must be installed separately) which uses the **ipywidget** framework.

‎doc/users/interactive_guide.rst‎

Lines changed: 61 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@
88
==================================================
99

1010
Matplotlib supports rich interactive figures by embedding figures into
11-
a GUI window. The basic interactions of panning and zooming in as
12-
Axis to inspect your data is 'baked in' to Matplotlib. This is
11+
a GUI window. The basic interactions of panning and zooming in an
12+
Axes to inspect your data is 'baked in' to Matplotlib. This is
1313
supported by a full mouse and keyboard event handling system that
1414
you can use to build sophisticated interactive graphs.
1515

@@ -50,7 +50,7 @@ than directly implement the I/O loop [#f2]_. For example "when the
5050
user clicks on this button, please run this function" or "when the
5151
user hits the 'z' key, please run this other function". This allows
5252
users to write reactive, event-driven, programs without having to
53-
delve into the nity-gritty [#f3]_ details of I/O. The core event loop
53+
delve into the nitty-gritty [#f3]_ details of I/O. The core event loop
5454
is sometimes referred to as "the main loop" and is typically started,
5555
depending on the library, by methods with names like ``_exec``,
5656
``run``, or ``start``.
@@ -75,13 +75,13 @@ interfaces.
7575
Command Prompt Integration
7676
==========================
7777

78-
So far, so good. We have the REPL (like the IPthon terminal) that
78+
So far, so good. We have the REPL (like the IPython terminal) that
7979
lets us interactively send things code to the interpreter and get
8080
results back. We also have the GUI toolkit that run an event loop
8181
waiting for user input and let up register functions to be run when
8282
that happens. However, if we want to do both we have a problem: the
8383
prompt and the GUI event loop are both infinite loops that each think
84-
*they* are in charge! In order for both the prompt and the GUI widows
84+
*they* are in charge! In order for both the prompt and the GUI windows
8585
to be responsive we need a method to allow the loops to 'timeshare' :
8686

8787
1. let the GUI main loop block the python process when you want
@@ -110,17 +110,21 @@ Blocking the Prompt
110110
The simplest "integration" is to start the GUI event loop in
111111
'blocking' mode and take over the CLI. While the GUI event loop is
112112
running you can not enter new commands into the prompt (your terminal
113-
may echo the charters typed into standard in, but they will not be
113+
may echo the characters typed into the terminal, but they will not be
114114
sent to the Python interpreter because it is busy running the GUI
115115
event loop), but the figure windows will be responsive. Once the
116116
event loop is stopped (leaving any still open figure windows
117117
non-responsive) you will be able to use the prompt again. Re-starting
118118
the event loop will make any open figure responsive again (and will
119-
process and queued up user interaction).
119+
process any queued up user interaction).
120120

121121
To start the event loop until all open figures are closed use
122-
`.pyplot.show` as ``pyplot.show(block=True)``. To start the event
123-
loop for a fixed amount of time (in seconds) use `.pyplot.pause`.
122+
`.pyplot.show` as ::
123+
124+
pyplot.show(block=True)
125+
126+
To start the event loop for a fixed amount of time (in seconds) use
127+
`.pyplot.pause`.
124128

125129
If you are not using `.pyplot` you can start and stop the event loops
126130
via `.FigureCanvasBase.start_event_loop` and
@@ -130,25 +134,9 @@ large GUI application and the GUI event loop should already be running
130134
for the application.
131135

132136
Away from the prompt, this technique can be very useful if you want to
133-
write a script that pauses for user interaction, see
134-
:ref:`interactive_scripts`.
135-
136-
.. _spin_event_loop:
137-
138-
Explicitly spinning the Event Loop
139-
----------------------------------
140-
141-
.. autosummary::
142-
:template: autosummary.rst
143-
:nosignatures:
144-
145-
backend_bases.FigureCanvasBase.flush_events
146-
backend_bases.FigureCanvasBase.draw_idle
147-
148-
149-
150-
This is particularly useful if you want to provide updates to a plot
151-
during a long computation.
137+
write a script that pauses for user interaction, or displays a figure
138+
between polling for additional data. See :ref:`interactive_scripts`
139+
for more details.
152140

153141

154142
Input Hook integration
@@ -197,8 +185,8 @@ more details.
197185

198186
.. _interactive_scripts :
199187

200-
Scripts
201-
=======
188+
Scripts and functions
189+
=====================
202190

203191

204192
.. autosummary::
@@ -211,21 +199,58 @@ Scripts
211199
figure.Figure.ginput
212200
pyplot.ginput
213201

202+
pyplot.show
203+
pyplot.pause
204+
214205
There are several use-cases for using interactive figures in scripts:
215206

216-
- progress updates as a long running script progresses
217207
- capture user input to steer the script
208+
- progress updates as a long running script progresses
218209
- streaming updates from a data source
219210

211+
Blocking functions
212+
------------------
220213

221-
In the first if you only need to collect points in an Axes you can use
214+
If you only need to collect points in an Axes you can use
222215
`.figure.Figure.ginput` or more generally the tools from
223216
`.blocking_input` the tools will take care of starting and stopping
224217
the event loop for you. However if you have written some custom event
225218
handling or are using `.widgets` you will need to manually run the GUI
226219
event loop using the methods described :ref:`above <cp_block_the_prompt>`.
227220

228-
In the second caes, if you have open windows that have pending UI
221+
You can also use the methods described in :ref:`cp_block_the_prompt`
222+
to suspend run the GUI event loop. Once the loop exits your code will
223+
resume. In general, anyplace you would use `time.sleep` you can use
224+
`.pyplot.pause` instead with the added benefit of interactive figures.
225+
226+
For example, if you want to poll for data you could use something like ::
227+
228+
fig, ax = plt.subplots()
229+
ln, = ax.plot([], [])
230+
231+
while True:
232+
x, y = get_new_data()
233+
ln.set_data(x, y)
234+
fig.canvas.draw_idle()
235+
plt.pause(1)
236+
237+
which would poll for new data and update the figure at 1Hz.
238+
239+
.. _spin_event_loop:
240+
241+
Explicitly spinning the Event Loop
242+
----------------------------------
243+
244+
.. autosummary::
245+
:template: autosummary.rst
246+
:nosignatures:
247+
248+
backend_bases.FigureCanvasBase.flush_events
249+
backend_bases.FigureCanvasBase.draw_idle
250+
251+
252+
253+
If you have open windows that have pending UI
229254
events (mouse clicks, button presses, or draws) you can explicitly
230255
process those events by calling `.FigureCanvasBase.flush_events`.
231256
This will run the GUI event loop until all UI events currently waiting
@@ -243,7 +268,7 @@ For example ::
243268
fig, ax = plt.subplots()
244269
fig.canvas.show()
245270
th = np.linspace(0, 2*np.pi, 512)
246-
ax.set_Lima(-1.5, 1.5)
271+
ax.set_ylim(-1.5, 1.5)
247272

248273
ln, = ax.plot(th, np.sin(th))
249274

@@ -281,9 +306,6 @@ The more frequently you call `.FigureCanvasBase.flush_events` the more
281306
responsive your figure will feel but at the cost of spending more
282307
resource on the visualization and less on your computation.
283308

284-
The third case you will have to integrate updating the ``Aritist``
285-
instances, calling ``draw_idle``, and flushing the GUI event loop with your
286-
data I/O.
287309

288310
.. _stale_artists:
289311

@@ -312,7 +334,7 @@ the artists parent. If you wish to suppress a given artist from propagating
312334
set this attribute to None.
313335

314336
`.figure.Figure` instances do not have a containing artist and their
315-
default callback is `None`. If you call ``.pyplot.ion` and are not in
337+
default callback is `None`. If you call `.pyplot.ion` and are not in
316338
``IPython`` we will install callback to invoke
317339
`~.backend_bases.FigureCanvasBase.draw_idle` when ever the
318340
`.figure.Figure` becomes stale. In ``IPython`` we use the
@@ -405,7 +427,7 @@ IPython / prompt toolkit
405427

406428
With IPython >= 5.0 IPython has changed from using cpython's readline
407429
based prompt to a ``prompt_toolkit`` based prompt. ``prompt_toolkit``
408-
has the same conceptual input hook, which is feed into pt via the
430+
has the same conceptual input hook, which is feed into prompt_toolkit via the
409431
:meth:`IPython.terminal.interactiveshell.TerminalInteractiveShell.inputhook`
410432
method. The source for the prompt_toolkit input hooks lives at
411433
:mod:`IPython.terminal.pt_inputhooks`

0 commit comments

Comments
 (0)