matplotlib Code

1116 lines (887 with data), 41.1 kB

FAQs = (


    ('BUGREPORT', 
     'How do I report a problem?',
"""\
OK, this is not a FAQ, but I wish it were <wink>.<p>

If you are having a problem <i>compiling</i> matplotlib, provide your
operating system and matplotlib version, any changes you may have made
to <tt>setup.py</tt> or <tt>setupext.py</tt>, and the output of

<pre>
  > rm -rf build
  > python setup.py build 
</pre>


If matplotlib compiled fine, but <i>no scripts run</i>, see <a
href=faq.html#FAILURE>failure</a>.<p>

If the matplotlib example scripts are running fine, and you have a
script that doesn't work that <i>you think may be a bug</i>, please
provide as much information as possible in your bug report, in
particular which matplotlib version and backend you are using,
operating system, and any nonstandard <a href=matplotlibrc>rc</a>
options.  Some of this information is provided simply by running your
script with <tt>python myscript.py --verbose-helpful</tt> and posting
the output along with your problem description.  Ideally, you should
provide a standalone script that runs on our system and exposes the
bug -- if you do this there is a very good chance the problem will be
fixed.  If we can't replicate the bug, it is much harder to fix.
Sometimes you cannot do this because the code or data is proprietary
-- in this case it is often helpful to post an image along with your
description that shows the problem.<p>

You can post problems either to the <a
href=http://lists.sourceforge.net/mailman/listinfo/matplotlib-users>matplotlib-users</a>
mailing list, or the sourceforge <a
href=http://sourceforge.net/tracker/?group_id=80706&atid=560720>bugs</a>
page.  I prefer the mailing list, because it gets read by more people,
and if it is a real and pesky bug I'll ask you to post it to the
sourceforge site.  But some people don't want the extra email traffic
of the mailing list, which is understandable, so it is fine to just
post to the sourceforge site.<p>
"""),


    ('FAILURE',
    "matplotlib compiled fine, but I can't get anything to plot" , """\
The first thing to try is to remove <tt>site-packages/matplotlib</tt>
and reinstall.  If you are running the windows installer or using some
other package, that is all you need to do.  If you are compiling
matplotlib yourself, you also need to remove the <tt>build</tt>
subdirectory of the matplotlib src tree you are compiling from.  It is
not enough to do <tt>python setup.py clean</tt>.  Try rebuilding and
reinstalling matplotlib after removing these two directories and see
if that helps.  If not, read on.<p>

The best way to test your install is by running a script, not working
interactively from a python shell or an integrated development
environment such as IDLE.  Each of those brings additional
complexities, as described at <a href=interactive.html>interactive
matplotlib</a> and this <a href=faq.html#FREEZE>faq</a>.  So open up a
UNIX shell (or a DOS command prompt) and cd into a directory
containing a minimal example in a file.  Something like <a
href=examples/simple_plot.py>simple_plot.py</a> or just this

<pre>
from pylab import *
plot([1,2,3])
show()
</pre>

and run it with (the verbose flag below is for matplotlib-0.64 or later)

<pre>
  > python simple_plot.py --verbose-helpful
</pre>

This will give you additional information about which backends
matplotlib is loading, version information, and more.  At this point
you might want to make sure you understand matplotlib's configuration
process, governed by the configuration file <a
href=matplotlibrc>matplotlibrc</a> which contains instructions within
and the concept of the matplotlib <a
href=backends.html>backend</a>.<p>

If you are still having trouble, please post a question and the output
of <tt>--verbose-helpful</tt> to the <a
href=http://sourceforge.net/mail/?group_id=80706>mailing list.</a>

"""),

    ('PYGTK24',
    "I can't compile matplotlib with pygtk 2.4." , """\
This is a <a
href="http://bugzilla.gnome.org/show_bug.cgi?id=155304">pygtk
bug</a>.  The patch is in pygtk CVS.  You basically need to add the
    G_BEGIN_DECLS/G_END_DECLS macros, and rename typename parameter to
    typename_

<pre>
-			  const char *typename,
+			  const char *typename_,
</pre>
"""),



    ('CLICKMAPS', "Can I use matplotlib to make clickable images?" ,
    """\ 
Yes.  Andrew Dalke of <a href=http://www.dalkescientific.com>Dalke
Scientific</a> has written a nice <a
href=http://www.dalkescientific.com/writings/diary/archive/2005/04/24/interactive_html.html>article</a>
on how to make html click maps with matplotlib agg PNGs.  We would
also like to add this functionality to SVG and add a SWF backend to
support these kind of images.  If you are interested in contributing
to these efforts that would be great.  If you need them but aren't up
to making the contribution yourself, please contact us on the <a href=http://sourceforge.net/mail/?group_id=80706>mailing
list</a> and fill out a <a href=http://sourceforge.net/tracker/?group_id=80706&atid=560721>support request</a>.

"""),

    ('ZORDER',
    "How can I control the order that my plot elements appear" , """\
Within an axes, the order that the various lines, markers, text,
collections, etc appear is determined by the <tt>zorder</tt> property
(matplotlib-0.65 or later).  The default order is patches, lines,
text, with collections of lines and collections of patches appearing
at the same level as regular lines and patches, respectively.  See <a
href=examples/zorder_demo.py>examples/zorder_demo.py</a>.
"""),

    ('TOOLBAR2',
    'Nothing happens when I click the new toolbar buttons', """\
The Home, Forward and back buttons on the new toolbar are used to
navigate between previously defined views.  If you haven't navigated
anywhere, these buttons will have no effect.  The Pan/Zoom, and zoom
to rect buttons activate a navigation mode, but by themselves do
nothing.  After clicking one of them, you need to put your mouse over
and axes and click/drag.  Then the navigation tools take effect - see
the <a href=tutorial.html#toolbar2>toolbar2 tutorial</a>.
"""),

    ('LOG',
     "I'm getting a log of zero error even though I know all of my data are positive",
     """\
This was a problem that occurs in versions of matplotlib < 0.72.
The log zero error is occurring when the transformation is made on the
<i>axes limits</i> and not on the data.  The autoscaler picks the best
min/max for the data coordinates, and will round down or up to
facilitate nice integer ticking.  When you plot with linear coords,
the autoscaler makes its pick according to linear scaling, and if when
you change scales the old scaling is in effect and the log transform
fails when converting the viewport.<p>

Solution: The best solution is to upgrade your matplotlib to >= 0.72.
If this is not a good option, rescale the axes after changing coords,
either manually

<pre>
  ax.set_yscale("log")
  ax.set_xscale("log")
  axis([minx, maxx, miny, maxy])
</pre>

or use the autoscaler

<pre>
  ax.set_yscale("log")
  ax.set_xscale("log")
  ax.autoscale_view()
</pre>

or set your log coords *before* calling a plot command

<pre>
  ax = gca()
  ax.set_yscale("log")
  ax.set_xscale("log")
  errorbar(x,y,err,fmt='o')
</pre>

and then the errorbar command will pick a "locator" to handle ticking
and viewport scaling appropriately from the outset.  This is the
approach taken in <a href=examples/log_bar.py>log_bar.py</a>.
"""),

    ('EQUAL', 
     'How do I make my figure square / axes sides equal?',
     """\
There are three considerations: the width/height of the figure, of the
axes, and the view limits

<pre>
figure(figsize=(8,8))       # figure sides equal
axes([0.1, 0.1, 0.8, 0.8])  # axes width, height equal
plot(something)
axis([-5, 5, -5, 5])        # view limits equal
</pre>

Note that your display device may not have the same dpi, in which case
your image will still not look square on your display.  I should
probably add dpix and dpiy to correct for this.  ZBut your postscript
and other hardcopy will be correct.<p>

If you really want square on a display with different horizontal and
vertical resolutions, you can do a little hack on the figure width and
height to correct for the display differences.
"""),
    
    ('FREEZE',
    'My matplotlib window is freezing',

""" Often times this is caused by running matplotlib with a backend
that is not compatible with your shell or IDE.<p>

There are known incompatiblities with some of the backends with some
of the IDEs, because they use different GUI event handlers. If you
want to use matplotlib from an IDE, please consult the backends
documentation for compatibility information. You will have the
greatest likelihood of success if you run the examples from the
command shell or by double clicking on them, rather than from an
IDE.<p>

If you are trying to generate plots interactively from the shell, you
need a shell that is compatible with your backend.  Currently, your
best bet is TkAgg from the standard python shell or ipython.  There
are a couple of custom GTK shells you can use, described <a
href=http://matplotlib.sourceforge.net/interactive.html>here</a>.<p>

To find out which IDEs are compatible with your backend, see <a
href=http://matplotlib.sourceforge.net/backends.html>backend</a>.<p>

To test whether you are experiencing a problem inherent in matplotlib,
you should open up a command shell and try to run one of the examples
from the matplotlib src distribution (the *.zip file for windows
users); Eg,

<pre>
  c:\matplotlib\examples> python simple_plot.py
</pre>

If this works fine, then you likely have an IDE/shell problem and not
a matplotlib specific problem.  Unfortunately, this problem tends to
crop up a lot.  See for example <a
href=http://sourceforge.net/mailarchive/message.php?msg_id=8610351>this
thread</a> and the responses to that post for more information.

"""),

    ('MOVIE', 'How do I make a movie with matplotlib?', """If you
want to take an animated plot and turn it into a movie, the best
approach is to save a series of image files (eg PNG) and use an
external tool to convert them to a movie.  There is a matplotlib
tutorial on this subject <a
href=http://web.media.mit.edu/~lifton/code/GraphMovies>here</a>.  You
can use <a
href=http://www.mplayerhq.hu/DOCS/HTML/en/mencoder.html>mencoder</a>,
which is part of the <a href=http://www.mplayerhq.hu>mplayer</a> suite
for this

<pre>
#fps (frames per second) controls the play speed
mencoder 'mf://*.png' -mf type=png:fps=10 -ovc \\
   lavc -lavcopts vcodec=wmv2 -oac copy -o animation.avi
</pre>

The swiss army knife of image tools, ImageMagick's <a
href=http://imagemagick.sourceforge.net/www/convert.html>convert</a>,
works for this as well.<p> 

Here is a simple example script that saves some PNGs, makes them into
a movie, and then cleans up.

<pre>
import os, sys
from pylab import *

files = []
figure(figsize=(5,5))
ax = subplot(111)
for i in range(50):  # 50 frames
    cla()
    imshow(rand(5,5), interpolation='nearest')
    fname = '_tmp%03d.png'%i
    print 'Saving frame', fname
    savefig(fname)
    files.append(fname)

print 'Making movie animation.mpg - this make take a while'
os.system("mencoder 'mf://_tmp*.png' -mf type=png:fps=10 \\
  -ovc lavc -lavcopts vcodec=wmv2 -oac copy -o animation.mpg")

# cleanup
for fname in files: os.remove(fname)

</pre>
"""),


    ('WRONGDIR',
    "When I try to import pylab, I get an error about no _transform.so or ft2font.so",

"""
If you are trying to run matplotlib from the matplotlib build dir, you
will fail.  This is because the matplotlib python src dir is in your
module path, but it does not include the compiled extension modules
which are in site-packages/matplotlib.  Change into another directory
and try again.<p>

If the problem persists, see if the required object files are in
site-packages/matplotlib.  If not, something is wrong with your
install.  You may want to try rebuilding with
<pre>
   > rm -rf build
   > python setup.py build > build.out 
</pre>

and post the results to the matplotlib-devel or matplotlib-users
<a href=http://sourceforge.net/mail/?group_id=80706>mailing lists</a>.
"""),
    

    ('EXAMPLES',
    'Where can I find information about what matplotlib can do?',
"""\
There are a lot of features under the hood in matplotlib.  This
tutorial is a good place to start.  When you are finished with it, the
next step (other than getting to work on your own figures, of course)
is to download the source distribution and take a look at the <a
href=http://matplotlib.sf.net/examples>examples</a> subdirectory.  If
you are working with date plots you'll find several date demos with
obvious filenames like <a
href=examples/date_demo1.py>examples/date_demo1.py</a>.  Likewise,
you'll find examples for images (<a
href=examples/image_demo.py>examples/image_demo.py</a>), contouring
(<a href=examples/contour_demo.py>examples/contour_demo.py</a>, using
matplotlib with a graphical user interface (<a
href=examples/embedding_in_wx.py>examples/embedding_in_wx.py</a> and
many more.  At last count, there were 116 examples.  Because these are
not included with the standard windows installer, they are often
overlooked, which is why I emphasize them here.<p>

The next place to turn to find the hidden gems is the <a
href=whats_new.html>what's new</a> page.  Every feature ever
introduced into matplotlib is listed on that page with the version it
was introduced, usually with links to examples and functions.
Scrolling through that page is one of the best ways to find out what
capabilities and customizations are supported.<p>
"""),


    ('LARGEPS',
    "My PS/EPS files are huge; what's wrong?",
"""
With matplotlib-0.61, Paul Barrett introduced truetype fonts in
backend_ps, primarily in order to support mathtext.  Because he was
unable to get the individual glyphs from freetype, he had to dump the
entire font into the PS file.  A typical font takes about 300K of
noncompressed space.  This, however, is a fixed cost and does not
increase with the complexity of the figure or number of points
plotted.  It would, however, increase if you use multiple fonts, eg in
mathtext.<p>

Before 0.61, we used the afm fonts that ship with matplotlib and
matplotlib has its own <a href=matplotlib.afm.html>AFM parser</a>
which handles character metrics, kerning, etc.  It would not be too
much work to have an option (eg in the matplotlib rc file) which
allows users to simply use AFM fonts when possible (eg when not using
mathtext) in which case you wouldn't see these big eps files.  The
other advantage to this approach is that they seem to render nicer in
some viewers, eg xdvi.<p>

One nice thing about dumping the truetype into the ps files is that
the text is the same across backends.  The ideal solution would be
able to dump just the glyphs needed, which presumably would be much
smaller, but we haven't figured this out yet.<p>

Given that the 300K is a fixed cost (118K gzipped), if you still find
the size sufficiently troublesome that it justifies the extra work (on
our end) to provide an option to revert to AFM fonts, please let us
know on the mailing list.
"""),

   ('PROMPT',
    "After my matplotlib script runs, I get a python shell prompt. What's going on?",
"""
Tkinter, used by the default windows backend TkAgg not have a mainloop
like GTK or WX.  We needed a way to keep the figure open, and decided
the best way was to switch into interactive mode in python.  This has
the additional benefit that you can issue additional python commands
to customize your figure interactively, if you want.
"""),

   ('USE',
    "matplotlib seems to be ignoring the <tt>use</tt> command",
"""
You must use the use command before importing pylab, as
described on <a href=backends.html>backends</a>

<pre>
  >>> import matplotlib
  >>> matplotlib.use('Agg')
  >>> from pylab import *
</pre>

Note that if you are using an IDE like pycrust, pythonwin, or IDLE,
pylab may have already been loaded, and subsequent calls
to <tt>use</tt> or <tt>from pylab import *</tt> will have
no effect unless you explicitly force a module reload.  """),

    ('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 prompt or in a config file.
See <a href=matplotlib.numerix.html>numerix module</a> for more
information.<p>

Some of the matplotlib extension code operates on Numeric/numarray
arrays, eg the image and transforms modules.  To get optimum
performance, you need to compile matplotlib with the package you want
to use.  matplotlib setup.py will automatically detect whether you
have Numeric or numarray or both at compile time, and will compile the
appropriate extensions to work with one or both, if present.  The
actual extension chosen at runtime will be determined by your
'numerix' <a href=matplotlibrc>matplotlibrc</a> setting."""),

    ('SLOW', 'matplotlib seems painfully slow, am I doing something wrong?',

     """\
Hopefully, yes.  A lot of work has gone into making matplotlib
reasonably fast plotting largish arrays and image data.  If things
seem exceptionally pokey, it may indicate a problem in your setup.
Before matplotlib-0.64, the most common cause is getting your numerix
settings out of kilter.  As indicated in <a href=faq.html#NUMARRAY>the
numarray faq</a>, it is important that the Numeric/numarray extension
you want to use is available at the time you compile matplotlib, since
the appropriate extensions are determined automatically when
matplotlib is compiled.  Both Numeric and numarray extensions are
available in the windows installer .  Failure to do so can cause up to
a 30-fold performance hit in some cases.<p>

Also, if you are running a python script, make sure your interactive
setting in your <a href=matplotlibrc>matplotlibrc</a> is <tt>False</tt>;
otherwise the figure will be redrawn with every plotting command when
what you want if for the figure to be drawn only once at the end of
the script.  See <a href=interactive.html>interactive</a> and <a
href=faq.html#SHOW>what's up with show?</a> for more information.<p>

For images, matplotlib-0.70 added a number of optimizations that
delivered approximately a 4x performance boost over earlier versions.
So if you need fast image support, make sure you are using the latest
release.  Also, the matplotlib normalization code, which converts
image data on an arbitrary scale to the unit interval, may be
unnecessary if your data is already scaled to the unit interval.  You
can avoid this cose by writing a do-nothing normalization function.
<pre>
class mynorm(normalize):
    def __call__(self, X):
        return X
imshow(X, norm=mynorm())
</pre>

Another possibility to speed things up is to use <a
href=matplotlib.collections.html>collections</a>, which were designed
to efficiently plot large numbers of objects with some shared
properties.  If you find youself issuing many spearate plot commands,
or instantiating many Line2D or Patch objects, you may benefit from
recoding with collections.  See the matplotlib.axes.Axes
implementatation of scatter and pcolor, and the matplotlib.finance
module, for examples.<p>

If you are experiencing problems with performance, please post an
example to the mailing list.  It would be helpful to provide as much
information as possible, such as what OS you are on, what backend you
are using, the size of the data arrays you are plotting, and the
output of <tt>python yourscript.py --verbose-helpful</tt>.
"""),

    ('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.  """),

    ('OO', 
     'Is there any guide to using matplotlib with pythonic / OO /API rather than the pylab interface?', 

"""

There is no official documentation yet, but there are a few resources

<ul>

  <li>The class documentation at <a href=classdocs.html>classdocs</a>.
      </li>

  <li>Andrew Dalke has a nice tutorial style <a
  href=http://www.dalkescientific.com/writings/diary/archive/2005/04/23/matplotlib_without_gui.html>article</a>
  on the API on the <a href=http://www.dalkescientific.com>Dalke
  Scientific</a> website.

  <li>Many examples in the <a href=examples>examples</a> directory in
      the matplotlib src distribution illustrate the use of the API.
      Eg, 

     <pre>
    
      > grep -l FigureCanvas *.py

      agg_oo.py dynamic_demo_wx.py dynamic_image_wxagg.py
      embedding_in_gtk2.py embedding_in_gtk.py embedding_in_qt.py
      embedding_in_tk2.py embedding_in_tk.py embedding_in_wx2.py
      embedding_in_wx3.py embedding_in_wx4.py embedding_in_wx.py
      gtk_spreadsheet.py histogram_demo_canvasagg.py mpl_with_glade.py
      object_picker.py printing_in_wx.py to_numeric.py webapp_demo.py
      wxcursor_demo.py

     </pre>
 </li>

  <li><a
      href=examples/pythonic_matplotlib.py>pythonic_matplotlib.py</a>
      describes the translation from the matlab style interface to the
      pythonic, OO interface.</li>

  <li> <tt>matplotlib/pylab.py </tt> in <tt>site-packages</tt> or the
      matplotlib src directory <tt>lib</tt> is a useful resource.  The
      pylab interface is just a thin wrapper around the API, so you
      can look and see how it is done there, translating all the gcf()
      calls to your figure instance, all the gca() calls to your axes
      instance, and so on.</li>

  <li>You can always post questions to <a
      href=http://sourceforge.net/mailarchive/forum.php?forum_id=33405>matplotlib-users</a></li>

</ul>


I'm working on some additional documentation but it is not ready yet.

"""),

    ('PY2EXE', 'Can I freeze matplotlib with py2exe', """\

Yes.  I have successfully frozen example scripts using the TkAgg,
GTKAgg and WxAgg backends.  One trick is to make sure that py2exe can
find all the matplotlib data files.  Recent versions of matplotlib
(0.54.3 and later) support py2exe by looking in the py2exe dist dir
for a <tt>matplotlibdata</tt> subdir.  Thus if your <tt>setup.py</tt>
script looks like

<pre>
from distutils.core import setup
import glob
import py2exe

data = glob.glob(r'C:\Python23\share\matplotlib\*')
data.append(r'C:\Python23\share\matplotlib\matplotlibrc')

setup( console    = ["simple_plot.py"],
       data_files = [("matplotlibdata", data)],
      )

</pre>

You don't need anything special in your plotting script.  Eg, the
following works fine with recent versions of py2exe

<pre>
from pylab import *
plot([1,2,3])
show()
</pre>

matplotlib should be able to find your matplotlib data directory.  You
can still configure the defaults in
<tt>dist/matplotlibdata/matplotlibrc</tt> after the application has
been frozen.<p>

Note you may get warnings like "The following modules appear to be
missing" but in general I have found these to be harmless for freezing
matplotlib.<p>

To freeze GTK or GTKAgg, you need to do a couple of extra things,
including creating a <tt>setup.cfg</tt> file and copying the
<tt>lib</tt> and <tt>etc</tt> subdirectories of yout GTK install tree
to your py2exe dist subdir.  See the <tt>simple_plot_gtk</tt>
subdirectory in the <a href=py2exe_examples.zip>py2exe examples</a>
zip file.<p>

If you want to reduce the size of your application by excluding
certain backends, see the <a
href=http://starship.python.net/crew/theller/moin.cgi/MatPlotLib>matplotlib
py2exe wiki entry</a>.

"""),

    ('CUSTOM',
    'How do I dynamically change the rc defaults?',
    r"""
If you want to customize a session of matplotlib, eg, the default font,
linewidth, fontsize, etc, use the <a
href=matplotlib.pylab.html#-rc>rc</a> command.  This changes the
default for the rest of the session, or until you issue another rc
command.  See <a examples/customize_rc.py>customize_rc.py</a> for
example usage."""),

	
    ('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> Add the lib and bin subdirs of your GTK install
 directory to your PATH.  See the <a
 href=http://www.async.com.br/faq/pygtk/index.py?req=show&file=faq21.002.htp>pygtk
 FAQ entry</a> for one way to do this.</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 from <a href=http://prdownloads.sourceforge.net/gtk-win>
   dropline</a>.</ul>

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 troubleshooting advice.

""" ),
	

    ('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, Cairo,
PS, SVG, Paint, GD or EMF 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.pylab.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, GTKAgg, GTKCairo, WX,
WXAgg, TkAgg and FltkAgg, 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 and GTKCairo backends reuse 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, GTKAgg or GTKCairo are probably
your best best.  Tk widgets are not visually stunning. </li>

</ul>


"""),

    ('DATES',
     'Can I plot dates?',
     r"""
See the <a href=tutorial.html#dates>dates tutorial</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>, href=backends.html#Cairo>Cairo</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, Cairo 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. See <a href=fonts.html#TTFFONTS>ttf fonts</a> for more
information.

matplotlib keeps a cache of the font information it finds on your
system, so it needs a writable directory.  It first tries
<tt>HOME</tt> and if it is not found falls back on it's data path,
which can be set with the <tt>MATPLOTLIBDATA</tt> environment
variable.  <tt>MATPLOTLIBDATA</tt> is the directory in which all of
matplotlib's fonts, etc, live, and is not writable on a typical
install, so the best approach is to set <tt>HOME</tt> to a writable
directory.

Also, I advise you not to use the pylab interface in a web application
server (though you can).  pylab does a fair amount of work under the
hood, managing the current figure and so on, and in an application
server you might rather have full control of the whole process.  pylab
is simply a thin wrapper to the object oriented matplotlib API; see
the <a href=faq.html#OO>API FAQ</a>.


"""

     ),

    ('SHOW',
     "What's up with 'show'?  Do I have to use it?",
     """


You do not need this function with the image backends (Agg, Cairo, Paint, GD,
PS) but you do need it with the GUI (GTK, WX, TkAgg, GTKAgg, GTKCairo) 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.

<b>IMPORTANT: show should called at most once per script and it should
be the last line of your script.  At that point, the GUI takes control
of the interpreter.  If you want to force a figure draw, use <a
href=matplotlib.pylab.html#-draw>draw</a> instead.</b> """),
 
    ('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.pylab.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>xticks([])</tt>.  You
can make the fontsizes smaller, as in <tt>xlabel('time (s)',
fontsize=8)</tt> or, for the tick labels

<pre>
locs, labels = xticks()
set(labels, 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>"""),

    ('AXES',
     'Can I change the size of the subplots',
     """

subplot is just a helper function to generate regularly spaced axes.
For more fine-grained control, you can position axes anywhere you want
in any size using the axes command.  See
the <a href=matplotlib.pylab.html#-axes>axes command</a> and the example
<a href=examples/axes_demo.py>axes_demo.py<a/>.<p>

"""),

    ('IMAGES',
    'Can matplotlib handle image data?',
     """
Yes - you can now plot images from numerix arraysq with <a
href=matplotlib.pylab.html#-imshow>imshow</a>.  You can load png
files into arrays <a href=matplotlib.pylab.html#-imread>imread</a>;
image loaders coming soon."""),

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

<pre>
    from pylab 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. 
</pre>


""" 

),

     
     ('FREETYPE2',
      "Why are my fonts not being rendered properly?",
    """
This is probably due to an outdated freetype2 library.  The latest
version is 2.1.9.  See <a href=matplotlib.font_manager.html>font manager
docs</a> for details.
""" ),

      ('LEAKS',
       'matplotlib appears to be leaking memory, what should I do?',
"""\

A number of severe memory leaks were fixed in the 0.54 and 0.60
matplotlib releases.  These have been fixed, and here are no known
leaks in matplotlib 0.63 or later with Numeric-23.5 or numarray >1.1.
There is a leak in freetype 2.1.7 and earlier that was fixed in
freetype 2.1.9.  The memory leak situation has improved significantly
as I've migrated almost all of the extension code to pycxx, and I use
a number of unit tests to test leaks of various extension code
components. <p>

Below is a prototypical script that I use to diagnose and report
memory leaks.  Please use something like it when reporting leaks so I
get an idea of the magnitude of the problem (ie bytes per figure).
Also please provide your platform, matplotlib version, backend and as
much information about the versions of the libraries you are using:
freetype, png and zlib.  It would also help if you posted code so I
could look for any obvious coding errors vis-a-vis matplotlib.<p>

Running the code below with 0.0000k bytes / per figure
(matplotlib-0.63.0 / agg backend on linux with freetype 2.1.9,
libpng1.2 and libz 1.1.4).  If your numbers are much worse, it may be
that you are doing something wrong, ie, not properly closing, reusing
figure, etc, so please post some code to the list.<p>


<B>There is a fairly large leak in <tt>dot</tt> and a smaller leak in
<tt>sometrue</tt> in numarray version 1.1, which matplotlib makes
heavy use of.  If you are using matplotlib with numarray, and are
concerned about leaks, please use numarray CVS.  Also, there appear to
be small leaks in earlier versions of Numeric.  My tests with
Numeric-23.5 and numarray CVS (2004-09-29) revealed no detectable
leaks.  </B>

<pre>
import os, sys, time
import matplotlib
matplotlib.use('Agg')
from pylab import *


def report_memory(i):
    pid = os.getpid()
    a2 = os.popen('ps -p %d -o rss,sz' % pid).readlines()
    print i, '  ', a2[1],
    return int(a2[1].split()[1])



# take a memory snapshot on indStart and compare it with indEnd
indStart, indEnd = 30, 150
for i in range(indEnd):
    ind = arange(100)
    xx = rand(len(ind))

    figure(1)
    subplot(221)
    plot(ind, xx)

    subplot(222)
    X = rand(50,50)
    
    imshow(X)
    subplot(223)
    scatter(rand(50), rand(50))
    subplot(224)
    pcolor(10*rand(50,50))

    savefig('tmp%d' % i, dpi = 75)
    close(1)


    val = report_memory(i)
   # wait a few cycles for memory usage to stabilize
    if i==indStart: start = val 

end = val
print 'Average memory consumed per loop: %1.4fk bytes\n' % \\
      ((end-start)/float(indEnd-indStart))

</pre>
"""),


     ('GUIWIDGETS',
      "How do I control the properties of my figure window, eg title, size, etc...?",
    """
The only way currently to control the window size from the matlab
interface is to set the figure size with the figsize option, eg
figure(figsize=(10,12)).  However, you can set window properties in a
backend dependent manner with the figure manager instance.
<pre>
  manager = get_current_fig_manager()
</pre>
<ul>
<li>backend_gtk*    : manager.window is a gtk.Window instance</li>
<li>backend_wx*     : manager.frame is a wxFrame instance</li>
<li>backend_tkagg   : manager.window is a Tk.Tk() instance</li>
<li>backend_fltkagg : manager.window is a Fltk.Fl_Double_Window</li>
</ul>

Thus to set the title in a gtk* backend, you could do
<pre>
manager = get_current_fig_manager()
manager.window.set_title('hi mom')
</pre>
Of course, now your scripts won't work with other matplotlib
backends.<p>

In theory, we could abstract the essential window calls and expose
them in a GUI neutral manner.  We are trying to resist the urge to
become a GUI wrapping library so we can focus on being a plotting
library.<p>

If you need a lot of control over GUI properties, you may want to skip
the pylab interface and use the matplotlib API directly, eg build a
GTK app which embeds matplotlib.  See examples/embedding_in*.py in the
matplotlib src distribution or at <a
href=http://matplotlib.sf.net/examples>examples</a> explaining how to
embed matplotlib in your GUI of choice.
"""),
    
     )
     
@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@