matplotlib Code

432 lines (346 with data), 15.3 kB

FAQs = (

    ('VERSIONS',
    'What do the version numbers mean?',

    """
The system has been evolving a bit, but here is what I am currently
using

<ul>

<li>0.50, 0.60, etc.: major releases to wider community.  Should be
thoroughly bug tested and vetted</li>

<li>0.51, 0.52, etc.: new features released to matplotlib-users for
bug-vetting</li>

<li>0.51.1, 0.51.2, etc.: bug fix releases.</li>

</ul>
"""),

    ('NUMARRAY',
    'Does matplotlib work with numarray?',
    """
Yes.  Todd Miller has added a numerix module which allows you to
choose between Numeric or numarray at the promptw, in a config file,
or using an environment variable.  For the most part, this works
seamlessly.  See <a href=matplotlib.numerix.html>numerix module</a>
for more information.
"""),

    ('MATPLOTLIBRC', 
     'How do I customize the default behavior of matplotib?', 
"""
Recent versions of matplotlib (0.51 or later) use a configuration file
to set everything from the default font, to the figure size, to the
default line width.  See <a href=.matplotlibrc>.matplotlibrc</a> for a
sample config file and information on how to use it.  """),

    ('CUSTOM',
    'How do I customize the default behavior of a single session?',
    r"""
If you want to customize a session of matplotlib, eg, the default font,
linewidth, fontsize, etc, you can import and customize the rcParams
determined by the matplotlibrc file (see above).  For example, if you
are using mathtext you may want your default axes labels, tick labels
etc, to be in the same font as mathtext roman.  <it>You must import
and customize the rcParams before importing anything else from
matplotlib</it>

<pre>
from matplotlib import rcParams
# default font is computer modern roman and linewidth is 1.0
rcParams['text.fontname']   = 'cmr10'
rcParams['lines.linewidth'] = 2.0

from matplotlib.matlab import *
plot([1,2,3])
title(r'$\rm{Histogram of IQ:} \mu=100, \sigma=15$')
show()
</pre>
"""),
	
    ('GTKPATH',
    'I cannot import gtk / gdk / gobject',
    """

Basically, there are 3 things that I've seen cause failure (relative
likelihood in parentheses):

 <ul> 

 <li> You didn't set the path properly (95% of the time).
 <it>Solution:</it> <a
 href=http://www.async.com.br/faq/pygtk/index.py?req=show&file=faq21.012.htp>pygtk
 FAQ entry</a></li>

 <li> You previously installed some other GTK app and one of libiconv
   / libgtk /libgdk is in your windows system dir and causing a
   problem (4% of the time).  <it>Solution:</it> Remove these old libs.</li>

 <li> You accidentally installed GTK-Development lib and not
   GTK-Runtime (1% of the time).  <it>Solution:</it> install the
   runtime as described at <a
   href=http://www.async.com.br/faq/pygtk/index.py?req=show&file=faq21.012.htp>pygtk
   FAQ entry</a>.  There is a long thread on the pygtk mailing list
   where Cousing Stanley got his gtk corrupted; read <a
   href=http://www.mail-archive.com/pygtk@daa.com.au/msg07324.html>this
   thread</a>, which is filled with good advice.  
  </ul>

""" ),
	

    ('WHICHBACKEND',
     'Which backend should I use?',
     """
Each of the backends offers different strengths.  I'll summarize some
of them. 

<h4>Image generation</h4>

For pure image generation (no GUI) you can choose from the Agg, Paint,
GD, or PS backends.  At this point, I advise people to use the <a
href=http://antigrain.com>agg</a> backend because:

<ul>
  <li>it's the fastest</li>
  <li>it uses freetype2 (as does GD) which renders nicely even
      at small resolutions </li>
  <li>there are clipping issues with GD and Paint </li>
  <li>it supports fast antialiased drawing and alpha blending </li>
  <li>it supports <a href=matplotlib.mathtext.html>mathtext</a></li>
  <li>it supports images with <a href=matplotlib.matlab.html#-imshow>imshow</a></li>
</ul>

It is likely that with time many of these limitiations or problems
will be fixed on the other backends.<p>

For publication submission or use with TeX, however, the postscript
backend is naturally a good choice.

<h4>GUI</h4>

Currently there are several choices for GUIs: GTK, Wx, TkAgg, and
GTKAgg, with different advantages.

<ul>

<li>Speed: TkAgg and GTKAgg are likely to be the fastest since most of Agg is renderered in C extension code</li>

<li>Stability: GTK was the first backend and thus has been most
thoroughly vetted for bugs.  The GTKAgg backend reuses the GTK widget
code, so should likewise be quite stable</li>

<li>Interactivity: All of the GUI backends can be used interactively
from a python shell (see <a href=interactive.html>interactive</a>) but
TkAgg is the hands-down winner here since it can be use from any
python shell whereas the GTK and Wx backends require a GUI specific
shell </li>

<li>Pretty widgets: If you want to embed matplotlib in an application
and pretty GUIs are important to you, Wx, GTK, or GTKAgg are probably
your best best.  Tk widgets are not visually stunning. </li>

</ul>


"""),

    ('DATES',
     'Can I plot dates?',
     r"""
As of matplotlib-0.53, you can plot dates using a variety of datetime
instances (eg python2.3 datetime module, mx.DateTime, raw epoch data).
There are a number of converters, major and minor tick locators, and
date formatters specialized for plotting dates.  See see <a
href=matplotlib.ticker.html>ticker</a> and <a
href=matplotlib.dates.html>dates</a> for details and usage and the
examples <a href=examples/date_demo1.py>date_demo1.py</a> and <a
href=examples/date_demo2.py>date_demo2.py</a>.
"""),

    ('TWOSCALES',
     'Can I plot data with two y axes scales?',
     r"""
As of matplotlib-0.53, there is support for this.  See <a
href=examples/two_scalers.py>two_scales.py</a>.
"""),

    ('MATHTEXT',
     'Can I include math expressions in my figures?',
     r"""As of matplotlib-0.51, you can use TeX markup in any text element.
Just use raw strings and enclose the strings with dollar signs, as in
<tt>title(r'$\\alpha > \\beta_i$')</tt>.  See <a
href=screenshots.html#mathtext_demo>screenshot</a> and the <a
href=matplotlib.mathtext.html>mathtext</a> documentation for usage,
requirements and backend information.
"""),
    
    ('BATCHMODE',
     'Can I just generate images without having a window popup?',
     """
The easiest way to do this is use an image backend, either <a
href=backends.html#Agg>Agg</a>, <a
href=backends.html#GD>GD</a> or <a href=backends.html#Paint>Paint</a>
if you want to generate PNG images, eg, for use in a web page, or PS
if you want publication quality, scalable images.  All of these
backends run on all of the major platforms.  One additional option on
an X windows platform is to run the GTK backend under an Xvfb, which
works nicely and is not too hard to setup.  Contact
jdhunter@ace.bsd.uchicago.edu for more information if you are
interested setting this up."""),

    ('APPSERVER',
     'Can I use matplotlib in a web application server?',
     """
Yes.  matplotlb can be used with any web application server that can
call python.  It has been used with mod_python, xml_rpc, and other
frameworks.  You'll want to use one of the image backends; <a
href=faq.html#BATCHMODE>see image backends</a>.  Also to make small images
appropriate for use on a web page, you may want to consider the Agg or GD
backends, since they render small font rasters using freetype2 better
than Paint, which currently use freetype1.  You can work around
the problem of small raster sizes by making your fonts appear larger
for a given by decreasing the figure size and increasing the dpi.  Eg,

<pre>
figure(figsize=(6,4))
plot(blah, blah)
savefig('myfile', dpi=75)
</pre>

See <a href=fonts.html#TTFFONTS>ttf fonts</a> for more information.
"""

     ),

    ('SHOW',
     "What's up with 'show'?  Do I have to use it?",
     """
The use of show is probably the biggest source of confusion and
vexation among new users of matplotlib.  First of all, you do not
need this function with the image backends (Agg, Paint, GD, PS) but you do
need it with the GUI (GTK, WX, TkAgg, GTKAgg) backends, unless you are running
matplotlib in <a href=interactive.html>interactive mode</a>.  <p>

Because it is expensive to draw, I want to avoid redrawing the figure
many times in a batch script such as the following<p>

<pre>
  plot([1,2,3])            # draw here ?
  xlabel('time')           # and here ?
  ylabel('volts')          # and here ?
  title('a simple plot')   # and here ?
  show()            
</pre>

It is possible to force matplotlib to draw after every command, which
is what you want in <a href=interactive.html>interactive mode</a>, but
in a script you want to defer all drawing until the script has
executed.  This is especially important for complex figures that take
some time to draw.  'show' is designed to tell matplotlib that you're
all done issuing commands and you want to draw the figure now.  In the
TkAgg backend, which can be used from an arbitrary python shell
interactively, it also sets interactive mode.  So you can launch your
script with <tt>python -i myscript.py -dTkAgg</tt> and then change it
interactively from the shell."""),
 
    ('PSGUI',
     'Can I save PS/EPS from a GUI backend?',
     """
Yep.  Just choose a filename that contains <tt>ps</tt> in the extension, eg
<tt>somefile.ps</tt> or <tt>somefile.eps</tt> and matplotlib will try
and do the right thing.  That is, if it's an eps file, it will include
a bounding box, if it's a ps file it will output plain postscript.  It
is recommended you use matplotlib-0.50 or later for this feature to
work properly."""),

  ('TEXTOVERLAP',
   'My title or ticklabel or whatever is overlapping some other figure element, what should I do?',
   """
The default subplots take up a lot of room.  If you need extra space
for particularly large labels and titles, consider using custom <a
href=matplotlib.matlab.html#-axes>axes</a>, eg, <tt>axes([0.3, 0.3, 0.6,
0.6])</tt> gives you more room to the left and at the bottom than the
standard axes.</p>

Other things to consider.  With multiple subplots, eg, multiple rows,
turn off the xticklabels for all but the lowest subplot if they are
the same in all subplots <tt>set(gca(), 'xticklabels', [])</tt>.  You
can make the fontsizes smaller, as in <tt>xlabel('time (s)',
fontsize=8)</tt> or, for the tick labels

<pre>
t = gca().get_xticklabels()
set(t, 'fontsize', 8)
</pre>

You can also set the default ticklabel size in your <a
href=faq.html#MATPLOTLIBRC>matplotlibrc</a> file or override it for a
single plot using <a
href=faq.html#CUSTOM>rcParams</a>."""),

    ('DYNAMIC',
     'Can matplotlib do dynamic plots, like digital oscilloscopes or animations?', 
    """
Absolutely.  See for example, <a href=examples/anim.py>anim.py</a> and <a
href=examples/system_monitor.py>system_monitor.py</a>"""),

    ('PERFORMANCE',
     'Is matplotlib fast enough for very large data sets?',
     """
The answer, of course, is "it depends".  I've worked hard to make
matplotlib work well with very large data sets (100s of MB), because
these are the kinds of data I need to handle at work.  It is very good
at handling data sets where the x axis is contiguous (eg, time) and
only a small portion of data in displayed in the viewport; see for
example <a href=examples/stock_demo.py>stock_demo.py<a/> where you can
scroll through 2 months of minute-by-minute stock quote data.<br>

The performance with higher dimensional data, eg, pseudocolor plots
with x, y, and intensity parameters, is now dramatically better with
the image module.  Use imshow with a colormap in place of pcolor for
fast image drawing.  See, for example, <a
href=examples/specgram_demo.py>specgram_demo.py</a> and <a
href=examples/image_demo.py>image_demo.py</a>.<br>

Several people with high bandwidth requirements have reported being
happy with matplotlib's performance.  If you find areas that need
improvement, let me know.  """),

    ('IMAGES',
    'Can matplotlib handle image data?',
     """
Yes - you can now plot array images with <a
href=matplotlib.matlab.html#-imshow>imshow</a>.  More image loaders
coming soon. """),

    ('ROTATETICKS',
     'How do I make vertical xticklabels?',
     """
You can set the rotation of any text instance to vertical

<pre>
    from matplotlib.matlab import *
    plot([1,2,3,4], [1,4,9,16])
    set(gca(), 'xticks', [1,2,3,4])
    labels = set(gca(), 'xticklabels', ['Frogs', 'Hogs', 'Bogs', 'Slogs'])
    set(labels, 'rotation', 'vertical')
    show()
</pre>
"""),

     ('WINFONTS',
      "On windows with GTK, I'm getting lots of messages about not finding the  Times font",
    r"""

Apparently GTK changed the default pango font file, because this is a
new problem.  You can set font aliases in
C:\GTK\etc\pango\pango.aliases.  Add a line like

<pre>
times = "times new roman,angsana new,mingliu,simsun,gulimche,ms gothic,latha,mangal,code2000"
</pre>

Another alternative is suggested by Gary Ruben <gazzar@email.com>

<pre>
I just installed Gimp 2 for windows along with the latest GTK+ runtime
and noticed that it exhibited the same font problem I've been
experiencing for ages with matplotlib. I was getting WARNING **:

  Couldn't load font "MS Sans Serif 8" falling back to "Sans 8"
  errors. 

It's addressed in their FAQ,
http://www2.arnes.si/~sopjsimo/gimp/faq.html>, reproduced here:

  # I installed Gimp 2.0 on Windows 9x/ME or NT 4, and I'm getting a
  lot of messages saying ** (gimp-2.0.exe:4294830849): WARNING **:
  Couldn't load font "MS Sans Serif 8" falling back to "Sans 8". What
  should I do?

  # You have two options:

  * Go to Control Panel->Display properties->Apperance tab, and set
  all fonts to Tahoma (or any other TrueType font).

  * Uninstall GTK+ 2.2.4, then re-install it without the GTK-Wimp
  component.

I took option B and now all is well with both Gimp and Matplotlib.
I'm running Win98 and the Gimp FAQ entry hints that it may be a
problem in Win98,ME and NT installations. It might be worth adding
this to the Matplotlib faq page next to the "On windows with
GTK, I'm getting lots of messages about not finding the Times
font" entry.

Gary
<pre>


""" 

),

     ('FONTCACHE',
      "On windows with GD/Agg/Paint, the first time I ran my script I got a bunch or error messages but don't anymore",
    """
These modules use FontTools and TTFQuery to find freetype fonts.  The
first time you import one of these backends, a font registry created
in site-packages/ttfquery/font.cache.  As you system is scanned for
fonts, some errors may be caught if a font file is not readable, etc.
Generally, this is not a major problem, as long as most system fonts
are found.  In subsequent runs, the font.cache is already built so you
won't see the messages again.  If you want to see the error messages,
remove font.cache and rerun your script, capturing them to a file.
""" ),
     
     ('FREETYPE2',
      "Why are my fonts not being rendered properly?",
    """
This is probably due to an outdated freetype2 library.  The latest
version is 2.1.8.  See <a href=matplotlib.font_manager.html>font manager
docs</a> for details.
""" ),
    
    
     )
@header@
<h2> matplotlib FAQ </h2>

<h2> Questions </h2>
 <ul>
 + for name,q,a, in FAQs:
   <li><a href=faq.html#@name@>@q@</a></li>
 -
 </ul>

<h2> Answers </h2>
 + for name,q,a, in FAQs:
   <h3><a name=@name@><font color="#0000EE">@q@</font></a></h3>
     @a@
   <p>
 -

@footer@