@@ -15,8 +15,8 @@ Plotting: howto
15
15
16
16
.. _howto-findobj :
17
17
18
- Find all objects in figure of a certain type
19
- -------------------------------------------------------------
18
+ Find all objects in a figure of a certain type
19
+ ----------------------------------------------
20
20
21
21
Every matplotlib artist (see :ref: `artist-tutorial `) has a method
22
22
called :meth: `~matplotlib.artist.Artist.findobj ` that can be used to
@@ -27,16 +27,16 @@ following snippet finds every object in the figure which has a
27
27
`set_color ` property and makes the object blue::
28
28
29
29
def myfunc(x):
30
- return hasattr(x, 'set_color')
30
+ return hasattr(x, 'set_color')
31
31
32
32
for o in fig.findobj(myfunc):
33
- o.set_color('blue')
33
+ o.set_color('blue')
34
34
35
35
You can also filter on class instances::
36
36
37
37
import matplotlib.text as text
38
38
for o in fig.findobj(text.Text):
39
- o.set_fontstyle('italic')
39
+ o.set_fontstyle('italic')
40
40
41
41
42
42
.. _howto-transparent :
@@ -70,7 +70,7 @@ on individual elements, eg::
70
70
71
71
.. _howto-multipage :
72
72
73
- Save multiple plots in one pdf file
73
+ Save multiple plots to one pdf file
74
74
-----------------------------------
75
75
76
76
Many image file formats can only have one image per file, but some
@@ -87,7 +87,7 @@ the format::
87
87
88
88
savefig(pp, format='pdf')
89
89
90
- A simpler way is to call
90
+ An easier way is to call
91
91
:meth: `PdfPages.savefig <matplotlib.backends.backend_pdf.PdfPages.savefig> `::
92
92
93
93
pp.savefig()
@@ -144,15 +144,14 @@ specify the location explicitly::
144
144
ax = fig.add_axes([left, bottom, width, height])
145
145
146
146
where all values are in fractional (0 to 1) coordinates. See
147
- `axes_demo.py <http://matplotlib.sf.net/examples/axes_demo.py >`_ for
148
- an example of placing axes manually.
147
+ :ref: `pylab_examples-axes_demo ` for an example of placing axes manually.
149
148
150
149
.. _howto-auto-adjust :
151
150
152
151
Automatically make room for tick labels
153
152
----------------------------------------------------
154
153
155
- In most use cases, it is enough to simpy change the subplots adjust
154
+ In most use cases, it is enough to simply change the subplots adjust
156
155
parameters as described in :ref: `howto-subplots-adjust `. But in some
157
156
cases, you don't know ahead of time what your tick labels will be, or
158
157
how large they will be (data and labels outside your control may be
@@ -174,8 +173,8 @@ connecting
174
173
get the window extent there, and then do something with it, eg move
175
174
the left of the canvas over; see :ref: `event-handling-tutorial `.
176
175
177
- Here is that gets a bounding box in relative figure coordinates (0..1)
178
- of each of the labels and uses it to move the left of the subplots
176
+ Here is an example that gets a bounding box in relative figure coordinates
177
+ (0..1) of each of the labels and uses it to move the left of the subplots
179
178
over so that the tick labels fit in the figure
180
179
181
180
.. plot :: pyplots/auto_subplots_adjust.py
@@ -233,7 +232,7 @@ When plotting time series, eg financial time series, one often wants
233
232
to leave out days on which there is no data, eg weekends. By passing
234
233
in dates on the x-xaxis, you get large horizontal gaps on periods when
235
234
there is not data. The solution is to pass in some proxy x-data, eg
236
- evenly sampled indicies , and then use a custom formatter to format
235
+ evenly sampled indices , and then use a custom formatter to format
237
236
these as dates. The example below shows how to use an 'index formatter'
238
237
to achieve the desired plot::
239
238
@@ -250,8 +249,8 @@ to achieve the desired plot::
250
249
ind = np.arange(N) # the evenly spaced plot indices
251
250
252
251
def format_date(x, pos=None):
253
- thisind = np.clip(int(x+0.5), 0, N-1)
254
- return r.date[thisind].strftime('%Y-%m-%d')
252
+ thisind = np.clip(int(x+0.5), 0, N-1)
253
+ return r.date[thisind].strftime('%Y-%m-%d')
255
254
256
255
fig = plt.figure()
257
256
ax = fig.add_subplot(111)
@@ -405,15 +404,15 @@ A frequent request is to have two scales for the left and right
405
404
y-axis, which is possible using :func: `~matplotlib.pyplot.twinx ` (more
406
405
than two scales are not currently supported, though it is on the wish
407
406
list). This works pretty well, though there are some quirks when you
408
- are trying to interactively pan and zoom, since both scales do not get
407
+ are trying to interactively pan and zoom, because both scales do not get
409
408
the signals.
410
409
411
- The approach :func: `~matplotlib.pyplot.twinx ` (and its sister
412
- :func: `~matplotlib.pyplot.twiny `) uses is to use *2 different axes *,
410
+ The approach uses :func: `~matplotlib.pyplot.twinx ` (and its sister
411
+ :func: `~matplotlib.pyplot.twiny `) to use *2 different axes *,
413
412
turning the axes rectangular frame off on the 2nd axes to keep it from
414
413
obscuring the first, and manually setting the tick locs and labels as
415
414
desired. You can use separate matplotlib.ticker formatters and
416
- locators as desired since the two axes are independent::
415
+ locators as desired because the two axes are independent::
417
416
418
417
import numpy as np
419
418
import matplotlib.pyplot as plt
@@ -444,7 +443,7 @@ Generate images without having a window popup
444
443
445
444
The easiest way to do this is use an image backend (see
446
445
:ref: `what-is-a-backend `) such as Agg (for PNGs), PDF, SVG or PS. In
447
- your figure generating script, just place call
446
+ your figure generating script, just call the
448
447
:func: `matplotlib.use ` directive before importing pylab or
449
448
pyplot::
450
449
@@ -465,17 +464,43 @@ pyplot::
465
464
Use :func: `~matplotlib.pyplot.show `
466
465
------------------------------------------
467
466
468
- The user interface backends need to start the GUI mainloop, and this
469
- is what :func: `~matplotlib.pyplot.show ` does. It tells matplotlib to
470
- raise all of the figure windows and start the mainloop. Because the
471
- mainloop is blocking, you should only call this once per script, at
472
- the end. If you are using matplotlib to generate images only and do
473
- not want a user interface window, you do not need to call ``show `` (see
474
- :ref: `howto-batch ` and :ref: `what-is-a-backend `).
467
+ When you want to view your plots on your display,
468
+ the user interface backend will need to start the GUI mainloop.
469
+ This is what :func: `~matplotlib.pyplot.show ` does. It tells
470
+ matplotlib to raise all of the figure windows created so far and start
471
+ the mainloop. Because this mainloop is blocking (i.e., script execution is
472
+ paused), you should only call this once per script, at the end. Script
473
+ execution is resumed after the last window is closed. Therefore, if you are
474
+ using matplotlib to generate only images and do not want a user interface
475
+ window, you do not need to call ``show `` (see :ref: `howto-batch ` and
476
+ :ref: `what-is-a-backend `).
475
477
478
+ .. note ::
479
+ Because closing a figure window invokes the destruction of its plotting
480
+ elements, you should call :func: `~matplotlib.pyplot.savefig ` *before *
481
+ calling ``show `` if you wish to save the figure as well as view it.
482
+
483
+ .. versionadded :: v1.0.0
484
+ ``show `` now starts the GUI mainloop only if it isn't already running.
485
+ Therefore, multiple calls to ``show `` are now allowed.
476
486
477
- Because it is expensive to draw, matplotlib does not want to redrawing the figure
478
- many times in a script such as the following::
487
+ Having ``show `` block further execution of the script or the python
488
+ interperator depends on whether matplotlib is set for interactive mode
489
+ or not. In non-interactive mode (the default setting), execution is paused
490
+ until the last figure window is closed. In interactive mode, the execution
491
+ is not paused, which allows you to create additional figures (but the script
492
+ won't finish until the last figure window is closed).
493
+
494
+ .. note ::
495
+ Support for interactive/non-interactive mode depends upon the backend.
496
+ Until version 1.0.0 (and subsequent fixes for 1.0.1), the behavior of
497
+ the interactive mode was not consistent across backends.
498
+ As of v1.0.1, only the macosx backend differs from other backends
499
+ because it does not support non-interactive mode.
500
+
501
+
502
+ Because it is expensive to draw, you typically will not want matplotlib
503
+ to redraw a figure many times in a script such as the following::
479
504
480
505
plot([1,2,3]) # draw here ?
481
506
xlabel('time') # and here ?
@@ -484,24 +509,24 @@ many times in a script such as the following::
484
509
show()
485
510
486
511
487
- It is *possible * to force matplotlib to draw after every command,
488
- which is what you usually want when working interactively at the
512
+ However, it is *possible * to force matplotlib to draw after every command,
513
+ which might be what you want when working interactively at the
489
514
python console (see :ref: `mpl-shell `), but in a script you want to
490
- defer all drawing until the script has executed . This is especially
515
+ defer all drawing until the call to `` show `` . This is especially
491
516
important for complex figures that take some time to draw.
492
517
:func: `~matplotlib.pyplot.show ` is designed to tell matplotlib that
493
518
you're all done issuing commands and you want to draw the figure now.
494
519
495
520
.. note ::
496
521
497
- :func: `~matplotlib.pyplot.show ` should be called at most once per
498
- script and it should be the last line of your script. At that
499
- point, the GUI takes control of the interpreter. If you want to
500
- force a figure draw, use :func: `~matplotlib.pyplot.draw ` instead.
522
+ :func: `~matplotlib.pyplot.show ` should typically only be called
523
+ at most once per script and it should be the last line of your script.
524
+ At that point, the GUI takes control of the interpreter. If you want
525
+ to force a figure draw, use :func: `~matplotlib.pyplot.draw ` instead.
501
526
502
- Many users are frustrated by show because they want it to be a
503
- blocking call that raises the figure, pauses the script until the
504
- figure is closed , and then allows the script to continue running until
527
+ Many users are frustrated by `` show `` because they want it to be a
528
+ blocking call that raises the figure, pauses the script until they
529
+ close the figure , and then allow the script to continue running until
505
530
the next figure is created and the next show is made. Something like
506
531
this::
507
532
@@ -512,7 +537,13 @@ this::
512
537
513
538
This is not what show does and unfortunately, because doing blocking
514
539
calls across user interfaces can be tricky, is currently unsupported,
515
- though we have made some progress towards supporting blocking events.
540
+ though we have made significant progress towards supporting blocking events.
541
+
542
+ .. versionadded :: v1.0.0
543
+ As noted earlier, this restriction has been relaxed to allow multiple
544
+ calls to ``show ``. In *most * backends, you can now expect to be
545
+ able to create new figures and raise them in a subsequent call to
546
+ ``show `` after closing the figures from a previous call to ``show ``.
516
547
517
548
518
549
.. _howto-contribute :
@@ -537,7 +568,7 @@ want to receive them in a standard format. If possible, for any
537
568
non-trivial change, please include a complete, free-standing example
538
569
that the developers can run unmodified which shows the undesired
539
570
behavior pre-patch and the desired behavior post-patch, with a clear
540
- verbal description of what to look for. The original developer may
571
+ verbal description of what to look for. A developer may
541
572
have written the function you are working on years ago, and may no
542
573
longer be with the project, so it is quite possible you are the world
543
574
expert on the code you are patching and we want to hear as much detail
@@ -560,7 +591,7 @@ Contribute to matplotlib documentation
560
591
-----------------------------------------
561
592
562
593
matplotlib is a big library, which is used in many ways, and the
563
- documentation we have only scratches the surface of everything it can
594
+ documentation has only scratched the surface of everything it can
564
595
do. So far, the place most people have learned all these features are
565
596
through studying the examples (:ref: `how-to-search-examples `), which is a
566
597
recommended and great way to learn, but it would be nice to have more
@@ -569,7 +600,7 @@ corners. This is where you come in.
569
600
570
601
There is a good chance you know more about matplotlib usage in some
571
602
areas, the stuff you do every day, than many of the core developers
572
- who write most of the documentation. Just pulled your hair out
603
+ who wrote most of the documentation. Just pulled your hair out
573
604
compiling matplotlib for windows? Write a FAQ or a section for the
574
605
:ref: `installing ` page. Are you a digital signal processing wizard?
575
606
Write a tutorial on the signal analysis plotting functions like
@@ -582,10 +613,10 @@ for it in the :ref:`users-guide-index`. Bundle matplotlib in a
582
613
583
614
matplotlib is documented using the `sphinx
584
615
<http://sphinx.pocoo.org/index.html> `_ extensions to restructured text
585
- `ReST <http://docutils.sourceforge.net/rst.html >`_. sphinx is a
616
+ `( ReST) <http://docutils.sourceforge.net/rst.html >`_. sphinx is an
586
617
extensible python framework for documentation projects which generates
587
618
HTML and PDF, and is pretty easy to write; you can see the source for this
588
- document or any page on this site by clicking on *Show Source * link
619
+ document or any page on this site by clicking on the *Show Source * link
589
620
at the end of the page in the sidebar (or `here
590
621
<../_sources/faq/howto_faq.txt> `_ for this document).
591
622
@@ -630,9 +661,9 @@ Agg is to call::
630
661
For more on configuring your backend, see
631
662
:ref: `what-is-a-backend `.
632
663
633
- Alternatively, you can avoid pylab/pyplot altogeher , which will give
664
+ Alternatively, you can avoid pylab/pyplot altogether , which will give
634
665
you a little more control, by calling the API directly as shown in
635
- ` agg_oo.py < http://matplotlib.sf.net/examples/api/agg_oo.py >`_ .
666
+ :ref: ` api_examples- agg_oo.py` .
636
667
637
668
You can either generate hardcopy on the filesystem by calling savefig::
638
669
@@ -650,7 +681,9 @@ or by saving to a file handle::
650
681
import sys
651
682
fig.savefig(sys.stdout)
652
683
653
- Here is an example using the Python Imaging Library PIL. First the figure is saved to a StringIO objectm which is then fed to PIL for further processing::
684
+ Here is an example using the Python Imaging Library PIL. First the figure
685
+ is saved to a StringIO object which is then fed to PIL for further
686
+ processing::
654
687
655
688
import StringIO, Image
656
689
imgdata = StringIO.StringIO()
0 commit comments