From: <jd...@us...> - 2008-12-10 03:57:13
|
Revision: 6538 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=6538&view=rev Author: jdh2358 Date: 2008-12-10 03:57:09 +0000 (Wed, 10 Dec 2008) Log Message: ----------- added whats new doc Modified Paths: -------------- trunk/matplotlib/doc/_templates/indexsidebar.html trunk/matplotlib/doc/users/index.rst Added Paths: ----------- trunk/matplotlib/doc/users/whats_new.rst Modified: trunk/matplotlib/doc/_templates/indexsidebar.html =================================================================== --- trunk/matplotlib/doc/_templates/indexsidebar.html 2008-12-10 03:01:14 UTC (rev 6537) +++ trunk/matplotlib/doc/_templates/indexsidebar.html 2008-12-10 03:57:09 UTC (rev 6538) @@ -1,10 +1,11 @@ <h3>Download</h3> <p>Current version: <b>{{ version }}</b></p> -<p>Download matplotlib from the -sourceforge <a href="http://sourceforge.net/projects/matplotlib">project</a> -page (but first take a look at the <a href="{{ -pathto('users/installing') }}">installing</a> page).</p> +<p>Download matplotlib from the sourceforge <a +href="http://sourceforge.net/projects/matplotlib">project</a> page +(but first take a look at the <a href="{{ pathto('users/installing') +}}">installing</a> page). Here's a summary of <a href="{{ +pathto('users/whats_new') }}">what's new</a>. </p> <p>There are several matplotlib addon <a href="{{ pathto('users/toolkits') }}">toolkits</a>, including the projection Modified: trunk/matplotlib/doc/users/index.rst =================================================================== --- trunk/matplotlib/doc/users/index.rst 2008-12-10 03:01:14 UTC (rev 6537) +++ trunk/matplotlib/doc/users/index.rst 2008-12-10 03:57:09 UTC (rev 6538) @@ -24,6 +24,7 @@ plotting.rst toolkits.rst screenshots.rst + whats_new.rst license.rst credits.rst Added: trunk/matplotlib/doc/users/whats_new.rst =================================================================== --- trunk/matplotlib/doc/users/whats_new.rst (rev 0) +++ trunk/matplotlib/doc/users/whats_new.rst 2008-12-10 03:57:09 UTC (rev 6538) @@ -0,0 +1,248 @@ +.. _whats-new: + +*************************** +What's new in matplotlib +*************************** + +.. _whats-new-0-98-4: + +What new in matplotlib 0.98.4 +============================== + +It's been four months since the last matplotlib release, and there are +a lot of new features and bug-fixes + +.. _legend-refactor: + +Legend enhancements +-------------------- + +Jae-Joon has rewritten the legend class, and added support for +multiple columns and rows, as well as fancy box drawing. See +:ref:`pylab_examples-legend_demo3`. + + +.. _fancy-annotations: + +Fancy annotations and arrows +----------------------------- + +Jae-Joon has added lot's of support to annotations for drawing fancy +boxes and connectors in annotations. See +:ref:`pylab_examples-annotation_demo2` and +:ref:`pylab_examples-fancyarrow_demo`. + +.. _psd-amplitude: + +psd amplitude scaling +------------------------- + +Ryan May did a lot of work to rationalize the amplitude scaling of +:func:`~matplotlib.pyplot.psd` and friends. See +:ref:`pylab_examples-psd_demo2`. and :ref:`pylab_examples-psd_demo3`. +The changes should increase `MATLAB™ <http://www.mathworks.com>` +compatabililty and increase scaling options. + +.. _fill-between: + +Fill between +------------------ + +Added a :func:`~matplotlib.pyplot.fill_between` function to make it +easier to do shaded region plots in the presence of masked data. See +:ref:`pylab_examples-fill_between`. + +Lots more +----------- + +Here are the 0.98.4 notes from the CHANGELOG:: + + Added mdehoon's native macosx backend from sf patch 2179017 - JDH + + Removed the prints in the set_*style commands. Return the list of + pprinted strings instead - JDH + + Some of the changes Michael made to improve the output of the + property tables in the rest docs broke of made difficult to use + some of the interactive doc helpers, eg setp and getp. Having all + the rest markup in the ipython shell also confused the docstrings. + I added a new rc param docstring.harcopy, to format the docstrings + differently for hardcopy and other use. Ther ArtistInspector + could use a little refactoring now since there is duplication of + effort between the rest out put and the non-rest output - JDH + + Updated spectral methods (psd, csd, etc.) to scale one-sided + densities by a factor of 2 and, optionally, scale all densities by + the sampling frequency. This gives better MatLab + compatibility. -RM + + Fixed alignment of ticks in colorbars. -MGD + + drop the deprecated "new" keyword of np.histogram() for numpy 1.2 + or later. -JJL + + Fixed a bug in svg backend that new_figure_manager() ignores + keywords arguments such as figsize, etc. -JJL + + Fixed a bug that the handlelength of the new legend class set too + short when numpoints=1 -JJL + + Added support for data with units (e.g. dates) to + Axes.fill_between. -RM + + Added fancybox keyword to legend. Also applied some changes for + better look, including baseline adjustment of the multiline texts + so that it is center aligned. -JJL + + The transmuter classes in the patches.py are reorganized as + subclasses of the Style classes. A few more box and arrow styles + are added. -JJL + + Fixed a bug in the new legend class that didn't allowed a tuple of + coordinate vlaues as loc. -JJL + + Improve checks for external dependencies, using subprocess + (instead of deprecated popen*) and distutils (for version + checking) - DSD + + Reimplementaion of the legend which supports baseline alignement, + multi-column, and expand mode. - JJL + + Fixed histogram autoscaling bug when bins or range are given + explicitly (fixes Debian bug 503148) - MM + + Added rcParam axes.unicode_minus which allows plain hypen for + minus when False - JDH + + Added scatterpoints support in Legend. patch by Erik Tollerud - + JJL + + Fix crash in log ticking. - MGD + + Added static helper method BrokenHBarCollection.span_where and + Axes/pyplot method fill_between. See + examples/pylab/fill_between.py - JDH + + Add x_isdata and y_isdata attributes to Artist instances, and use + them to determine whether either or both coordinates are used when + updating dataLim. This is used to fix autoscaling problems that + had been triggered by axhline, axhspan, axvline, axvspan. - EF + + Update the psd(), csd(), cohere(), and specgram() methods of Axes + and the csd() cohere(), and specgram() functions in mlab to be in + sync with the changes to psd(). In fact, under the hood, these + all call the same core to do computations. - RM + + Add 'pad_to' and 'sides' parameters to mlab.psd() to allow + controlling of zero padding and returning of negative frequency + components, respecitively. These are added in a way that does not + change the API. - RM + + Fix handling of c kwarg by scatter; generalize is_string_like to + accept numpy and numpy.ma string array scalars. - RM and EF + + Fix a possible EINTR problem in dviread, which might help when + saving pdf files from the qt backend. - JKS + + Fix bug with zoom to rectangle and twin axes - MGD + + Added Jae Joon's fancy arrow, box and annotation enhancements -- + see examples/pylab_examples/annotation_demo2.py + + Autoscaling is now supported with shared axes - EF + + Fixed exception in dviread that happened with Minion - JKS + + set_xlim, ylim now return a copy of the viewlim array to avoid + modify inplace surprises + + Added image thumbnail generating function + matplotlib.image.thumbnail. See examples/misc/image_thumbnail.py + - JDH + + Applied scatleg patch based on ideas and work by Erik Tollerud and + Jae-Joon Lee. - MM + + Fixed bug in pdf backend: if you pass a file object for output + instead of a filename, e.g. in a wep app, we now flush the object + at the end. - JKS + + Add path simplification support to paths with gaps. - EF + + Fix problem with AFM files that don't specify the font's full name + or family name. - JKS + + Added 'scilimits' kwarg to Axes.ticklabel_format() method, for + easy access to the set_powerlimits method of the major + ScalarFormatter. - EF + + Experimental new kwarg borderpad to replace pad in legend, based + on suggestion by Jae-Joon Lee. - EF + + Allow spy to ignore zero values in sparse arrays, based on patch + by Tony Yu. Also fixed plot to handle empty data arrays, and + fixed handling of markers in figlegend. - EF + + Introduce drawstyles for lines. Transparently split linestyles + like 'steps--' into drawstyle 'steps' and linestyle '--'. Legends + always use drawstyle 'default'. - MM + + Fixed quiver and quiverkey bugs (failure to scale properly when + resizing) and added additional methods for determining the arrow + angles - EF + + Fix polar interpolation to handle negative values of theta - MGD + + Reorganized cbook and mlab methods related to numerical + calculations that have little to do with the goals of those two + modules into a separate module numerical_methods.py Also, added + ability to select points and stop point selection with keyboard in + ginput and manual contour labeling code. Finally, fixed contour + labeling bug. - DMK + + Fix backtick in Postscript output. - MGD + + [ 2089958 ] Path simplification for vector output backends + Leverage the simplification code exposed through path_to_polygons + to simplify certain well-behaved paths in the vector backends + (PDF, PS and SVG). "path.simplify" must be set to True in + matplotlibrc for this to work. - MGD + + Add "filled" kwarg to Path.intersects_path and + Path.intersects_bbox. - MGD + + Changed full arrows slightly to avoid an xpdf rendering problem + reported by Friedrich Hagedorn. - JKS + + Fix conversion of quadratic to cubic Bezier curves in PDF and PS + backends. Patch by Jae-Joon Lee. - JKS + + Added 5-point star marker to plot command q- EF + + Fix hatching in PS backend - MGD + + Fix log with base 2 - MGD + + Added support for bilinear interpolation in + NonUniformImage; patch by Gregory Lielens. - EF + + Added support for multiple histograms with data of + different length - MM + + Fix step plots with log scale - MGD + + Fix masked arrays with markers in non-Agg backends - MGD + + Fix clip_on kwarg so it actually works correctly - MGD + + Fix locale problems in SVG backend - MGD + + fix quiver so masked values are not plotted - JSW + + improve interactive pan/zoom in qt4 backend on windows - DSD + + Fix more bugs in NaN/inf handling. In particular, path + simplification (which does not handle NaNs or infs) will be turned + off automatically when infs or NaNs are present. Also masked + arrays are now converted to arrays with NaNs for consistent + handling of masks and NaNs - MGD and EF This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jd...@us...> - 2008-12-10 04:12:00
|
Revision: 6540 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=6540&view=rev Author: jdh2358 Date: 2008-12-10 04:11:56 +0000 (Wed, 10 Dec 2008) Log Message: ----------- updated genrst Modified Paths: -------------- trunk/matplotlib/doc/_templates/gallery.html trunk/matplotlib/doc/matplotlibrc Modified: trunk/matplotlib/doc/_templates/gallery.html =================================================================== --- trunk/matplotlib/doc/_templates/gallery.html 2008-12-10 04:05:18 UTC (rev 6539) +++ trunk/matplotlib/doc/_templates/gallery.html 2008-12-10 04:11:56 UTC (rev 6540) @@ -433,6 +433,8 @@ <a href="examples/pylab_examples/psd_demo2.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/psd_demo2.png" border="0" alt="psd_demo2"/></a> +<a href="examples/pylab_examples/psd_demo3.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/psd_demo3.png" border="0" alt="psd_demo3"/></a> + <a href="examples/pylab_examples/pythonic_matplotlib.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/pythonic_matplotlib.png" border="0" alt="pythonic_matplotlib"/></a> <a href="examples/pylab_examples/quadmesh_demo.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/quadmesh_demo.png" border="0" alt="quadmesh_demo"/></a> Modified: trunk/matplotlib/doc/matplotlibrc =================================================================== --- trunk/matplotlib/doc/matplotlibrc 2008-12-10 04:05:18 UTC (rev 6539) +++ trunk/matplotlib/doc/matplotlibrc 2008-12-10 04:11:56 UTC (rev 6540) @@ -295,7 +295,7 @@ #svg.embed_chars : True # embed character outlines in the SVG file # docstring params -docstring.hardcopy = True # set this when you want to generate hardcopy docstring +docstring.hardcopy : True # set this when you want to generate hardcopy docstring # Set the verbose flags. This controls how much information # matplotlib gives you at runtime and where it goes. The verbosity This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <ds...@us...> - 2008-12-12 14:47:45
|
Revision: 6591 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=6591&view=rev Author: dsdale Date: 2008-12-12 14:47:38 +0000 (Fri, 12 Dec 2008) Log Message: ----------- added note to api_changes.rst about removing configobj and traits Modified Paths: -------------- trunk/matplotlib/doc/api/api_changes.rst trunk/matplotlib/doc/pyplots/tex_demo.png Modified: trunk/matplotlib/doc/api/api_changes.rst =================================================================== --- trunk/matplotlib/doc/api/api_changes.rst 2008-12-12 14:05:20 UTC (rev 6590) +++ trunk/matplotlib/doc/api/api_changes.rst 2008-12-12 14:47:38 UTC (rev 6591) @@ -6,6 +6,13 @@ outward-facing API. If updating matplotlib breaks your scripts, this list may help describe what changes may be necessary in your code. +* Removed configobj_ and `enthought.traits`_ packages, which are only + required by the experimental traited config and are somewhat out of + date. If needed, install them independently. + +.. _configobj: http://www.voidspace.org.uk/python/configobj.html +.. _`enthought.traits`: http://code.enthought.com/projects/traits + Changes for 0.98.x ================== @@ -253,7 +260,7 @@ `Axes.toggle_log_lineary()` has been removed. :mod:`matplotlib.artist` -~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~ ============================================================ ============================================================ Old method New method Modified: trunk/matplotlib/doc/pyplots/tex_demo.png =================================================================== (Binary files differ) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jd...@us...> - 2008-12-15 03:22:24
|
Revision: 6605 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=6605&view=rev Author: jdh2358 Date: 2008-12-15 03:22:17 +0000 (Mon, 15 Dec 2008) Log Message: ----------- fixed a few doc bugs Modified Paths: -------------- trunk/matplotlib/doc/_templates/gallery.html trunk/matplotlib/doc/_templates/indexsidebar.html trunk/matplotlib/doc/users/intro.rst Modified: trunk/matplotlib/doc/_templates/gallery.html =================================================================== --- trunk/matplotlib/doc/_templates/gallery.html 2008-12-14 17:16:38 UTC (rev 6604) +++ trunk/matplotlib/doc/_templates/gallery.html 2008-12-15 03:22:17 UTC (rev 6605) @@ -169,6 +169,8 @@ <a href="examples/pylab_examples/customize_rc.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/customize_rc.png" border="0" alt="customize_rc"/></a> +<a href="examples/pylab_examples/dannys_example.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/dannys_example.png" border="0" alt="dannys_example"/></a> + <a href="examples/pylab_examples/dash_control.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/dash_control.png" border="0" alt="dash_control"/></a> <a href="examples/pylab_examples/dashpointlabel.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/dashpointlabel.png" border="0" alt="dashpointlabel"/></a> @@ -475,6 +477,8 @@ <a href="examples/pylab_examples/step_demo.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/step_demo.png" border="0" alt="step_demo"/></a> +<a href="examples/pylab_examples/stix_fonts_demo.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/stix_fonts_demo.png" border="0" alt="stix_fonts_demo"/></a> + <a href="examples/pylab_examples/subplot_demo.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/subplot_demo.png" border="0" alt="subplot_demo"/></a> <a href="examples/pylab_examples/subplot_toolbar.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/subplot_toolbar_00.png" border="0" alt="subplot_toolbar"/></a> @@ -487,6 +491,8 @@ <a href="examples/pylab_examples/table_demo.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/table_demo.png" border="0" alt="table_demo"/></a> +<a href="examples/pylab_examples/tex_demo.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/tex_demo.png" border="0" alt="tex_demo"/></a> + <a href="examples/pylab_examples/text_handles.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/text_handles.png" border="0" alt="text_handles"/></a> <a href="examples/pylab_examples/text_rotation.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/text_rotation.png" border="0" alt="text_rotation"/></a> @@ -503,6 +509,8 @@ <a href="examples/pylab_examples/unicode_demo.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/unicode_demo.png" border="0" alt="unicode_demo"/></a> +<a href="examples/pylab_examples/usetex_demo.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/usetex_demo.png" border="0" alt="usetex_demo"/></a> + <a href="examples/pylab_examples/vertical_ticklabels.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/vertical_ticklabels.png" border="0" alt="vertical_ticklabels"/></a> <a href="examples/pylab_examples/vline_demo.html"><img src="_static/plot_directive/mpl_examples/pylab_examples/thumbnails/vline_demo.png" border="0" alt="vline_demo"/></a> Modified: trunk/matplotlib/doc/_templates/indexsidebar.html =================================================================== --- trunk/matplotlib/doc/_templates/indexsidebar.html 2008-12-14 17:16:38 UTC (rev 6604) +++ trunk/matplotlib/doc/_templates/indexsidebar.html 2008-12-15 03:22:17 UTC (rev 6605) @@ -1,11 +1,11 @@ <h3>Download</h3> <p>Current version: <b>{{ version }}</b></p> -<p>Download matplotlib from the sourceforge <a -href="http://sourceforge.net/projects/matplotlib">project</a> page -(but first take a look at the <a href="{{ pathto('users/installing') -}}">installing</a> page). Here's a summary of <a href="{{ -pathto('users/whats_new') }}">what's new</a>. </p> +<p>Download matplotlib from the +sourceforge <a href="http://sourceforge.net/projects/matplotlib">project</a> +page (but first take a look at the <a href="{{ +pathto('users/installing') }}">installing</a> page). Here's a summary +of <a href="{{ pathto('users/whats_new') }}">what's new</a>. </p> <p>There are several matplotlib addon <a href="{{ pathto('users/toolkits') }}">toolkits</a>, including the projection Modified: trunk/matplotlib/doc/users/intro.rst =================================================================== --- trunk/matplotlib/doc/users/intro.rst 2008-12-14 17:16:38 UTC (rev 6604) +++ trunk/matplotlib/doc/users/intro.rst 2008-12-15 03:22:17 UTC (rev 6605) @@ -2,11 +2,11 @@ ============ matplotlib is a library for making 2D plots of arrays in `Python -<http://www.python.org>`. Although it has its origins in emulating -the `MATLAB™ <http://www.mathworks.com>` graphics commands, it is +<http://www.python.org>`_. Although it has its origins in emulating +the `MATLAB™ <http://www.mathworks.com>`_ graphics commands, it is independent of MATLAB, and can be used in a Pythonic, object oriented way. Although matplotlib is written primarily in pure Python, it -makes heavy use of `NumPy <http://www.numpy.org>` and other extension +makes heavy use of `NumPy <http://www.numpy.org>`_ and other extension code to provide good performance even for large arrays. matplotlib is designed with the philosophy that you should be able to @@ -25,7 +25,7 @@ programming language, and decided to start over in Python. Python more than makes up for all of MATLAB's deficiencies as a programming language, but I was having difficulty finding a 2D plotting package -(for 3D `VTK <http://www.vtk.org/>` more than exceeds all of my +(for 3D `VTK <http://www.vtk.org/>`_ more than exceeds all of my needs). When I went searching for a Python plotting package, I had several @@ -67,16 +67,16 @@ devices, aka renderers, that transform the frontend representation to hardcopy or a display device (:ref:`what-is-a-backend`). Example backends: PS creates `PostScript® -<http://http://www.adobe.com/products/postscript/>` hardcopy, SVG -creates `Scalable Vector Graphics <http://www.w3.org/Graphics/SVG/>` +<http://http://www.adobe.com/products/postscript/>`_ hardcopy, SVG +creates `Scalable Vector Graphics <http://www.w3.org/Graphics/SVG/>`_ hardcopy, Agg creates PNG output using the high quality `Anti-Grain -Geometry <http://www.antigrain.com>` library that ships with -matplotlib, GTK embeds matplotlib in a `Gtk+ <http://www.gtk.org/>` +Geometry <http://www.antigrain.com>`_ library that ships with +matplotlib, GTK embeds matplotlib in a `Gtk+ <http://www.gtk.org/>`_ application, GTKAgg uses the Anti-Grain renderer to create a figure and embed it a Gtk+ application, and so on for `PDF -<http://www.adobe.com/products/acrobat/adobepdf.html>`, `WxWidgets -<http://www.wxpython.org/>`, `Tkinter -<http://docs.python.org/lib/module-Tkinter.html>` etc. +<http://www.adobe.com/products/acrobat/adobepdf.html>`_, `WxWidgets +<http://www.wxpython.org/>`_, `Tkinter +<http://docs.python.org/lib/module-Tkinter.html>`_ etc. matplotlib is used by many people in many different contexts. Some people want to automatically generate PostScript files to send This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <ef...@us...> - 2010-06-26 07:45:33
|
Revision: 8468 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=8468&view=rev Author: efiring Date: 2010-06-26 07:45:26 +0000 (Sat, 26 Jun 2010) Log Message: ----------- docs: be consistent in referring to MATLAB. For the legal rationale, see Joe Harrington's post to scipy-dev: http://article.gmane.org/gmane.comp.python.scientific.user/25399/match=matlab+trademark Modified Paths: -------------- trunk/matplotlib/doc/_templates/index.html trunk/matplotlib/doc/api/api_changes.rst trunk/matplotlib/doc/faq/usage_faq.rst trunk/matplotlib/doc/users/artists.rst trunk/matplotlib/doc/users/installing.rst trunk/matplotlib/doc/users/intro.rst trunk/matplotlib/doc/users/pyplot_tutorial.rst trunk/matplotlib/doc/users/screenshots.rst trunk/matplotlib/doc/users/whats_new.rst Modified: trunk/matplotlib/doc/_templates/index.html =================================================================== --- trunk/matplotlib/doc/_templates/index.html 2010-06-26 07:37:44 UTC (rev 8467) +++ trunk/matplotlib/doc/_templates/index.html 2010-06-26 07:45:26 UTC (rev 8468) @@ -9,10 +9,19 @@ publication quality figures in a variety of hardcopy formats and interactive environments across platforms. matplotlib can be used in python scripts, the python and <a - href="http://ipython.scipy.org">ipython</a> shell (ala matlab or - mathematica), web application servers, and six graphical user + href="http://ipython.scipy.org">ipython</a> shell (ala + MATLAB<sup>®<a name="matlab" href="#ftn.matlab">*</a></sup> + or + Mathematica<sup>®<a name="mathematica" + href="#ftn.mathematica">†</a></sup>), + web application servers, and six graphical user interface toolkits.</p> + + + + + <p>matplotlib tries to make easy things easy and hard things possible. You can generate plots, histograms, power spectra, bar charts, errorcharts, scatterplots, etc, with just a few lines of code. @@ -35,7 +44,7 @@ <p>For the power user, you have full control of line styles, font properties, axes properties, etc, via an object oriented interface - or via a set of functions familiar to Matlab® users. + or via a set of functions familiar to MATLAB users. The pylab mode provides all of the <a href="api/pyplot_api.html">pyplot</a> plotting functions listed below, as well as non-plotting functions from <a href="http://scipy.org/Numpy_Example_List_With_Doc">numpy</a> and @@ -1193,4 +1202,16 @@ </tr> </table> + +<div class="footnote"><p> +<sup><a name="ftn.matlab" href="#matlab">*</a></sup> +MATLAB is a registered trademark of The MathWorks, Inc. +</p> +<p> +<sup><a name="ftn.mathematica" href="#mathematica">†</a></sup> +Mathematica is a registered trademark of Wolfram Research, Inc. +</p> + + + {% endblock %} Modified: trunk/matplotlib/doc/api/api_changes.rst =================================================================== --- trunk/matplotlib/doc/api/api_changes.rst 2010-06-26 07:37:44 UTC (rev 8467) +++ trunk/matplotlib/doc/api/api_changes.rst 2010-06-26 07:45:26 UTC (rev 8468) @@ -179,7 +179,7 @@ to scale one-sided densities by a factor of 2. Also, optionally scale the densities by the sampling frequency, which gives true values of densities that can be integrated by the returned frequency values. - This also gives better MatLab compatibility. The corresponding + This also gives better MATLAB compatibility. The corresponding :class:`matplotlib.axes.Axes` methods and :mod:`matplotlib.pyplot` functions were updated as well. @@ -1094,7 +1094,7 @@ - pylab figure now defaults to num=None, which creates a new figure with a guaranteed unique number - - contour method syntax changed - now it is matlab compatible + - contour method syntax changed - now it is MATLAB compatible unchanged: contour(Z) old: contour(Z, x=Y, y=Y) @@ -1183,7 +1183,7 @@ :: - mpl_connect and mpl_disconnect in the matlab interface renamed to + mpl_connect and mpl_disconnect in the MATLAB interface renamed to connect and disconnect Did away with the text methods for angle since they were ambiguous. @@ -1272,7 +1272,7 @@ Changes for 0.54 ================ -matlab interface +MATLAB interface ---------------- dpi @@ -1289,7 +1289,7 @@ pcolor and scatter ~~~~~~~~~~~~~~~~~~ -There are two changes to the matlab interface API, both involving the +There are two changes to the MATLAB interface API, both involving the patch drawing commands. For efficiency, pcolor and scatter have been rewritten to use polygon collections, which are a new set of objects from matplotlib.collections designed to enable efficient handling of @@ -1323,7 +1323,7 @@ for a discussion on how to set the properties as a sequence. For scatter, the size argument is now in points^2 (the area of the -symbol in points) as in matlab and is not in data coords as before. +symbol in points) as in MATLAB and is not in data coords as before. Using sizes in data coords caused several problems. So you will need to adjust your size arguments accordingly or use scatter_classic. @@ -1491,7 +1491,7 @@ * backends must implement FigureCanvasBackend (the thing that controls the figure and handles the events if any) and - FigureManagerBackend (wraps the canvas and the window for matlab + FigureManagerBackend (wraps the canvas and the window for MATLAB interface). FigureCanvasBase implements a backend switching mechanism @@ -1514,9 +1514,9 @@ Migrating code: - Matlab interface: + MATLAB interface: - The only API change for those using the matlab interface is in how + The only API change for those using the MATLAB interface is in how you call figure redraws for dynamically updating figures. In the old API, you did @@ -1653,7 +1653,7 @@ - new module transforms supplies Bound1D, Bound2D and Transform instances and more - - Changes to the matlab helpers API + - Changes to the MATLAB helpers API * _matlab_helpers.GcfBase is renamed by Gcf. Backends no longer need to derive from this class. Instead, they provide a factory Modified: trunk/matplotlib/doc/faq/usage_faq.rst =================================================================== --- trunk/matplotlib/doc/faq/usage_faq.rst 2010-06-26 07:37:44 UTC (rev 8467) +++ trunk/matplotlib/doc/faq/usage_faq.rst 2010-06-26 07:45:26 UTC (rev 8468) @@ -17,19 +17,19 @@ installed alongside :mod:`matplotlib`; and :mod:`matplotlib.pyplot` is a module in matplotlib. -Pyplot provides a Matlab-style state-machine interface to +Pyplot provides a MATLAB-style state-machine interface to the underlying object-oriented plotting library in matplotlib. Pylab combines the pyplot functionality (for plotting) with the numpy functionality (for mathematics and for working with arrays) in a single namespace, making that namespace -(or environment) even more Matlab-like. This is what you get if +(or environment) even more MATLAB-like. This is what you get if you use the *ipython* shell with the *-pylab* option, which imports everything from pylab and makes plotting fully interactive. We have been gradually converting the matplotlib examples -from pure Matlab-style, using "from pylab import \*", to a preferred +from pure MATLAB-style, using "from pylab import \*", to a preferred style in which pyplot is used for some convenience functions, either pyplot or the object-oriented style is used for the remainder of the plotting code, and numpy is used explicitly for numeric array operations. @@ -42,7 +42,7 @@ Then one calls, for example, np.arange, np.zeros, np.pi, plt.figure, plt.plot, plt.show, etc. -Example, pure Matlab-style:: +Example, pure MATLAB-style:: from pylab import * x = arange(0, 10, 0.2) @@ -71,7 +71,7 @@ plt.show() So, why do all the extra typing required as one moves away from the pure -matlab-style? For very simple things like this example, the only +MATLAB-style? For very simple things like this example, the only advantage is educational: the wordier styles are more explicit, more clear as to where things come from and what is going on. For more complicated applications, the explicitness and clarity become Modified: trunk/matplotlib/doc/users/artists.rst =================================================================== --- trunk/matplotlib/doc/users/artists.rst 2010-06-26 07:37:44 UTC (rev 8467) +++ trunk/matplotlib/doc/users/artists.rst 2010-06-26 07:45:26 UTC (rev 8468) @@ -1,610 +1,611 @@ -.. _artist-tutorial: - -*************** -Artist tutorial -*************** - -There are three layers to the matplotlib API. The -:class:`matplotlib.backend_bases.FigureCanvas` is the area onto which -the figure is drawn, the :class:`matplotlib.backend_bases.Renderer` is -the object which knows how to draw on the -:class:`~matplotlib.backend_bases.FigureCanvas`, and the -:class:`matplotlib.artist.Artist` is the object that knows how to use -a renderer to paint onto the canvas. The -:class:`~matplotlib.backend_bases.FigureCanvas` and -:class:`~matplotlib.backend_bases.Renderer` handle all the details of -talking to user interface toolkits like `wxPython -<http://www.wxpython.org>`_ or drawing languages like PostScript®, and -the ``Artist`` handles all the high level constructs like representing -and laying out the figure, text, and lines. The typical user will -spend 95% of his time working with the ``Artists``. - -There are two types of ``Artists``: primitives and containers. The primitives represent the standard graphical objects we want to paint onto our canvas: :class:`~matplotlib.lines.Line2D`, :class:`~matplotlib.patches.Rectangle`, :class:`~matplotlib.text.Text`, :class:`~matplotlib.image.AxesImage`, etc., and the containers are places to put them (:class:`~matplotlib.axis.Axis`, :class:`~matplotlib.axes.Axes` and :class:`~matplotlib.figure.Figure`). The standard use is to create a :class:`~matplotlib.figure.Figure` instance, use the ``Figure`` to create one or more :class:`~matplotlib.axes.Axes` or :class:`~matplotlib.axes.Subplot` instances, and use the ``Axes`` instance helper methods to create the primitives. In the example below, we create a ``Figure`` instance using :func:`matplotlib.pyplot.figure`, which is a convenience method for instantiating ``Figure`` instances and connecting them with your user interface or drawing toolkit ``FigureCanvas``. As we will discuss below, this is not necessary -- you can work directly with PostScript, PDF Gtk+, or wxPython ``FigureCanvas`` instances, instantiate your ``Figures`` directly and connect them yourselves -- but since we are focusing here on the ``Artist`` API we'll let :mod:`~matplotlib.pyplot` handle some of those details for us:: - - import matplotlib.pyplot as plt - fig = plt.figure() - ax = fig.add_subplot(2,1,1) # two rows, one column, first plot - -The :class:`~matplotlib.axes.Axes` is probably the most important -class in the matplotlib API, and the one you will be working with most -of the time. This is because the ``Axes`` is the plotting area into -which most of the objects go, and the ``Axes`` has many special helper -methods (:meth:`~matplotlib.axes.Axes.plot`, -:meth:`~matplotlib.axes.Axes.text`, -:meth:`~matplotlib.axes.Axes.hist`, -:meth:`~matplotlib.axes.Axes.imshow`) to create the most common -graphics primitives (:class:`~matplotlib.lines.Line2D`, -:class:`~matplotlib.text.Text`, -:class:`~matplotlib.patches.Rectangle`, -:class:`~matplotlib.image.Image`, respectively). These helper methods -will take your data (eg. ``numpy`` arrays and strings) and create -primitive ``Artist`` instances as needed (eg. ``Line2D``), add them to -the relevant containers, and draw them when requested. Most of you -are probably familiar with the :class:`~matplotlib.axes.Subplot`, -which is just a special case of an ``Axes`` that lives on a regular -rows by columns grid of ``Subplot`` instances. If you want to create -an ``Axes`` at an arbitrary location, simply use the -:meth:`~matplotlib.figure.Figure.add_axes` method which takes a list -of ``[left, bottom, width, height]`` values in 0-1 relative figure -coordinates:: - - fig2 = plt.figure() - ax2 = fig2.add_axes([0.15, 0.1, 0.7, 0.3]) - -Continuing with our example:: - - import numpy as np - t = np.arange(0.0, 1.0, 0.01) - s = np.sin(2*np.pi*t) - line, = ax.plot(t, s, color='blue', lw=2) - -In this example, ``ax`` is the ``Axes`` instance created by the -``fig.add_subplot`` call above (remember ``Subplot`` is just a -subclass of ``Axes``) and when you call ``ax.plot``, it creates a -``Line2D`` instance and adds it to the :attr:`Axes.lines -<matplotlib.axes.Axes.lines>` list. In the interactive `ipython -<http://ipython.scipy.org/>`_ session below, you can see that the -``Axes.lines`` list is length one and contains the same line that was -returned by the ``line, = ax.plot...`` call: - -.. sourcecode:: ipython - - In [101]: ax.lines[0] - Out[101]: <matplotlib.lines.Line2D instance at 0x19a95710> - - In [102]: line - Out[102]: <matplotlib.lines.Line2D instance at 0x19a95710> - -If you make subsequent calls to ``ax.plot`` (and the hold state is "on" -which is the default) then additional lines will be added to the list. -You can remove lines later simply by calling the list methods; either -of these will work:: - - del ax.lines[0] - ax.lines.remove(line) # one or the other, not both! - -The Axes also has helper methods to configure and decorate the x-axis -and y-axis tick, tick labels and axis labels:: - - xtext = ax.set_xlabel('my xdata') # returns a Text instance - ytext = ax.set_ylabel('my xdata') - -When you call :meth:`ax.set_xlabel <matplotlib.axes.Axes.set_xlabel>`, -it passes the information on the :class:`~matplotlib.text.Text` -instance of the :class:`~matplotlib.axis.XAxis`. Each ``Axes`` -instance contains an :class:`~matplotlib.axis.XAxis` and a -:class:`~matplotlib.axis.YAxis` instance, which handle the layout and -drawing of the ticks, tick labels and axis labels. - -.. I'm commenting this out, since the new Sphinx cross-references -.. sort of take care of this above - MGD - -.. Here are the most important matplotlib modules that contain the -.. classes referenced above - -.. =============== ================== -.. Artist Module -.. =============== ================== -.. Artist matplotlib.artist -.. Rectangle matplotlib.patches -.. Line2D matplotlib.lines -.. Axes matplotlib.axes -.. XAxis and YAxis matplotlib.axis -.. Figure matplotlib.figure -.. Text matplotlib.text -.. =============== ================== - -Try creating the figure below. - -.. plot:: pyplots/fig_axes_labels_simple.py - -.. _customizing-artists: - -Customizing your objects -======================== - -Every element in the figure is represented by a matplotlib -:class:`~matplotlib.artist.Artist`, and each has an extensive list of -properties to configure its appearance. The figure itself contains a -:class:`~matplotlib.patches.Rectangle` exactly the size of the figure, -which you can use to set the background color and transparency of the -figures. Likewise, each :class:`~matplotlib.axes.Axes` bounding box -(the standard white box with black edges in the typical matplotlib -plot, has a ``Rectangle`` instance that determines the color, -transparency, and other properties of the Axes. These instances are -stored as member variables :attr:`Figure.patch -<matplotlib.figure.Figure.patch>` and :attr:`Axes.patch -<matplotlib.axes.Axes.patch>` ("Patch" is a name inherited from -MATLAB™, and is a 2D "patch" of color on the figure, eg. rectangles, -circles and polygons). Every matplotlib ``Artist`` has the following -properties - -========== ====================================================================== -Property Description -========== ====================================================================== -alpha The transparency - a scalar from 0-1 -animated A boolean that is used to facilitate animated drawing -axes The axes that the Artist lives in, possibly None -clip_box The bounding box that clips the Artist -clip_on Whether clipping is enabled -clip_path The path the artist is clipped to -contains A picking function to test whether the artist contains the pick point -figure The figure instance the artist lives in, possibly None -label A text label (eg. for auto-labeling) -picker A python object that controls object picking -transform The transformation -visible A boolean whether the artist should be drawn -zorder A number which determines the drawing order -========== ====================================================================== - -Each of the properties is accessed with an old-fashioned setter or -getter (yes we know this irritates Pythonistas and we plan to support -direct access via properties or traits but it hasn't been done yet). -For example, to multiply the current alpha by a half:: - - a = o.get_alpha() - o.set_alpha(0.5*a) - -If you want to set a number of properties at once, you can also use -the ``set`` method with keyword arguments. For example:: - - o.set(alpha=0.5, zorder=2) - -If you are working interactively at the python shell, a handy way to -inspect the ``Artist`` properties is to use the -:func:`matplotlib.artist.getp` function (simply -:func:`~matplotlib.pylab.getp` in pylab), which lists the properties -and their values. This works for classes derived from ``Artist`` as -well, eg. ``Figure`` and ``Rectangle``. Here are the ``Figure`` rectangle -properties mentioned above: - -.. sourcecode:: ipython - - In [149]: matplotlib.artist.getp(fig.patch) - alpha = 1.0 - animated = False - antialiased or aa = True - axes = None - clip_box = None - clip_on = False - clip_path = None - contains = None - edgecolor or ec = w - facecolor or fc = 0.75 - figure = Figure(8.125x6.125) - fill = 1 - hatch = None - height = 1 - label = - linewidth or lw = 1.0 - picker = None - transform = <Affine object at 0x134cca84> - verts = ((0, 0), (0, 1), (1, 1), (1, 0)) - visible = True - width = 1 - window_extent = <Bbox object at 0x134acbcc> - x = 0 - y = 0 - zorder = 1 - -.. TODO: Update these URLs - -The docstrings for all of the classes also contain the ``Artist`` -properties, so you can consult the interactive "help" or the -:ref:`artist-api` for a listing of properties for a given object. - -.. _object-containers: - -Object containers -================= - - -Now that we know how to inspect and set the properties of a given -object we want to configure, we need to now how to get at that object. -As mentioned in the introduction, there are two kinds of objects: -primitives and containers. The primitives are usually the things you -want to configure (the font of a :class:`~matplotlib.text.Text` -instance, the width of a :class:`~matplotlib.lines.Line2D`) although -the containers also have some properties as well -- for example the -:class:`~matplotlib.axes.Axes` :class:`~matplotlib.artist.Artist` is a -container that contains many of the primitives in your plot, but it -also has properties like the ``xscale`` to control whether the xaxis -is 'linear' or 'log'. In this section we'll review where the various -container objects store the ``Artists`` that you want to get at. - -.. _figure-container: - -Figure container -================ - -The top level container ``Artist`` is the -:class:`matplotlib.figure.Figure`, and it contains everything in the -figure. The background of the figure is a -:class:`~matplotlib.patches.Rectangle` which is stored in -:attr:`Figure.patch <matplotlib.figure.Figure.patch>`. As -you add subplots (:meth:`~matplotlib.figure.Figure.add_subplot`) and -axes (:meth:`~matplotlib.figure.Figure.add_axes`) to the figure -these will be appended to the :attr:`Figure.axes -<matplotlib.figure.Figure.axes>`. These are also returned by the -methods that create them: - -.. sourcecode:: ipython - - In [156]: fig = plt.figure() - - In [157]: ax1 = fig.add_subplot(211) - - In [158]: ax2 = fig.add_axes([0.1, 0.1, 0.7, 0.3]) - - In [159]: ax1 - Out[159]: <matplotlib.axes.Subplot instance at 0xd54b26c> - - In [160]: print fig.axes - [<matplotlib.axes.Subplot instance at 0xd54b26c>, <matplotlib.axes.Axes instance at 0xd3f0b2c>] - -Because the figure maintains the concept of the "current axes" (see -:meth:`Figure.gca <matplotlib.figure.Figure.gca>` and -:meth:`Figure.sca <matplotlib.figure.Figure.sca>`) to support the -pylab/pyplot state machine, you should not insert or remove axes -directly from the axes list, but rather use the -:meth:`~matplotlib.figure.Figure.add_subplot` and -:meth:`~matplotlib.figure.Figure.add_axes` methods to insert, and the -:meth:`~matplotlib.figure.Figure.delaxes` method to delete. You are -free however, to iterate over the list of axes or index into it to get -access to ``Axes`` instances you want to customize. Here is an -example which turns all the axes grids on:: - - for ax in fig.axes: - ax.grid(True) - - -The figure also has its own text, lines, patches and images, which you -can use to add primitives directly. The default coordinate system for -the ``Figure`` will simply be in pixels (which is not usually what you -want) but you can control this by setting the transform property of -the ``Artist`` you are adding to the figure. - -.. TODO: Is that still true? - -More useful is "figure coordinates" where (0, 0) is the bottom-left of -the figure and (1, 1) is the top-right of the figure which you can -obtain by setting the ``Artist`` transform to :attr:`fig.transFigure -<matplotlib.figure.Figure.transFigure>`: - -.. sourcecode:: ipython - - In [191]: fig = plt.figure() - - In [192]: l1 = matplotlib.lines.Line2D([0, 1], [0, 1], - transform=fig.transFigure, figure=fig) - - In [193]: l2 = matplotlib.lines.Line2D([0, 1], [1, 0], - transform=fig.transFigure, figure=fig) - - In [194]: fig.lines.extend([l1, l2]) - - In [195]: fig.canvas.draw() - -.. plot:: pyplots/fig_x.py - - -Here is a summary of the Artists the figure contains - -.. TODO: Add xrefs to this table - -================ =============================================================== -Figure attribute Description -================ =============================================================== -axes A list of Axes instances (includes Subplot) -patch The Rectangle background -images A list of FigureImages patches - useful for raw pixel display -legends A list of Figure Legend instances (different from Axes.legends) -lines A list of Figure Line2D instances (rarely used, see Axes.lines) -patches A list of Figure patches (rarely used, see Axes.patches) -texts A list Figure Text instances -================ =============================================================== - -.. _axes-container: - -Axes container -============== - -The :class:`matplotlib.axes.Axes` is the center of the matplotlib -universe -- it contains the vast majority of all the ``Artists`` used -in a figure with many helper methods to create and add these -``Artists`` to itself, as well as helper methods to access and -customize the ``Artists`` it contains. Like the -:class:`~matplotlib.figure.Figure`, it contains a -:class:`~matplotlib.patches.Patch` -:attr:`~matplotlib.axes.Axes.patch` which is a -:class:`~matplotlib.patches.Rectangle` for Cartesian coordinates and a -:class:`~matplotlib.patches.Circle` for polar coordinates; this patch -determines the shape, background and border of the plotting region:: - - ax = fig.add_subplot(111) - rect = ax.patch # a Rectangle instance - rect.set_facecolor('green') - -When you call a plotting method, eg. the canonical -:meth:`~matplotlib.axes.Axes.plot` and pass in arrays or lists of -values, the method will create a :meth:`matplotlib.lines.Line2D` -instance, update the line with all the ``Line2D`` properties passed as -keyword arguments, add the line to the :attr:`Axes.lines -<matplotlib.axes.Axes.lines>` container, and returns it to you: - -.. sourcecode:: ipython - - In [213]: x, y = np.random.rand(2, 100) - - In [214]: line, = ax.plot(x, y, '-', color='blue', linewidth=2) - -``plot`` returns a list of lines because you can pass in multiple x, y -pairs to plot, and we are unpacking the first element of the length -one list into the line variable. The line has been added to the -``Axes.lines`` list: - -.. sourcecode:: ipython - - In [229]: print ax.lines - [<matplotlib.lines.Line2D instance at 0xd378b0c>] - -Similarly, methods that create patches, like -:meth:`~matplotlib.axes.Axes.bar` creates a list of rectangles, will -add the patches to the :attr:`Axes.patches -<matplotlib.axes.Axes.patches>` list: - -.. sourcecode:: ipython - - In [233]: n, bins, rectangles = ax.hist(np.random.randn(1000), 50, facecolor='yellow') - - In [234]: rectangles - Out[234]: <a list of 50 Patch objects> - - In [235]: print len(ax.patches) - -You should not add objects directly to the ``Axes.lines`` or -``Axes.patches`` lists unless you know exactly what you are doing, -because the ``Axes`` needs to do a few things when it creates and adds -an object. It sets the figure and axes property of the ``Artist``, as -well as the default ``Axes`` transformation (unless a transformation -is set). It also inspects the data contained in the ``Artist`` to -update the data structures controlling auto-scaling, so that the view -limits can be adjusted to contain the plotted data. You can, -nonetheless, create objects yourself and add them directly to the -``Axes`` using helper methods like -:meth:`~matplotlib.axes.Axes.add_line` and -:meth:`~matplotlib.axes.Axes.add_patch`. Here is an annotated -interactive session illustrating what is going on: - -.. sourcecode:: ipython - - In [261]: fig = plt.figure() - - In [262]: ax = fig.add_subplot(111) - - # create a rectangle instance - In [263]: rect = matplotlib.patches.Rectangle( (1,1), width=5, height=12) - - # by default the axes instance is None - In [264]: print rect.get_axes() - None - - # and the transformation instance is set to the "identity transform" - In [265]: print rect.get_transform() - <Affine object at 0x13695544> - - # now we add the Rectangle to the Axes - In [266]: ax.add_patch(rect) - - # and notice that the ax.add_patch method has set the axes - # instance - In [267]: print rect.get_axes() - Axes(0.125,0.1;0.775x0.8) - - # and the transformation has been set too - In [268]: print rect.get_transform() - <Affine object at 0x15009ca4> - - # the default axes transformation is ax.transData - In [269]: print ax.transData - <Affine object at 0x15009ca4> - - # notice that the xlimits of the Axes have not been changed - In [270]: print ax.get_xlim() - (0.0, 1.0) - - # but the data limits have been updated to encompass the rectangle - In [271]: print ax.dataLim.bounds - (1.0, 1.0, 5.0, 12.0) - - # we can manually invoke the auto-scaling machinery - In [272]: ax.autoscale_view() - - # and now the xlim are updated to encompass the rectangle - In [273]: print ax.get_xlim() - (1.0, 6.0) - - # we have to manually force a figure draw - In [274]: ax.figure.canvas.draw() - - -There are many, many ``Axes`` helper methods for creating primitive -``Artists`` and adding them to their respective containers. The table -below summarizes a small sampling of them, the kinds of ``Artist`` they -create, and where they store them - -============================== ==================== ======================= -Helper method Artist Container -============================== ==================== ======================= -ax.annotate - text annotations Annotate ax.texts -ax.bar - bar charts Rectangle ax.patches -ax.errorbar - error bar plots Line2D and Rectangle ax.lines and ax.patches -ax.fill - shared area Polygon ax.patches -ax.hist - histograms Rectangle ax.patches -ax.imshow - image data AxesImage ax.images -ax.legend - axes legends Legend ax.legends -ax.plot - xy plots Line2D ax.lines -ax.scatter - scatter charts PolygonCollection ax.collections -ax.text - text Text ax.texts -============================== ==================== ======================= - - -In addition to all of these ``Artists``, the ``Axes`` contains two -important ``Artist`` containers: the :class:`~matplotlib.axis.XAxis` -and :class:`~matplotlib.axis.YAxis`, which handle the drawing of the -ticks and labels. These are stored as instance variables -:attr:`~matplotlib.axes.Axes.xaxis` and -:attr:`~matplotlib.axes.Axes.yaxis`. The ``XAxis`` and ``YAxis`` -containers will be detailed below, but note that the ``Axes`` contains -many helper methods which forward calls on to the -:class:`~matplotlib.axis.Axis` instances so you often do not need to -work with them directly unless you want to. For example, you can set -the font size of the ``XAxis`` ticklabels using the ``Axes`` helper -method:: - - for label in ax.get_xticklabels(): - label.set_color('orange') - -Below is a summary of the Artists that the Axes contains - -============== ====================================== -Axes attribute Description -============== ====================================== -artists A list of Artist instances -patch Rectangle instance for Axes background -collections A list of Collection instances -images A list of AxesImage -legends A list of Legend instances -lines A list of Line2D instances -patches A list of Patch instances -texts A list of Text instances -xaxis matplotlib.axis.XAxis instance -yaxis matplotlib.axis.YAxis instance -============== ====================================== - -.. _axis-container: - -Axis containers -=============== - -The :class:`matplotlib.axis.Axis` instances handle the drawing of the -tick lines, the grid lines, the tick labels and the axis label. You -can configure the left and right ticks separately for the y-axis, and -the upper and lower ticks separately for the x-axis. The ``Axis`` -also stores the data and view intervals used in auto-scaling, panning -and zooming, as well as the :class:`~matplotlib.ticker.Locator` and -:class:`~matplotlib.ticker.Formatter` instances which control where -the ticks are placed and how they are represented as strings. - -Each ``Axis`` object contains a :attr:`~matplotlib.axis.Axis.label` attribute (this is what :mod:`~matplotlib.pylab` modifies in calls to :func:`~matplotlib.pylab.xlabel` and :func:`~matplotlib.pylab.ylabel`) as well as a list of major and minor ticks. The ticks are :class:`~matplotlib.axis.XTick` and :class:`~matplotlib.axis.YTick` instances, which contain the actual line and text primitives that render the ticks and ticklabels. Because the ticks are dynamically created as needed (eg. when panning and zooming), you should access the lists of major and minor ticks through their accessor methods :meth:`~matplotlib.axis.Axis.get_major_ticks` and :meth:`~matplotlib.axis.Axis.get_minor_ticks`. Although the ticks contain all the primitives and will be covered below, the ``Axis`` methods contain accessor methods to return the tick lines, tick labels, tick locations etc.: - -.. sourcecode:: ipython - - In [285]: axis = ax.xaxis - - In [286]: axis.get_ticklocs() - Out[286]: array([ 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.]) - - In [287]: axis.get_ticklabels() - Out[287]: <a list of 10 Text major ticklabel objects> - - # note there are twice as many ticklines as labels because by - # default there are tick lines at the top and bottom but only tick - # labels below the xaxis; this can be customized - In [288]: axis.get_ticklines() - Out[288]: <a list of 20 Line2D ticklines objects> - - # by default you get the major ticks back - In [291]: axis.get_ticklines() - Out[291]: <a list of 20 Line2D ticklines objects> - - # but you can also ask for the minor ticks - In [292]: axis.get_ticklines(minor=True) - Out[292]: <a list of 0 Line2D ticklines objects> - -Here is a summary of some of the useful accessor methods of the ``Axis`` -(these have corresponding setters where useful, such as -set_major_formatter) - -====================== ========================================================= -Accessor method Description -====================== ========================================================= -get_scale The scale of the axis, eg 'log' or 'linear' -get_view_interval The interval instance of the axis view limits -get_data_interval The interval instance of the axis data limits -get_gridlines A list of grid lines for the Axis -get_label The axis label - a Text instance -get_ticklabels A list of Text instances - keyword minor=True|False -get_ticklines A list of Line2D instances - keyword minor=True|False -get_ticklocs A list of Tick locations - keyword minor=True|False -get_major_locator The matplotlib.ticker.Locator instance for major ticks -get_major_formatter The matplotlib.ticker.Formatter instance for major ticks -get_minor_locator The matplotlib.ticker.Locator instance for minor ticks -get_minor_formatter The matplotlib.ticker.Formatter instance for minor ticks -get_major_ticks A list of Tick instances for major ticks -get_minor_ticks A list of Tick instances for minor ticks -grid Turn the grid on or off for the major or minor ticks -====================== ========================================================= - -Here is an example, not recommended for its beauty, which customizes -the axes and tick properties - -.. plot:: pyplots/fig_axes_customize_simple.py - :include-source: - - -.. _tick-container: - -Tick containers -=============== - -The :class:`matplotlib.axis.Tick` is the final container object in our -descent from the :class:`~matplotlib.figure.Figure` to the -:class:`~matplotlib.axes.Axes` to the :class:`~matplotlib.axis.Axis` -to the :class:`~matplotlib.axis.Tick`. The ``Tick`` contains the tick -and grid line instances, as well as the label instances for the upper -and lower ticks. Each of these is accessible directly as an attribute -of the ``Tick``. In addition, there are boolean variables that determine -whether the upper labels and ticks are on for the x-axis and whether -the right labels and ticks are on for the y-axis. - -============== ========================================================== -Tick attribute Description -============== ========================================================== -tick1line Line2D instance -tick2line Line2D instance -gridline Line2D instance -label1 Text instance -label2 Text instance -gridOn boolean which determines whether to draw the tickline -tick1On boolean which determines whether to draw the 1st tickline -tick2On boolean which determines whether to draw the 2nd tickline -label1On boolean which determines whether to draw tick label -label2On boolean which determines whether to draw tick label -============== ========================================================== - -Here is an example which sets the formatter for the right side ticks with -dollar signs and colors them green on the right side of the yaxis - -.. plot:: pyplots/dollar_ticks.py - :include-source: +.. _artist-tutorial: + +*************** +Artist tutorial +*************** + +There are three layers to the matplotlib API. The +:class:`matplotlib.backend_bases.FigureCanvas` is the area onto which +the figure is drawn, the :class:`matplotlib.backend_bases.Renderer` is +the object which knows how to draw on the +:class:`~matplotlib.backend_bases.FigureCanvas`, and the +:class:`matplotlib.artist.Artist` is the object that knows how to use +a renderer to paint onto the canvas. The +:class:`~matplotlib.backend_bases.FigureCanvas` and +:class:`~matplotlib.backend_bases.Renderer` handle all the details of +talking to user interface toolkits like `wxPython +<http://www.wxpython.org>`_ or drawing languages like PostScript®, and +the ``Artist`` handles all the high level constructs like representing +and laying out the figure, text, and lines. The typical user will +spend 95% of his time working with the ``Artists``. + +There are two types of ``Artists``: primitives and containers. The primitives represent the standard graphical objects we want to paint onto our canvas: :class:`~matplotlib.lines.Line2D`, :class:`~matplotlib.patches.Rectangle`, :class:`~matplotlib.text.Text`, :class:`~matplotlib.image.AxesImage`, etc., and the containers are places to put them (:class:`~matplotlib.axis.Axis`, :class:`~matplotlib.axes.Axes` and :class:`~matplotlib.figure.Figure`). The standard use is to create a :class:`~matplotlib.figure.Figure` instance, use the ``Figure`` to create one or more :class:`~matplotlib.axes.Axes` or :class:`~matplotlib.axes.Subplot` instances, and use the ``Axes`` instance helper methods to create the primitives. In the example below, we create a ``Figure`` instance using :func:`matplotlib.pyplot.figure`, which is a convenience method for instantiating ``Figure`` instances and connecting them with your user interface or drawing toolkit ``FigureCanvas``. As we will discuss below, this is not necessary -- you +can work directly with PostScript, PDF Gtk+, or wxPython ``FigureCanvas`` instances, instantiate your ``Figures`` directly and connect them yourselves -- but since we are focusing here on the ``Artist`` API we'll let :mod:`~matplotlib.pyplot` handle some of those details for us:: + + import matplotlib.pyplot as plt + fig = plt.figure() + ax = fig.add_subplot(2,1,1) # two rows, one column, first plot + +The :class:`~matplotlib.axes.Axes` is probably the most important +class in the matplotlib API, and the one you will be working with most +of the time. This is because the ``Axes`` is the plotting area into +which most of the objects go, and the ``Axes`` has many special helper +methods (:meth:`~matplotlib.axes.Axes.plot`, +:meth:`~matplotlib.axes.Axes.text`, +:meth:`~matplotlib.axes.Axes.hist`, +:meth:`~matplotlib.axes.Axes.imshow`) to create the most common +graphics primitives (:class:`~matplotlib.lines.Line2D`, +:class:`~matplotlib.text.Text`, +:class:`~matplotlib.patches.Rectangle`, +:class:`~matplotlib.image.Image`, respectively). These helper methods +will take your data (eg. ``numpy`` arrays and strings) and create +primitive ``Artist`` instances as needed (eg. ``Line2D``), add them to +the relevant containers, and draw them when requested. Most of you +are probably familiar with the :class:`~matplotlib.axes.Subplot`, +which is just a special case of an ``Axes`` that lives on a regular +rows by columns grid of ``Subplot`` instances. If you want to create +an ``Axes`` at an arbitrary location, simply use the +:meth:`~matplotlib.figure.Figure.add_axes` method which takes a list +of ``[left, bottom, width, height]`` values in 0-1 relative figure +coordinates:: + + fig2 = plt.figure() + ax2 = fig2.add_axes([0.15, 0.1, 0.7, 0.3]) + +Continuing with our example:: + + import numpy as np + t = np.arange(0.0, 1.0, 0.01) + s = np.sin(2*np.pi*t) + line, = ax.plot(t, s, color='blue', lw=2) + +In this example, ``ax`` is the ``Axes`` instance created by the +``fig.add_subplot`` call above (remember ``Subplot`` is just a +subclass of ``Axes``) and when you call ``ax.plot``, it creates a +``Line2D`` instance and adds it to the :attr:`Axes.lines +<matplotlib.axes.Axes.lines>` list. In the interactive `ipython +<http://ipython.scipy.org/>`_ session below, you can see that the +``Axes.lines`` list is length one and contains the same line that was +returned by the ``line, = ax.plot...`` call: + +.. sourcecode:: ipython + + In [101]: ax.lines[0] + Out[101]: <matplotlib.lines.Line2D instance at 0x19a95710> + + In [102]: line + Out[102]: <matplotlib.lines.Line2D instance at 0x19a95710> + +If you make subsequent calls to ``ax.plot`` (and the hold state is "on" +which is the default) then additional lines will be added to the list. +You can remove lines later simply by calling the list methods; either +of these will work:: + + del ax.lines[0] + ax.lines.remove(line) # one or the other, not both! + +The Axes also has helper methods to configure and decorate the x-axis +and y-axis tick, tick labels and axis labels:: + + xtext = ax.set_xlabel('my xdata') # returns a Text instance + ytext = ax.set_ylabel('my xdata') + +When you call :meth:`ax.set_xlabel <matplotlib.axes.Axes.set_xlabel>`, +it passes the information on the :class:`~matplotlib.text.Text` +instance of the :class:`~matplotlib.axis.XAxis`. Each ``Axes`` +instance contains an :class:`~matplotlib.axis.XAxis` and a +:class:`~matplotlib.axis.YAxis` instance, which handle the layout and +drawing of the ticks, tick labels and axis labels. + +.. I'm commenting this out, since the new Sphinx cross-references +.. sort of take care of this above - MGD + +.. Here are the most important matplotlib modules that contain the +.. classes referenced above + +.. =============== ================== +.. Artist Module +.. =============== ================== +.. Artist matplotlib.artist +.. Rectangle matplotlib.patches +.. Line2D matplotlib.lines +.. Axes matplotlib.axes +.. XAxis and YAxis matplotlib.axis +.. Figure matplotlib.figure +.. Text matplotlib.text +.. =============== ================== + +Try creating the figure below. + +.. plot:: pyplots/fig_axes_labels_simple.py + +.. _customizing-artists: + +Customizing your objects +======================== + +Every element in the figure is represented by a matplotlib +:class:`~matplotlib.artist.Artist`, and each has an extensive list of +properties to configure its appearance. The figure itself contains a +:class:`~matplotlib.patches.Rectangle` exactly the size of the figure, +which you can use to set the background color and transparency of the +figures. Likewise, each :class:`~matplotlib.axes.Axes` bounding box +(the standard white box with black edges in the typical matplotlib +plot, has a ``Rectangle`` instance that determines the color, +transparency, and other properties of the Axes. These instances are +stored as member variables :attr:`Figure.patch +<matplotlib.figure.Figure.patch>` and :attr:`Axes.patch +<matplotlib.axes.Axes.patch>` ("Patch" is a name inherited from +MATLAB, and is a 2D "patch" of color on the figure, eg. rectangles, +circles and polygons). Every matplotlib ``Artist`` has the following +properties + +========== ====================================================================== +Property Description +========== ====================================================================== +alpha The transparency - a scalar from 0-1 +animated A boolean that is used to facilitate animated drawing +axes The axes that the Artist lives in, possibly None +clip_box The bounding box that clips the Artist +clip_on Whether clipping is enabled +clip_path The path the artist is clipped to +contains A picking function to test whether the artist contains the pick point +figure The figure instance the artist lives in, possibly None +label A text label (eg. for auto-labeling) +picker A python object that controls object picking +transform The transformation +visible A boolean whether the artist should be drawn +zorder A number which determines the drawing order +========== ====================================================================== + +Each of the properties is accessed with an old-fashioned setter or +getter (yes we know this irritates Pythonistas and we plan to support +direct access via properties or traits but it hasn't been done yet). +For example, to multiply the current alpha by a half:: + + a = o.get_alpha() + o.set_alpha(0.5*a) + +If you want to set a number of properties at once, you can also use +the ``set`` method with keyword arguments. For example:: + + o.set(alpha=0.5, zorder=2) + +If you are working interactively at the python shell, a handy way to +inspect the ``Artist`` properties is to use the +:func:`matplotlib.artist.getp` function (simply +:func:`~matplotlib.pylab.getp` in pylab), which lists the properties +and their values. This works for classes derived from ``Artist`` as +well, eg. ``Figure`` and ``Rectangle``. Here are the ``Figure`` rectangle +properties mentioned above: + +.. sourcecode:: ipython + + In [149]: matplotlib.artist.getp(fig.patch) + alpha = 1.0 + animated = False + antialiased or aa = True + axes = None + clip_box = None + clip_on = False + clip_path = None + contains = None + edgecolor or ec = w + facecolor or fc = 0.75 + figure = Figure(8.125x6.125) + fill = 1 + hatch = None + height = 1 + label = + linewidth or lw = 1.0 + picker = None + transform = <Affine object at 0x134cca84> + verts = ((0, 0), (0, 1), (1, 1), (1, 0)) + visible = True + width = 1 + window_extent = <Bbox object at 0x134acbcc> + x = 0 + y = 0 + zorder = 1 + +.. TODO: Update these URLs + +The docstrings for all of the classes also contain the ``Artist`` +properties, so you can consult the interactive "help" or the +:ref:`artist-api` for a listing of properties for a given object. + +.. _object-containers: + +Object containers +================= + + +Now that we know how to inspect and set the properties of a given +object we want to configure, we need to now how to get at that object. +As mentioned in the introduction, there are two kinds of objects: +primitives and containers. The primitives are usually the things you +want to configure (the font of a :class:`~matplotlib.text.Text` +instance, the width of a :class:`~matplotlib.lines.Line2D`) although +the containers also have some properties as well -- for example the +:class:`~matplotlib.axes.Axes` :class:`~matplotlib.artist.Artist` is a +container that contains many of the primitives in your plot, but it +also has properties like the ``xscale`` to control whether the xaxis +is 'linear' or 'log'. In this section we'll review where the various +container objects store the ``Artists`` that you want to get at. + +.. _figure-container: + +Figure container +================ + +The top level container ``Artist`` is the +:class:`matplotlib.figure.Figure`, and it contains everything in the +figure. The background of the figure is a +:class:`~matplotlib.patches.Rectangle` which is stored in +:attr:`Figure.patch <matplotlib.figure.Figure.patch>`. As +you add subplots (:meth:`~matplotlib.figure.Figure.add_subplot`) and +axes (:meth:`~matplotlib.figure.Figure.add_axes`) to the figure +these will be appended to the :attr:`Figure.axes +<matplotlib.figure.Figure.axes>`. These are also returned by the +methods that create them: + +.. sourcecode:: ipython + + In [156]: fig = plt.figure() + + In [157]: ax1 = fig.add_subplot(211) + + In [158]: ax2 = fig.add_axes([0.1, 0.1, 0.7, 0.3]) + + In [159]: ax1 + Out[159]: <matplotlib.axes.Subplot instance at 0xd54b26c> + + In [160]: print fig.axes + [<matplotlib.axes.Subplot instance at 0xd54b26c>, <matplotlib.axes.Axes instance at 0xd3f0b2c>] + +Because the figure maintains the concept of the "current axes" (see +:meth:`Figure.gca <matplotlib.figure.Figure.gca>` and +:meth:`Figure.sca <matplotlib.figure.Figure.sca>`) to support the +pylab/pyplot state machine, you should not insert or remove axes +directly from the axes list, but rather use the +:meth:`~matplotlib.figure.Figure.add_subplot` and +:meth:`~matplotlib.figure.Figure.add_axes` methods to insert, and the +:meth:`~matplotlib.figure.Figure.delaxes` method to delete. You are +free however, to iterate over the list of axes or index into it to get +access to ``Axes`` instances you want to customize. Here is an +example which turns all the axes grids on:: + + for ax in fig.axes: + ax.grid(True) + + +The figure also has its own text, lines, patches and images, which you +can use to add primitives directly. The default coordinate system for +the ``Figure`` will simply be in pixels (which is not usually what you +want) but you can control this by setting the transform property of +the ``Artist`` you are adding to the figure. + +.. TODO: Is that still true? + +More useful is "figure coordinates" where (0, 0) is the bottom-left of +the figure and (1, 1) is the top-right of the figure which you can +obtain by setting the ``Artist`` transform to :attr:`fig.transFigure +<matplotlib.figure.Figure.transFigure>`: + +.. sourcecode:: ipython + + In [191]: fig = plt.figure() + + In [192]: l1 = matplotlib.lines.Line2D([0, 1], [0, 1], + transform=fig.transFigure, figure=fig) + + In [193]: l2 = matplotlib.lines.Line2D([0, 1], [1, 0], + transform=fig.transFigure, figure=fig) + + In [194]: fig.lines.extend([l1, l2]) + + In [195]: fig.canvas.draw() + +.. plot:: pyplots/fig_x.py + + +Here is a summary of the Artists the figure contains + +.. TODO: Add xrefs to this table + +================ =============================================================== +Figure attribute Description +================ =============================================================== +axes A list of Axes instances (includes Subplot) +patch The Rectangle background +images A list of FigureImages patches - useful for raw pixel display +legends A list of Figure Legend instances (different from Axes.legends) +lines A list of Figure Line2D instances (rarely used, see Axes.lines) +patches A list of Figure patches (rarely used, see Axes.patches) +texts A list Figure Text instances +================ =============================================================== + +.. _axes-container: + +Axes container +============== + +The :class:`matplotlib.axes.Axes` is the center of the matplotlib +universe -- it contains the vast majority of all the ``Artists`` used +in a figure with many helper methods to create and add these +``Artists`` to itself, as well as helper methods to access and +customize the ``Artists`` it contains. Like the +:class:`~matplotlib.figure.Figure`, it contains a +:class:`~matplotlib.patches.Patch` +:attr:`~matplotlib.axes.Axes.patch` which is a +:class:`~matplotlib.patches.Rectangle` for Cartesian coordinates and a +:class:`~matplotlib.patches.Circle` for polar coordinates; this patch +determines the shape, background and border of the plotting region:: + + ax = fig.add_subplot(111) + rect = ax.patch # a Rectangle instance + rect.set_facecolor('green') + +When you call a plotting method, eg. the canonical +:meth:`~matplotlib.axes.Axes.plot` and pass in arrays or lists of +values, the method will create a :meth:`matplotlib.lines.Line2D` +instance, update the line with all the ``Line2D`` properties passed as +keyword arguments, add the line to the :attr:`Axes.lines +<matplotlib.axes.Axes.lines>` container, and returns it to you: + +.. sourcecode:: ipython + + In [213]: x, y = np.random.rand(2, 100) + + In [214]: line, = ax.plot(x, y, '-', color='blue', linewidth=2) + +``plot`` returns a list of lines because you can pass in multiple x, y +pairs to plot, and we are unpacking the first element of the length +one list into the line variable. The line has been added to the +``Axes.lines`` list: + +.. sourcecode:: ipython + + In [229]: print ax.lines + [<matplotlib.lines.Line2D instance at 0xd378b0c>] + +Similarly, methods that create patches, like +:meth:`~matplotlib.axes.Axes.bar` creates a list of rectangles, will +add the patches to the :attr:`Axes.patches +<matplotlib.axes.Axes.patches>` list: + +.. sourcecode:: ipython + + In [233]: n, bins, rectangles = ax.hist(np.random.randn(1000), 50, facecolor='yellow') + + In [234]: rectangles + Out[234]: <a list of 50 Patch objects> + + In [235]: print len(ax.patches) + +You should not add objects directly to the ``Axes.lines`` or +``Axes.patches`` lists unless you know exactly what you are doing, +because the ``Axes`` needs to do a few things when it creates and adds +an object. It sets the figure and axes property of the ``Artist``, as +well as the default ``Axes`` transformation (unless a transformation +is set). It also inspects the data contained in the ``Artist`` to +update the data structures controlling auto-scaling, so that the view +limits can be adjusted to contain the plotted data. You can, +nonetheless, create objects yourself and add them directly to the +``Axes`` using helper methods like +:meth:`~matplotlib.axes.Axes.add_line` and +:meth:`~matplotlib.axes.Axes.add_patch`. Here is an annotated +interactive session illustrating what is going on: + +.. sourcecode:: ipython + + In [261]: fig = plt.figure() + + In [262]: ax = fig.add_subplot(111) + + # create a rectangle instance + In [263]: rect = matplotlib.patches.Rectangle( (1,1), width=5, height=12) + + # by default the axes instance is None + In [264]: print rect.get_axes() + None + + # and the transformation instance is set to the "identity transform" + In [265]: print rect.get_transform() + <Affine object at 0x13695544> + + # now we add the Rectangle to the Axes + In [266]: ax.add_patch(rect) + + # and notice that the ax.add_patch method has set the axes + # instance + In [267]: print rect.get_axes() + Axes(0.125,0.1;0.775x0.8) + + # and the transformation has been set too + In [268]: print rect.get_transform() + <Affine object at 0x15009ca4> + + # the default axes transformation is ax.transData + In [269]: print ax.transData + <Affine object at 0x15009ca4> + + # notice that the xlimits of the Axes have not been changed + In [270]: print ax.get_xlim() + (0.0, 1.0) + + # but the data limits have been updated to encompass the rectangle + In [271]: print ax.dataLim.bounds + (1.0, 1.0, 5.0, 12.0) + + # we can manually invoke the auto-scaling machinery + In [272]: ax.autoscale_view() + + # and now the xlim are updated to encompass the rectangle + In [273]: print ax.get_xlim() + (1.0, 6.0) + + # we have to manually force a figure draw + In [274]: ax.figure.canvas.draw() + + +There are many, many ``Axes`` helper methods for creating primitive +``Artists`` and adding them to their respective containers. The table +below summarizes a small sampling of them, the kinds of ``Artist`` they +create, and where they store them + +============================== ==================== ======================= +Helper method Artist Container +============================== ==================== ======================= +ax.annotate - text annotations Annotate ax.texts +ax.bar - bar charts Rectangle ax.patches +ax.errorbar - error bar plots Line2D and Rectangle ax.lines and ax.patches +ax.fill - shared area Polygon ax.patches +ax.hist - histograms Rectangle ax.patches +ax.imshow - image data AxesImage ax.images +ax.legend - axes legends Legend ax.legends +ax.plot - xy plots Line2D ax.lines +ax.scatter - scatter charts PolygonCollection ax.collections +ax.text - text Text ax.texts +============================== ==================== ======================= + + +In addition to all of these ``Artists``, the ``Axes`` contains two +important ``Artist`` containers: the :class:`~matplotlib.axis.XAxis` +and :class:`~matplotlib.axis.YAxis`, which handle the drawing of the +ticks and labels. These are stored as instance variables +:attr:`~matplotlib.axes.Axes.xaxis` and +:attr:`~matplotlib.axes.Axes.yaxis`. The ``XAxis`` and ``YAxis`` +containers will be detailed below, but note that the ``Axes`` contains +many helper methods which forward calls on to the +:class:`~matplotlib.axis.Axis` instances so you often do not need to +work with them directly unless you want to. For example, you can set +the font size of the ``XAxis`` ticklabels using the ``Axes`` helper +method:: + + for label in ax.get_xticklabels(): + label.set_color('orange') + +Below is a summary of the Artists that the Axes contains + +============== ====================================== +Axes attribute Description +============== ====================================== +artists A list of Artist instances +patch Rectangle instance for Axes background +collections A list of Collection instances +images A list of AxesImage +legends A list of Legend instances +lines A list of Line2D instances +patches A list of Patch instances +texts A list of Text instances +xaxis matplotlib.axis.XAxis instance +yaxis matplotlib.axis.YAxis instance +============== ====================================== + +.. _axis-container: + +Axis containers +=============== + +The :class:`matplotlib.axis.Axis` instances handle the drawing of the +tick lines, the grid lines, the tick labels and the axis label. You +can configure the left and right ticks separately for the y-axis, and +the upper and lower ticks separately for the x-axis. The ``Axis`` +also stores the data and view intervals used in auto-scaling, panning +and zooming, as well as the :class:`~matplotlib.ticker.Locator` and +:class:`~matplotlib.ticker.Formatter` instances which control where +the ticks are placed and how they are represented as strings. + +Each ``Axis`` object contains a :attr:`~matplotlib.axis.Axis.label` attribute (this is what :mod:`~matplotlib.pylab` modifies in calls to :func:`~matplotlib.pylab.xlabel` and :func:`~matplotlib.pylab.ylabel`) as well as a list of major and minor ticks. The ticks are :class:`~matplotlib.axis.XTick` and :class:`~matplotlib.axis.YTick` instances, which contain the actual line and text primitives that render the ticks and ticklabels. Because the ticks are dynamically created as needed (eg. when panning and zooming), you should access the lists of major and minor ticks through their accessor methods :meth:`~matplotlib.axis.Axis.get_major_ticks` and :meth:`~matplotlib.axis.Axis.get_minor_ticks`. Although the ticks contain all the primitives and will be covered below, the ``Axis`` methods contain accessor methods to return the tick lines, tick labels, tick locations etc.: + +.. sourcecode:: ipython + + In [285]: axis = ax.xaxis + + In [286]: axis.get_ticklocs() + Out[286]: array([ 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.]) + + In [287]: axis.get_ticklabels() + Out[287]: <a list of 10 Text major ticklabel objects> + + # note there are twice as many ticklines as labels because by + # default there are tick lines at the top and bottom but only tick + # labels below the xaxis; this can be customized + In [288]: axis.get_ticklines() + Out[288]: <a list of 20 Line2D ticklines objects> + + # by default you get the major ticks back + In [291]: axis.get_ticklines() + Out[291]: <a list of 20 Line2D ticklines objects> + + # but you can also ask for the minor ticks + In [292]: axis.get_ticklines(minor=True) + Out[292]: <a list of 0 Line2D ticklines objects> + +Here is a summary of some of the useful accessor methods of the ``Axis`` +(these have corresponding setters where useful, such as +set_major_formatter) + +====================== ========================================================= +Accessor method Description +====================== ========================================================= +get_scale The scale of the axis, eg 'log' or 'linear' +get_view_interval ... [truncated message content] |
From: <jd...@us...> - 2010-07-06 01:05:35
|
Revision: 8498 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=8498&view=rev Author: jdh2358 Date: 2010-07-06 01:05:28 +0000 (Tue, 06 Jul 2010) Log Message: ----------- added whats new for 1.0 Modified Paths: -------------- trunk/matplotlib/doc/users/whats_new.rst Added Paths: ----------- trunk/matplotlib/doc/api/gridspec_api.rst trunk/matplotlib/doc/pyplots/whats_new_1_subplot3d.py Added: trunk/matplotlib/doc/api/gridspec_api.rst =================================================================== --- trunk/matplotlib/doc/api/gridspec_api.rst (rev 0) +++ trunk/matplotlib/doc/api/gridspec_api.rst 2010-07-06 01:05:28 UTC (rev 8498) @@ -0,0 +1,12 @@ +************* +matplotlib gridspec +************* + + +:mod:`matplotlib.gridspec` +==================== + +.. automodule:: matplotlib.gridspec + :members: + :undoc-members: + :show-inheritance: Added: trunk/matplotlib/doc/pyplots/whats_new_1_subplot3d.py =================================================================== --- trunk/matplotlib/doc/pyplots/whats_new_1_subplot3d.py (rev 0) +++ trunk/matplotlib/doc/pyplots/whats_new_1_subplot3d.py 2010-07-06 01:05:28 UTC (rev 8498) @@ -0,0 +1,30 @@ +from mpl_toolkits.mplot3d.axes3d import Axes3D +from matplotlib import cm +#from matplotlib.ticker import LinearLocator, FixedLocator, FormatStrFormatter +import matplotlib.pyplot as plt +import numpy as np + +fig = plt.figure() + +ax = fig.add_subplot(1, 2, 1, projection='3d') +X = np.arange(-5, 5, 0.25) +Y = np.arange(-5, 5, 0.25) +X, Y = np.meshgrid(X, Y) +R = np.sqrt(X**2 + Y**2) +Z = np.sin(R) +surf = ax.plot_surface(X, Y, Z, rstride=1, cstride=1, cmap=cm.jet, + linewidth=0, antialiased=False) +ax.set_zlim3d(-1.01, 1.01) + +#ax.w_zaxis.set_major_locator(LinearLocator(10)) +#ax.w_zaxis.set_major_formatter(FormatStrFormatter('%.03f')) + +fig.colorbar(surf, shrink=0.5, aspect=5) + +from mpl_toolkits.mplot3d.axes3d import get_test_data +ax = fig.add_subplot(1, 2, 2, projection='3d') +X, Y, Z = get_test_data(0.05) +ax.plot_wireframe(X, Y, Z, rstride=10, cstride=10) + +plt.show() + Modified: trunk/matplotlib/doc/users/whats_new.rst =================================================================== --- trunk/matplotlib/doc/users/whats_new.rst 2010-07-05 23:09:51 UTC (rev 8497) +++ trunk/matplotlib/doc/users/whats_new.rst 2010-07-06 01:05:28 UTC (rev 8498) @@ -7,11 +7,140 @@ This page just covers the highlights -- for the full story, see the `CHANGELOG <http://matplotlib.sourceforge.net/_static/CHANGELOG>`_ +new in matplotlib-1.0 +====================== + +.. _whats-new-html5: + +HTML5/Canvas backend +--------------------- + +Simon Ratcliffe and Ludwig Schwardt have released an `HTML5/Canvas +<http://code.google.com/p/mplh5canvas/>`_ backend for matplotlib. The +backend is almost feature complete, and they have done a lot of work +comparing their html5 rendered images with our core renderer Agg. The +backend features client/server interactive navigation of matplotlib +figures in an html5 compliant browser. + +Sophisticated subplot grid layout +--------------------------------- + +Jae-Joon Lee has written :mod:`~matplotlib.gridspec`, a new module for +doing complex subplot layouts, featuring row and column spans and +more. See :ref:`gridspec` for a tutorial overview. + +.. plot:: users/plotting/examples/demo_gridspec01.py + +Easy pythonic subplots +----------------------- + +Fernando Perez got tired of all the boilerplate code needed to create a +figure and multiple subplots when using the matplotlib API, and wrote +a :func:`~matplotlib.pyplot.subplots` helper function. Basic usage +allows you to create the figure and an array of subplots with numpy +indexing (starts with 0). Eg:: + + fig, axarr = plt.subplots(2, 2) + axarr[0,0].plot([1,2,3]) # upper, left + +See :ref:`pylab_examples-subplots_demo` for several code examples. + +Contour fixes and and triplot +--------------------------------- + +Ian Thomas has fixed a long-standing bug that has vexed our most +talented developers for years. :func:`~matplotlib.pyplot.contourf` +now handles interior masked regions, and the boundaries of line and +filled contours coincide. + +Additionally, he has contributed a new module `matplotlib.tri` and +helper function :func:`~matplotlib.pyplot.triplot` for creating and +plotting unstructured triangular grids. + +.. plot:: mpl_examples/pylab_examples/triplot_demo.py + +multiple calls to show supported +--------------------------------- + +A long standing request is to support multiple calls to +:func:`~matplotlib.pyplot.show`. This has been difficult because it +is hard to get consistent behavior across operating systems, user +interface toolkits and versions. Eric Firing has done a lot of work +on rationalizing show across backends, with the desired behavior to +make show raise all newly created figures and block execution until +they are closed. Repeated calls to show should raise newly created +figures since the last call. Eric has done a lot of testing on the +user interface toolkits and versions and platforms he has access to, +but it is not possible to test them all, so please report problems to +the `mailing list +<http://sourceforge.net/mailarchive/forum.php?forum_name=matplotlib-users>`_ +and `bug tracker +<http://sourceforge.net/tracker/?group_id=80706&atid=560720>`_. + + +mplot3d graphs can be embedded in arbitrary axes +------------------------------------------------- + +You can now place an mplot3d graph into an arbitrary axes location, +supporting mixing of 2D and 3D graphs in the same figure, and/or +multiple 3D graphs in a single figure, using the "projection" keyword +argument to add_axes or add_subplot. Thanks Ben Root. + +.. plot:: pyplots/whats_new_1_subplot3d.py + +tick_params +------------ + +Eric Firing wrote tick_params, a convenience method for changing the +appearance of ticks and tick labels. See pyplot function +:func:`~matplotlib.pyplot.tick_params` and associated Axes method +:meth:`~matplotlib.axes.Axes.tick_params`. + +Lots of performance and feature enhancements +--------------------------------------------- + + +* Faster magnification of large images, and the ability to zoom in to + a single pixel + +* Local installs of documentation work better + +* Improved "widgets" -- mouse grabbing is supported + +* More accurate snapping of lines to pixel boundaries + +* More consistent handling of color, particularly the alpha channel, + throughout the API + +Much improved software carpentry +--------------------------------- + +The matplotlib trunk is probably in as good a shape as it has ever +been, thanks to improved software carpentry. We now have a buildbot +which runs a suite of nose regression tests on every svn commit, +auto-generating a set of images and comparing them against a set of +known-goods, sending emails to developers on failures with a +pixel-by-pixel image comparison. Releases and release bugfixes happen +in branches, allowing active new feature development to happen in the +trunk while keeping the release branches stable. Thanks to Andrew +Straw, Michael Droettboom and other matplotlib developers for the +heavy lifting. + +Bugfix marathon +---------------- + +Eric Firing went on a bug fixing and closing marathon, closing over +100 bugs on the `bug tracker +<http://sourceforge.net/tracker/?group_id=80706&atid=560720>`_ with +help from Jae-Joon Lee, Michael Droettboom, Christoph Gohlke and +Michiel de Hoon. + + new in matplotlib-0.99 ====================== -.. _whats-new-mplot3d: + New documentation ----------------- @@ -21,6 +150,7 @@ working with paths and transformations: :ref:`path_tutorial` and :ref:`transforms_tutorial`. +.. _whats-new-mplot3d: mplot3d -------- This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <js...@us...> - 2010-07-30 16:12:56
|
Revision: 8599 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=8599&view=rev Author: jswhit Date: 2010-07-30 16:12:48 +0000 (Fri, 30 Jul 2010) Log Message: ----------- update broken basemap toolkit screenshot Modified Paths: -------------- trunk/matplotlib/doc/pyplots/plotmap.py trunk/matplotlib/doc/users/screenshots.rst Modified: trunk/matplotlib/doc/pyplots/plotmap.py =================================================================== --- trunk/matplotlib/doc/pyplots/plotmap.py 2010-07-30 12:28:08 UTC (rev 8598) +++ trunk/matplotlib/doc/pyplots/plotmap.py 2010-07-30 16:12:48 UTC (rev 8599) @@ -1,66 +1,41 @@ -# make plot of etopo bathymetry/topography data on -# lambert conformal conic map projection, drawing coastlines, state and -# country boundaries, and parallels/meridians. - -# the data is interpolated to the native projection grid. -import os -from mpl_toolkits.basemap import Basemap, shiftgrid +from mpl_toolkits.basemap import Basemap +import matplotlib.pyplot as plt import numpy as np - -from pylab import title, colorbar, show, axes, cm, arange, figure, \ - text - -# read in topo data (on a regular lat/lon grid) -# longitudes go from 20 to 380. -# you can get this data from matplolib svn matplotlib/htdocs/screenshots/data/ -datadir = '/home/jdhunter/python/svn/matplotlib/trunk/htdocs/screenshots/data/' -if not os.path.exists(datadir): - raise SystemExit('You need to download the data with svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/htdocs/screenshots/data/" and set the datadir variable in %s'%__file__) - -topoin = np.loadtxt(os.path.join(datadir, 'etopo20data.gz')) -lons = np.loadtxt(os.path.join(datadir, 'etopo20lons.gz')) -lats = np.loadtxt(os.path.join(datadir, 'etopo20lats.gz')) -# shift data so lons go from -180 to 180 instead of 20 to 380. -topoin,lons = shiftgrid(180.,topoin,lons,start=False) - -# setup of basemap ('lcc' = lambert conformal conic). -# use major and minor sphere radii from WGS84 ellipsoid. -m = Basemap(llcrnrlon=-145.5,llcrnrlat=1.,urcrnrlon=-2.566,urcrnrlat=46.352,\ - rsphere=(6378137.00,6356752.3142),\ - resolution='l',area_thresh=1000.,projection='lcc',\ - lat_1=50.,lon_0=-107.) -# transform to nx x ny regularly spaced native projection grid -nx = int((m.xmax-m.xmin)/40000.)+1; ny = int((m.ymax-m.ymin)/40000.)+1 -topodat,x,y = m.transform_scalar(topoin,lons,lats,nx,ny,returnxy=True) -# create the figure. -fig=figure(figsize=(6,6)) -# add an axes, leaving room for colorbar on the right. -ax = fig.add_axes([0.1,0.1,0.7,0.7]) -# plot image over map with imshow. -im = m.imshow(topodat,cm.jet) -# setup colorbar axes instance. -# for matplotlib 0.91 and earlier, could do l,b,w,h = ax.get_position() -# for post 0.91, pos = ax.get_position(); l,b,w,h = pos.bounds -# this works for both. -pos = ax.get_position() -l, b, w, h = getattr(pos, 'bounds', pos) -cax = axes([l+w+0.075, b, 0.05, h]) -colorbar(cax=cax) # draw colorbar -axes(ax) # make the original axes current again -# plot blue dot on boulder, colorado and label it as such. -xpt,ypt = m(-104.237,40.125) -m.plot([xpt],[ypt],'bo') -text(xpt+100000,ypt+100000,'Boulder') -# draw coastlines and political boundaries. -m.drawcoastlines() -m.drawcountries() -m.drawstates() -# draw parallels and meridians. -# label on left, right and bottom of map. -parallels = arange(0.,80,20.) -m.drawparallels(parallels,labels=[1,1,0,1]) -meridians = arange(10.,360.,30.) -m.drawmeridians(meridians,labels=[1,1,0,1]) -# set title. -title('ETOPO Topography - Lambert Conformal Conic') -show() +# create figure +fig = plt.figure(figsize=(8,8)) +# set up orthographic map projection with +# perspective of satellite looking down at 50N, 100W. +# use low resolution coastlines. +map = Basemap(projection='ortho',lat_0=50,lon_0=-100,resolution='l') +# lat/lon coordinates of five cities. +lats=[40.02,32.73,38.55,48.25,17.29] +lons=[-105.16,-117.16,-77.00,-114.21,-88.10] +cities=['Boulder, CO','San Diego, CA', + 'Washington, DC','Whitefish, MT','Belize City, Belize'] +# compute the native map projection coordinates for cities. +xc,yc = map(lons,lats) +# make up some data on a regular lat/lon grid. +nlats = 73; nlons = 145; delta = 2.*np.pi/(nlons-1) +lats = (0.5*np.pi-delta*np.indices((nlats,nlons))[0,:,:]) +lons = (delta*np.indices((nlats,nlons))[1,:,:]) +wave = 0.75*(np.sin(2.*lats)**8*np.cos(4.*lons)) +mean = 0.5*np.cos(2.*lats)*((np.sin(2.*lats))**2 + 2.) +# compute native map projection coordinates of lat/lon grid. +# (convert lons and lats to degrees first) +x, y = map(lons*180./np.pi, lats*180./np.pi) +# draw map boundary +map.drawmapboundary(color="0.9") +# draw graticule (latitude and longitude grid lines) +map.drawmeridians(np.arange(0,360,30),color="0.9") +map.drawparallels(np.arange(-90,90,30),color="0.9") +# plot filled circles at the locations of the cities. +map.plot(xc,yc,'wo') +# plot the names of five cities. +for name,xpt,ypt in zip(cities,xc,yc): + plt.text(xpt+100000,ypt+100000,name,fontsize=9,color='w') +# contour data over the map. +cs = map.contour(x,y,wave+mean,15,linewidths=1.5) +# draw blue marble image in background. +# (downsample the image by 50% for speed) +map.bluemarble(scale=0.5) +plt.show() Modified: trunk/matplotlib/doc/users/screenshots.rst =================================================================== --- trunk/matplotlib/doc/users/screenshots.rst 2010-07-30 12:28:08 UTC (rev 8598) +++ trunk/matplotlib/doc/users/screenshots.rst 2010-07-30 16:12:48 UTC (rev 8599) @@ -188,13 +188,9 @@ Basemap demo ============ -Jeff Whitaker provided this example showing how to efficiently plot a -collection of lines over a colormap image using the -:ref:`toolkit_basemap` . Many map projections are handled via the -proj4 library: cylindrical equidistant, mercator, lambert conformal -conic, lambert azimuthal equal area, albers equal area conic and -stereographic. See the `tutorial -<http://www.scipy.org/wikis/topical_software/Maps>`_ entry on the wiki. +Jeff Whitaker's :ref:`toolkit_basemap` add-on toolkit makes it possible to plot data on many +different map projections. This example shows how to plot contours, markers and text +on an orthographic projection, with NASA's "blue marble" satellite image as a background. .. plot:: pyplots/plotmap.py This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <jd...@us...> - 2010-10-13 15:45:20
|
Revision: 8751 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=8751&view=rev Author: jdh2358 Date: 2010-10-13 15:45:14 +0000 (Wed, 13 Oct 2010) Log Message: ----------- add build_dep instructions to installing docs and faq Modified Paths: -------------- trunk/matplotlib/doc/faq/installing_faq.rst trunk/matplotlib/doc/users/installing.rst Modified: trunk/matplotlib/doc/faq/installing_faq.rst =================================================================== --- trunk/matplotlib/doc/faq/installing_faq.rst 2010-10-12 19:13:57 UTC (rev 8750) +++ trunk/matplotlib/doc/faq/installing_faq.rst 2010-10-13 15:45:14 UTC (rev 8751) @@ -106,6 +106,17 @@ > cd matplotlib > python setup.py install +.. note:: + + If you are on debian/ubuntu, you can get all the dependencies + required to build matplotlib with:: + + sudo apt-get build_dep python-matplotlib + + This does not build matplotlib, but it does get the install the + build dependencies, which will make building from svn easy. + + If you want to be able to follow the development branch as it changes just replace the last step with (Make sure you have **setuptools** installed):: @@ -116,9 +127,11 @@ > svn update -When you run `svn update`, if the output shows that only Python files have been updated, you are all set. -If C files have changed, you need to run the `python setupegg develop` command again to compile them. +When you run `svn update`, if the output shows that only Python files +have been updated, you are all set. If C files have changed, you need +to run the `python setupegg develop` command again to compile them. + There is more information on :ref:`using Subversion <using-svn>` in the developer docs. Modified: trunk/matplotlib/doc/users/installing.rst =================================================================== --- trunk/matplotlib/doc/users/installing.rst 2010-10-12 19:13:57 UTC (rev 8750) +++ trunk/matplotlib/doc/users/installing.rst 2010-10-13 15:45:14 UTC (rev 8751) @@ -131,6 +131,17 @@ development packages (look for a "-dev" postfix) in addition to the libraries themselves. +.. note:: + + If you are on debian/ubuntu, you can get all the dependencies + required to build matplotlib with:: + + sudo apt-get build_dep python-matplotlib + + This does not build matplotlib, but it does get the install the + build dependencies, which will make building from svn easy. + + :term:`python` 2.4 (or later but not python3) matplotlib requires python 2.4 or later (`download <http://www.python.org/download/>`__) This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |