SF.net SVN: matplotlib:[7048] trunk/matplotlib

[<lee...@us...>]

Revision: 7048
          http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7048&view=rev
Author:   leejjoon
Date:     2009-04-17 19:35:59 +0000 (Fri, 17 Apr 2009)

Log Message:
-----------
axes_grid toolkit initial check in

Modified Paths:
--------------
    trunk/matplotlib/CHANGELOG
    trunk/matplotlib/doc/users/toolkits.rst
    trunk/matplotlib/setup.py

Added Paths:
-----------
    trunk/matplotlib/doc/_static/demo_axes_grid.png
    trunk/matplotlib/doc/mpl_toolkits/
    trunk/matplotlib/doc/mpl_toolkits/axes_grid/
    trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures
    trunk/matplotlib/doc/mpl_toolkits/axes_grid/index.rst
    trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/
    trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axes_divider.rst
    trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/index.rst
    trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/overview.rst
    trunk/matplotlib/examples/axes_grid/
    trunk/matplotlib/examples/axes_grid/demo_axes_divider.py
    trunk/matplotlib/examples/axes_grid/demo_axes_grid.py
    trunk/matplotlib/examples/axes_grid/demo_axes_rgb.py
    trunk/matplotlib/examples/axes_grid/demo_fixed_size_axes.py
    trunk/matplotlib/examples/axes_grid/demo_image.py
    trunk/matplotlib/examples/axes_grid/demo_parasite_axes.py
    trunk/matplotlib/examples/axes_grid/demo_parasite_axes2.py
    trunk/matplotlib/examples/axes_grid/parasite_simple.py
    trunk/matplotlib/examples/axes_grid/parasite_simple2.py
    trunk/matplotlib/examples/axes_grid/scatter_hist.py
    trunk/matplotlib/examples/axes_grid/simple_anchored_artists.py
    trunk/matplotlib/examples/axes_grid/simple_axes_divider1.py
    trunk/matplotlib/examples/axes_grid/simple_axes_divider2.py
    trunk/matplotlib/examples/axes_grid/simple_axes_divider3.py
    trunk/matplotlib/examples/axes_grid/simple_axesgrid.py
    trunk/matplotlib/examples/axes_grid/simple_axesgrid2.py
    trunk/matplotlib/examples/axes_grid/simple_axisline.py
    trunk/matplotlib/examples/axes_grid/simple_axisline2.py
    trunk/matplotlib/examples/axes_grid/simple_axisline3.py
    trunk/matplotlib/examples/axes_grid/simple_axisline4.py
    trunk/matplotlib/examples/axes_grid/simple_rgb.py
    trunk/matplotlib/lib/mpl_toolkits/axes_grid/
    trunk/matplotlib/lib/mpl_toolkits/axes_grid/__init__.py
    trunk/matplotlib/lib/mpl_toolkits/axes_grid/anchored_artists.py
    trunk/matplotlib/lib/mpl_toolkits/axes_grid/axes_divider.py
    trunk/matplotlib/lib/mpl_toolkits/axes_grid/axes_grid.py
    trunk/matplotlib/lib/mpl_toolkits/axes_grid/axes_rgb.py
    trunk/matplotlib/lib/mpl_toolkits/axes_grid/axislines.py
    trunk/matplotlib/lib/mpl_toolkits/axes_grid/inset_locator.py
    trunk/matplotlib/lib/mpl_toolkits/axes_grid/parasite_axes.py

Modified: trunk/matplotlib/CHANGELOG
===================================================================
--- trunk/matplotlib/CHANGELOG	2009-04-17 16:34:09 UTC (rev 7047)
+++ trunk/matplotlib/CHANGELOG	2009-04-17 19:35:59 UTC (rev 7048)
@@ -1,5 +1,7 @@
 ======================================================================
 
+2009-04-17 Initial check-in of the axes_grid toolkit. - JJL
+
 2009-04-17 Added a support for bbox_to_anchor in
            offsetbox.AnchoredOffsetbox. Improved a documentation.
            - JJL

Added: trunk/matplotlib/doc/_static/demo_axes_grid.png
===================================================================
(Binary files differ)


Property changes on: trunk/matplotlib/doc/_static/demo_axes_grid.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures	                        (rev 0)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1 @@
+link ../../../examples/axes_grid/
\ No newline at end of file


Property changes on: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures
___________________________________________________________________
Added: svn:special
   + *

Added: trunk/matplotlib/doc/mpl_toolkits/axes_grid/index.rst
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/index.rst	                        (rev 0)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/index.rst	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,23 @@
+
+.. _toolkit_axesgrid-index:
+
+Matplotlib AxesGrid Toolkit
+===========================
+
+The matplotlib AxesGrid toolkit is a collection of helper classes to
+ease displaying multiple images in matplotlib.  While the aspect
+parameter in matplotlib adjust the position of the single axes,
+AxesGrid toolkit provides a framework to adjust the position of
+multiple axes according to their aspects. 
+
+.. plot:: mpl_toolkits/axes_grid/figures/demo_axes_grid.py
+
+
+Documentation
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   users/index.rst
+

Added: trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axes_divider.rst
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axes_divider.rst	                        (rev 0)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axes_divider.rst	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,89 @@
+AxesDivider
+===========
+
+The axes_divider module provide helper classes to adjust the axes
+positions of set of images in the drawing time.
+
+* *Size* This provides a classese of units that the size of each axes
+  will be determined. For example, you can specify a fixed size
+
+* *Divider* this is the class that is used calculates the axes
+  position. It divides the given renctangular area into several
+  areas. You intialize the divider by setting the horizontal and
+  vertical list of sizes that the division will be based on. You then
+  use the new_locator method, whose return value is a callable object
+  that can be used to set the axes_locator of the axes.
+
+
+You first initialize the divider by specifying its grids, i.e., horiz and vert.
+
+for example,::
+
+    rect = [0.2, 0.2, 0.6, 0.6]
+    horiz=[h0, h1, h2, h3]
+    vert=[v0, v1, v2]
+    divider = Divider(fig, rect, horiz, vert)
+
+where, rect is a bounds of the box that will be divided and h0,..h3,
+v0,..v2 need to be an callable object that returns a tuple of two
+floats. The first float is the relative size, and the second float is
+the absolute size. Use of the subclasses contained in the Size class
+is recommanded. Lets' consider a following grid.
+
++-----+-----+-----+-----+
+| v0  |     |     |     |
++-----+-----+-----+-----+
+| v1  |     |     |     |
++-----+-----+-----+-----+
+|h0,v2| h1  | h2  | h3  |
++-----+-----+-----+-----+
+
+
+* h0 => 2, 0
+* h1 => 0, 2
+* h2 => 0, 3
+
+The height of the bottom row is always 2 (axes_divider internally
+assumes that the unit is inch). The first and the second rows with
+height ration of 2:3. For example, if the total height of the grid 6,
+the the first and second row will each occupy 2/(2+3) and 3/(2+3) of
+(6-1) inches. The widths of columns (horiz) will be similarly
+determined. When aspect ratio is set, the total height (or width) will
+be adjusted accordingly.
+
+
+The Size class is a container class that contains several sub-class
+that can be used to set the horiz and vert. For example, for the
+vertical configuration above will be::
+
+  from Size import Fixed, Scaled
+  vert = [Fixed(2), Scaled(2), Scaled(3)]
+
+After you set up the divider object, you
+Then you create a locator instance which will be given to the axes.::
+
+     locator = divider.new_locator(nx=0, ny=1)
+     ax.set_axes_locator(locator)
+
+The return value of the new_locator method is a instance of the
+AxesLocator class. It is a callable object that will return the
+location and size of the cell at the first column and the second row.
+You may create a locator that spans over multiple cells.::
+
+     locator = divider.new_locator(nx=0, nx=2, ny=1)
+
+The above locator, when called, will return the position and size of
+the cells spanning the first and second column and the first row. You
+may consider it as [0:2, 1].
+
+See the example,
+
+.. plot:: mpl_toolkits/axes_grid/figures/simple_axes_divider2.py
+   :include-source:
+
+You can adjust the size of the each axes accroding to their x or y
+data limits (AxesX and AxesY), similar to the axes aspect parameter.
+
+.. plot:: mpl_toolkits/axes_grid/figures/simple_axes_divider3.py
+   :include-source:
+

Added: trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/index.rst
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/index.rst	                        (rev 0)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/index.rst	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,12 @@
+.. _axes_grid_users-guide-index:
+
+################################################
+  The Matplotlib AxesGrid Toolkit User's Guide
+################################################
+
+:Release: |version|
+:Date: |today|
+
+.. toctree::
+
+    overview.rst

Added: trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/overview.rst
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/overview.rst	                        (rev 0)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/overview.rst	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,349 @@
+=================
+AxesGrid Overview
+=================
+
+The matplotlib AxesGrid toolkit is a collection of helper classes,
+mainly to ease displaying (multiple) images in matplotlib.
+
+.. contents::
+   :depth: 1
+   :local:
+
+`AxesGrid`_, `RGB Axes`_ and `AxesDivider`_ are helper classes that
+deals with adjusting the location of (multiple) Axes, mainly for
+displaying images.  It provides a framework to adjust the position of
+multiple axes at the drawing time.  `ParasiteAxes`_ provides twinx(or
+twiny)-like features so that you can plot different data (e.g.,
+different y-scale) in a same Axes. `AxisLine`_ is a custom Axes
+class. Unlike default Axes in matpotlib, each axis (left, right, top
+and bottom) is associated with a separate artist (which is resposible
+to draw axis-line, ticks, ticklabels, label). `AnchoredArtists`_
+includes custom artists which are placed at some anchored position,
+like the legend.
+
+
+
+
+AxesGrid
+========
+
+
+A class that creates a grid of Axes. In matplotlib, the axes location
+(and size) is specified in the normalized figure coordinates. This may
+not be ideal for images that needs to be displayed with a given aspect
+ratio.  For example, displaying images of a same size with some fixed
+padding between them cannot be easily done in matplotlib. AxesGrid is
+used in such case.
+
+.. plot:: mpl_toolkits/axes_grid/figures/simple_axesgrid.py
+   :include-source:
+
+* The postion of each axes is determined at the drawing time (see
+  `AxesDivider`_), so that the size of the entire grid fits in the
+  given rectangle (like the aspec of axes). Note that in this example,
+  the paddings between axes are fixed even if you changes the figure
+  size.
+
+* axes in the same column has a same axes width (in figure
+  coordinate), and similarly, axes in the same row has a same
+  height. The widths (height) of the axes in the same row (column) are
+  scaled according to their view limits (xlim or ylim).
+
+  .. plot:: mpl_toolkits/axes_grid/figures/simple_axesgrid2.py
+     :include-source:
+
+* xaxis are shared among axes in a same column. Similarly, yaxis are
+  shared among axes in a same row. Therefore, changing axis properties
+  (view limits, tick location, etc. either by plot commands or using
+  your mouse in interactive backends) of one axes will affect all
+  other shared axes.
+
+
+
+When initialized, AxesGrid creates given number (*ngrids* or *ncols* *
+*nrows* if *ngrids* is None) of Axes instances. A sequence-like
+interface is provided to access the individual Axes instances (e.g.,
+grid[0] is the first Axes in the grid. See below for the order of
+axes).
+
+
+
+AxesGrid takes following arguments,
+
+
+ ============= ========   ================================================
+ Name          Default    Description
+ ============= ========   ================================================
+ fig
+ rect
+ nrows_ncols              number of rows and cols. e.g. (2,2)
+ ngrids        None       number of grids. nrows x ncols if None
+ direction     "row"      increasing direction of axes number. [row|column]
+ axes_pad      0.02       pad between axes in inches
+ add_all       True       Add axes to figures if True
+ share_all     False      xaxis & yaxis of all axes are shared if True
+ aspect        True       aspect of axes
+ label_mode    "L"        location of tick labels thaw will be displayed.
+                          "1" (only the lower left axes),
+                          "L" (left most and bottom most axes),
+                          or "all".
+ cbar_mode     None       [None|single|each]
+ cbar_location "right"    [right|top]
+ cbar_pad      None       pad between image axes and colorbar axes
+ cbar_size     "5%"       size of the colorbar
+ axes_class    None
+ ============= ========   ================================================
+
+ *rect*
+  specifies the location of the grid. You can either specify
+  coordinates of the rectangle to be used (e.g., (0.1, 0.1, 0.8, 0.8)
+  as in the Axes), or the subplot-like position (e.g., "121").
+
+ *direction*
+  means the increasing direction of the axes number.
+
+ *aspect*
+  By default (False), widths and heigths of axes in the grid are
+  scaled independently. If True, they are scaled according to their
+  data limits (similar to aspect parameter in mpl).
+
+ *share_all*
+  if True, xaxis  and yaxis of all axes are shared.
+
+ *direction*
+  direction of increasing axes number.   For "row",
+
+   +---------+---------+
+   | grid[0] | grid[1] |
+   +---------+---------+
+   | grid[2] | grid[3] |
+   +---------+---------+
+
+  For "column",
+
+   +---------+---------+
+   | grid[0] | grid[2] |
+   +---------+---------+
+   | grid[1] | grid[3] |
+   +---------+---------+
+
+You can also create a colorbar (or colobars). You can have colorbar
+for each axes (cbar_mode="each"), or you can have a single colorbar
+for the grid (cbar_mode="single"). The colorbar can be placed on your
+right, or top. The axes for each colorbar is stored as a *cbar_axes*
+attribute.
+
+
+
+The examples below show what you can do with AxesGrid.
+
+.. plot:: mpl_toolkits/axes_grid/figures/demo_axes_grid.py
+
+
+RGB Axes
+========
+
+RGBAxes is a helper clase to conveniently show RGB composite
+images. Like AxesGrid, the location of axes are adjusted so that the
+area occupied by them fits in a given rectangle.  Also, the xaxis and
+yaxis of each axes are shared. ::
+
+    from mpl_toolkits.axes_grid.axes_rgb import RGBAxes
+
+    fig = plt.figure(1)
+    ax = RGBAxes(fig, [0.1, 0.1, 0.8, 0.8])
+
+    r, g, b = get_rgb() # r,g,b are 2-d images
+    ax.imshow_rgb(r, g, b,
+                  origin="lower", interpolation="nearest")
+
+
+.. plot:: mpl_toolkits/axes_grid/figures/simple_rgb.py
+
+
+
+AxesDivider
+===========
+
+Behind the scene, the AxesGrid class and the RGBAxes class utilize the
+AxesDivider class, whose role is to calculate the location of the axes
+at drawing time. While a more about the AxesDivider is (will be)
+explained in (yet to be written) AxesDividerGuide, direct use of the
+AxesDivider class will not be necessary for most users.  The
+axes_divider module provides a helper function make_axes_locatable,
+which can be useful. It takes a exisitng axes instance and create a
+divider for it. ::
+
+	ax = subplot(1,1,1)
+	divider = make_axes_locatable(ax)
+
+
+
+
+*make_axes_locatable* returns an isntance of the AxesLocator class,
+derived from the Locator. It has *new_vertical*, and *new_horizontal*
+methods. The *new_vertical* (*new_horizontal*) creates a new axes on
+the upper (right) side of the original axes.
+
+
+scatter_hist.py with AxesDivider
+--------------------------------
+
+The "scatter_hist.py" example in mpl can be rewritten using
+*make_axes_locatable*. ::
+
+    from mpl_toolkits.axes_grid import make_axes_locatable
+
+    axScatter = subplot(111)
+    divider = make_axes_locatable(axScatter)
+
+    # create new axes on the right and on the top of the current axes
+    # The first argument of the new_vertical(new_horizontal) method is
+    # the height (width) of the axes to be created in inches.
+    axHistx = divider.new_vertical(1.2, pad=0.1, sharex=axScatter)
+    axHisty = divider.new_horizontal(1.2, pad=0.1, sharey=axScatter)
+
+    fig.add_axes(axHistx)
+    fig.add_axes(axHisty)
+
+
+    # the scatter plot:
+    axScatter.scatter(x, y)
+    axScatter.set_aspect(1.)
+
+    # histograms
+    bins = np.arange(-lim, lim + binwidth, binwidth)
+    axHistx.hist(x, bins=bins)
+    axHisty.hist(y, bins=bins, orientation='horizontal')
+
+See the full source code below.
+
+
+.. plot:: mpl_toolkits/axes_grid/figures/scatter_hist.py
+
+
+The scatter_hist using the AxesDivider has some advantage over the
+original scatter_hist.py in mpl. For example, you can set the aspect
+ratio of the scatter plot, even with the x-axis or y-axis is shared
+accordingly.
+
+
+ParasiteAxes
+============
+
+The ParasiteAxes is a axes whose location is identical to its host
+axes. The location is adjusted in the drawing time, thus it works even
+if the host change its location (e.g., images). It provides *twinx*,
+*twiny* (similar to twinx and twiny in the matplotlib). Also it
+provides *twin*, which takes an arbitraty tranfromation that maps
+between the data coordinates of the host and the parasite axes.
+Artists in each axes are mergred and drawn acrroding to their zorder.
+It also modifies some behavior of the axes. For example, color cycle
+for plot lines are shared between host and parasites. Also, the legend
+command in host, creates a legend that includes lines in the parasite
+axes.
+
+Example 1. twinx
+----------------
+
+.. plot:: mpl_toolkits/axes_grid/figures/parasite_simple.py
+   :include-source:
+
+Example 2. twin
+---------------
+
+A more sophiscated example using twin. Note that if you change the
+x-limit in the host axes, the x-limit of the parasite axes will change
+accordingly.
+
+
+.. plot:: mpl_toolkits/axes_grid/figures/parasite_simple2.py
+
+
+
+AxisLine
+========
+
+AxisLine is a custom (and very experimenta) Axes class, where each
+axis (left, right, top and bottom) have a separate artist associated
+(which is resposible to draw axis-line, ticks, ticklabels, label).
+Also, you can create your own axis, which can pass through a fixed
+position in the axes coordinate, or a fixed position in the data
+coordinate (i.e., the axis floats around when viewlimit changes).
+
+Most of the class in this toolkit is based on this class. And it has
+not been tested extensibly. You may go back to the original mpl
+behanvior, by ::
+
+  ax.toggle_axisline(False)
+
+The axes class, by default, provides 4 artists which are responsible
+to draw axis in "left","right","bottom" and "top". They are accessed
+as ax.axis["left"], ax.axis["right"], and so on, i.e., ax.axis is a
+dictionary that contains artists (note that ax.axis is still a
+callable methods and it behaves as an original Axes.axis method in
+mpl).
+
+For example, you can hide right, and top axis by ::
+
+  ax.axis["right"].set_visible(False)
+  ax.axis["top"].set_visible(False)
+
+
+.. plot:: mpl_toolkits/axes_grid/figures/simple_axisline3.py
+
+
+SubplotZero gives you two more additional (floating?) axis of x=0 and
+y=0 (in data coordinate)
+
+.. plot:: mpl_toolkits/axes_grid/figures/simple_axisline2.py
+   :include-source:
+
+
+Axisline with ParasiteAxes
+--------------------------
+
+Most of axes class in the axes_grid toolkit, including ParasiteAxes,
+is based on the Axisline axes. The combination of the two can be
+useful in some case. For example, you can have different tick-location,
+tick-label, or tick-formatter for bottom and top (or left and right)
+axis. ::
+
+  ax2 = ax.twin() # now, ax2 is responsible for "top" axis and "right" axis
+  ax2.set_xticks([0., .5*np.pi, np.pi, 1.5*np.pi, 2*np.pi])
+  ax2.set_xticklabels(["0", r"$\frac{1}{2}\pi$",
+                       r"$\pi$", r"$\frac{3}{2}\pi$", r"$2\pi$"])
+
+
+.. plot:: mpl_toolkits/axes_grid/figures/simple_axisline4.py
+
+
+AxisLine Axes lets you create a custom axis, ::
+
+    # make new (right-side) yaxis, but wth some offset
+    offset = (20, 0)
+    new_axisline = ax.get_grid_helper().new_fixed_axis
+    ax.axis["right2"] = new_axisline(loc="right",
+                                     offset=offset)
+
+
+And, you can use it with parasiteAxes.
+
+
+.. plot:: mpl_toolkits/axes_grid/figures/demo_parasite_axes2.py
+
+
+AnchoredArtists
+===============
+
+It's a collection of artists whose location is anchored to the (axes)
+bbox, like the legend. It is derived from *OffsetBox* in mpl, and
+artist need to be drawn in the canvas coordinate. But, there is a
+limited support for an arbitrary transform. For example, the ellipse
+in the example below will have width and height in the data
+coordinate.
+
+.. plot:: mpl_toolkits/axes_grid/figures/simple_anchored_artists.py
+   :include-source:
+
+

Modified: trunk/matplotlib/doc/users/toolkits.rst
===================================================================
--- trunk/matplotlib/doc/users/toolkits.rst	2009-04-17 16:34:09 UTC (rev 7047)
+++ trunk/matplotlib/doc/users/toolkits.rst	2009-04-17 19:35:59 UTC (rev 7048)
@@ -53,3 +53,17 @@
 line, mesh) tools.  Not the fastest or feature complete 3D library out
 there, but ships with matplotlib and thus may be a lighter weight
 solution for some use cases.
+
+
+.. _toolkit_axes_grid:
+
+AxesGrid
+========
+
+The matplotlib AxesGrid toolkit is a collection of helper classes to
+ease displaying multiple images in matplotlib. The AxesGrid toolkit is
+distributed with matplotlib source.
+
+.. image:: ../_static/demo_axes_grid.png
+
+See :ref:`toolkit_axesgrid-index` for documentations.

Added: trunk/matplotlib/examples/axes_grid/demo_axes_divider.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/demo_axes_divider.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/demo_axes_divider.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,124 @@
+import matplotlib.pyplot as plt
+from demo_image import get_demo_image
+#import mpl_toolkits.imaging.axes_grid as imaging
+
+def demo_simple_image(ax):
+    Z, extent = get_demo_image()
+
+    im = ax.imshow(Z, extent=extent, interpolation="nearest")
+    cb = plt.colorbar(im)
+    plt.setp(cb.ax.get_yticklabels(), visible=False)
+
+
+def demo_locatable_axes_hard(fig1):
+
+    from mpl_toolkits.axes_grid \
+         import SubplotDivider, LocatableAxes, Size
+
+    divider = SubplotDivider(fig1, 2, 2, 2, aspect=True)
+
+    # axes for image
+    ax = LocatableAxes(fig1, divider.get_position())
+
+    # axes for coloarbar
+    ax_cb = LocatableAxes(fig1, divider.get_position())
+
+    h = [Size.AxesX(ax), # main axes
+         Size.Fixed(0.05), # padding, 0.1 inch
+         Size.Fixed(0.2), # colorbar, 0.3 inch
+         ]
+
+    v = [Size.AxesY(ax)]
+
+    divider.set_horizontal(h)
+    divider.set_vertical(v)
+
+    ax.set_axes_locator(divider.new_locator(nx=0, ny=0))
+    ax_cb.set_axes_locator(divider.new_locator(nx=2, ny=0))
+
+    fig1.add_axes(ax)
+    fig1.add_axes(ax_cb)
+
+    ax_cb.axis["left"].toggle(all=False)
+    ax_cb.axis["right"].toggle(ticks=True)
+
+    Z, extent = get_demo_image()
+
+    im = ax.imshow(Z, extent=extent, interpolation="nearest")
+    plt.colorbar(im, cax=ax_cb)
+    plt.setp(ax_cb.get_yticklabels(), visible=False)
+
+
+def demo_locatable_axes_easy(ax):
+    from mpl_toolkits.axes_grid import make_axes_locatable
+
+    divider = make_axes_locatable(ax)
+
+    ax_cb = divider.new_horizontal(size="5%", pad=0.05)
+    fig1 = ax.get_figure()
+    fig1.add_axes(ax_cb)
+
+    Z, extent = get_demo_image()
+    im = ax.imshow(Z, extent=extent, interpolation="nearest")
+
+    plt.colorbar(im, cax=ax_cb)
+    ax_cb.yaxis.tick_right()
+    for tl in ax_cb.get_yticklabels():
+        tl.set_visible(False)
+    ax_cb.yaxis.tick_right()
+
+
+def demo_images_side_by_sied(ax):
+    from mpl_toolkits.axes_grid import make_axes_locatable
+
+    divider = make_axes_locatable(ax)
+
+    Z, extent = get_demo_image()
+    ax2 = divider.new_horizontal(size="100%", pad=0.05)
+    fig1 = ax.get_figure()
+    fig1.add_axes(ax2)
+
+    ax.imshow(Z, extent=extent, interpolation="nearest")
+    ax2.imshow(Z, extent=extent, interpolation="nearest")
+    for tl in ax2.get_yticklabels():
+        tl.set_visible(False)
+
+
+def demo():
+
+    fig1 = plt.figure(1, (6, 6))
+    fig1.clf()
+
+    ## PLOT 1
+    # simple image & colorbar
+    ax = fig1.add_subplot(2, 2, 1)
+    demo_simple_image(ax)
+
+    ## PLOT 2
+    # image and colorbar whose location is adjusted in the drawing time.
+    # a hard way
+
+    demo_locatable_axes_hard(fig1)
+
+
+    ## PLOT 3
+    # image and colorbar whose location is adjusted in the drawing time.
+    # a easy way
+
+    ax = fig1.add_subplot(2, 2, 3)
+    demo_locatable_axes_easy(ax)
+
+
+    ## PLOT 4
+    # two images side by sied with fixed padding.
+
+    ax = fig1.add_subplot(2, 2, 4)
+    demo_images_side_by_sied(ax)
+
+    plt.draw()
+    plt.show()
+
+
+
+if __name__ == "__main__":
+   demo()

Added: trunk/matplotlib/examples/axes_grid/demo_axes_grid.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/demo_axes_grid.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/demo_axes_grid.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,87 @@
+import matplotlib.pyplot as plt
+from demo_image import get_demo_image
+from mpl_toolkits.axes_grid import AxesGrid
+
+
+def demo_simple_grid(fig):
+    """
+    A grid of 2x2 images with 0.05 inch pad between images and only
+    the lower-left axes is labeld.
+    """
+    grid = AxesGrid(fig, 131, # similar to subplot(131)
+                    nrows_ncols = (2, 2),
+                    axes_pad = 0.05,
+                    label_mode = "1",
+                    )
+
+    Z, extent = get_demo_image()
+    for i in range(4):
+        im = grid[i].imshow(Z, extent=extent, interpolation="nearest")
+
+    # This only affects axes in first column and second row as share_all = False.
+    grid.axes_llc.set_xticks([-2, 0, 2])
+    grid.axes_llc.set_yticks([-2, 0, 2])
+
+
+def demo_grid_with_single_cbar(fig):
+    """
+    A grid of 2x2 images with a single colobar
+    """
+    grid = AxesGrid(fig, 132, # similar to subplot(132)
+                    nrows_ncols = (2, 2),
+                    axes_pad = 0.0,
+                    share_all=True,
+                    label_mode = "L",
+                    cbar_mode="single",
+                    )
+
+    Z, extent = get_demo_image()
+    for i in range(4):
+        im = grid[i].imshow(Z, extent=extent, interpolation="nearest")
+    plt.colorbar(im, cax = grid.cbar_axes[0])
+    grid.cbar_axes[0].colorbar(im)
+
+    # This affects all axes as share_all = True.
+    grid.axes_llc.set_xticks([-2, 0, 2])
+    grid.axes_llc.set_yticks([-2, 0, 2])
+
+
+def demo_grid_with_each_cbar(fig):
+    """
+    A grid of 2x2 images. Each image has its own colobar.
+    """
+
+    grid = AxesGrid(F, 133, # similar to subplot(122)
+                    nrows_ncols = (2, 2),
+                    axes_pad = 0.1,
+                    label_mode = "1",
+                    share_all = True,
+                    cbar_location="top",
+                    cbar_mode="each",
+                    cbar_size="7%",
+                    cbar_pad="2%",
+                    )
+    Z, extent = get_demo_image()
+    for i in range(4):
+        im = grid[i].imshow(Z, extent=extent, interpolation="nearest")
+        grid.cbar_axes[i].colorbar(im)
+
+    # This affects all axes because we set share_all = True.
+    grid.axes_llc.set_xticks([-2, 0, 2])
+    grid.axes_llc.set_yticks([-2, 0, 2])
+
+
+
+if __name__ == "__main__":
+
+    F = plt.figure(1, (5.5, 2.5))
+
+    F.subplots_adjust(left=0.05, right=0.98)
+
+    demo_simple_grid(F)
+    demo_grid_with_single_cbar(F)
+    demo_grid_with_each_cbar(F)
+
+    plt.draw()
+    plt.show()
+

Added: trunk/matplotlib/examples/axes_grid/demo_axes_rgb.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/demo_axes_rgb.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/demo_axes_rgb.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,82 @@
+import numpy as np
+import matplotlib.pyplot as plt
+
+from demo_axes_divider import get_demo_image
+from mpl_toolkits.axes_grid.axes_rgb import make_rgb_axes, RGBAxes
+
+def get_rgb():
+    Z, extent = get_demo_image()
+
+    Z[Z<0] = 0.
+    Z = Z/Z.max()
+
+    R = Z[:13,:13]
+    G = Z[2:,2:]
+    B = Z[:13,2:]
+
+    return R, G, B
+
+
+def make_cube(r, g, b):
+    ny, nx = r.shape
+    R = np.zeros([ny, nx, 3], dtype="d")
+    R[:,:,0] = r
+    G = np.zeros_like(R)
+    G[:,:,1] = g
+    B = np.zeros_like(R)
+    B[:,:,2] = b
+
+    RGB = R + G + B
+
+    return R, G, B, RGB
+
+
+
+def demo_rgb():
+    fig = plt.figure(1)
+    fig.clf()
+
+    ax = fig.add_subplot(111)
+    ax_r, ax_g, ax_b = make_rgb_axes(ax, pad=0.02)
+    #fig.add_axes(ax_r)
+    #fig.add_axes(ax_g)
+    #fig.add_axes(ax_b)
+
+    r, g, b = get_rgb()
+    im_r, im_g, im_b, im_rgb = make_cube(r, g, b)
+    kwargs = dict(origin="lower", interpolation="nearest")
+    ax.imshow(im_rgb, **kwargs)
+    ax_r.imshow(im_r, **kwargs)
+    ax_g.imshow(im_g, **kwargs)
+    ax_b.imshow(im_b, **kwargs)
+
+
+
+
+def demo_rgb2():
+    fig = plt.figure(2)
+    ax = RGBAxes(fig, [0.1, 0.1, 0.8, 0.8], pad=0.0)
+    #fig.add_axes(ax)
+    #ax.add_RGB_to_figure()
+
+    r, g, b = get_rgb()
+    kwargs = dict(origin="lower", interpolation="nearest")
+    ax.imshow_rgb(r, g, b, **kwargs)
+
+    ax.RGB.set_xlim(0., 9.5)
+    ax.RGB.set_ylim(0.9, 10.6)
+
+    for ax1 in [ax.RGB, ax.R, ax.G, ax.B]:
+        for axisline in ax1._axislines.values():
+            axisline.line.set_color("w")
+            axisline.major_ticks.set_mec("w")
+
+    return ax
+
+
+if __name__ == "__main__":
+    demo_rgb()
+    ax = demo_rgb2()
+
+    plt.draw()
+    plt.show()

Added: trunk/matplotlib/examples/axes_grid/demo_fixed_size_axes.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/demo_fixed_size_axes.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/demo_fixed_size_axes.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,57 @@
+import matplotlib.pyplot as plt
+
+from mpl_toolkits.axes_grid \
+     import Divider, LocatableAxes, Size
+
+def demo_fixed_size_axes():
+
+    fig1 = plt.figure(1, (6, 6))
+
+    # The first items are for padding and the second items are for the axes.
+    # sizes are in inch.
+    h = [Size.Fixed(1.0), Size.Fixed(4.5)]
+    v = [Size.Fixed(0.7), Size.Fixed(5.)]
+
+    divider = Divider(fig1, (0.0, 0.0, 1., 1.), h, v, aspect=False)
+    # the width and height of the rectangle is ignored.
+
+    ax = LocatableAxes(fig1, divider.get_position())
+    ax.set_axes_locator(divider.new_locator(nx=1, ny=1))
+
+    fig1.add_axes(ax)
+
+    ax.plot([1,2,3])
+
+
+
+
+def demo_fixed_pad_axes():
+
+    fig = plt.figure(2, (6, 6))
+
+    # The first & third items are for padding and the second items are for the axes.
+    # sizes are in inch.
+    h = [Size.Fixed(1.0), Size.Scaled(1.), Size.Fixed(.2),]
+    v = [Size.Fixed(0.7), Size.Scaled(1.), Size.Fixed(.5),]
+
+    divider = Divider(fig, (0.0, 0.0, 1., 1.), h, v, aspect=False)
+    # the width and height of the rectangle is ignored.
+
+    ax = LocatableAxes(fig, divider.get_position())
+    ax.set_axes_locator(divider.new_locator(nx=1, ny=1))
+
+    fig.add_axes(ax)
+
+    ax.plot([1,2,3])
+
+
+
+
+
+
+if __name__ == "__main__":
+    demo_fixed_size_axes()
+    demo_fixed_pad_axes()
+
+    plt.draw()
+    plt.show()

Added: trunk/matplotlib/examples/axes_grid/demo_image.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/demo_image.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/demo_image.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,17 @@
+import numpy as np
+
+def get_demo_image():
+    # prepare image
+    delta = 0.5
+
+    extent = (-3,4,-4,3)
+    x = np.arange(-3.0, 4.001, delta)
+    y = np.arange(-4.0, 3.001, delta)
+    X, Y = np.meshgrid(x, y)
+    import matplotlib.mlab as mlab
+    Z1 = mlab.bivariate_normal(X, Y, 1.0, 1.0, 0.0, 0.0)
+    Z2 = mlab.bivariate_normal(X, Y, 1.5, 0.5, 1, 1)
+    Z = (Z1 - Z2) * 10
+
+    return Z, extent
+

Added: trunk/matplotlib/examples/axes_grid/demo_parasite_axes.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/demo_parasite_axes.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/demo_parasite_axes.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,53 @@
+from mpl_toolkits.axes_grid.parasite_axes import HostAxes, ParasiteAxes
+import matplotlib.pyplot as plt
+
+if __name__ == "__main__":
+    fig = plt.figure(1)
+
+    host = HostAxes(fig, [0.15, 0.1, 0.65, 0.8])
+    par1 = ParasiteAxes(host, sharex=host)
+    par2 = ParasiteAxes(host, sharex=host)
+    host.parasites.append(par1)
+    host.parasites.append(par2)
+
+    host.set_ylabel("Density")
+    host.set_xlabel("Distance")
+
+    host.axis["right"].set_visible(False)
+    par1.axis["right"].set_visible(True)
+    par1.set_ylabel("Temperature")
+
+    par1.axis["right"].major_ticklabels.set_visible(True)
+    par1.axis["right"].label.set_visible(True)
+
+    par2.set_ylabel("Velocity")
+    offset = (60, 0)
+    new_axisline = par2._grid_helper.new_axisline
+    par2.axis["right2"] = new_axisline(loc="right",
+                                       offset=offset)
+
+
+    fig.add_axes(host)
+
+    host.set_xlim(0, 2)
+    host.set_ylim(0, 2)
+
+    host.set_xlabel("Distance")
+    host.set_ylabel("Density")
+    par1.set_ylabel("Temperature")
+
+    p1, = host.plot([0, 1, 2], [0, 1, 2], label="Density")
+    p2, = par1.plot([0, 1, 2], [0, 3, 2], label="Temperature")
+    p3, = par2.plot([0, 1, 2], [50, 30, 15], label="Velocity")
+
+    par1.set_ylim(0, 4)
+    par2.set_ylim(1, 65)
+
+    host.legend()
+
+    host.axis["left"].label.set_color(p1.get_color())
+    par1.axis["right"].label.set_color(p2.get_color())
+    par2.axis["right2"].label.set_color(p3.get_color())
+
+    plt.draw()
+    plt.show()

Added: trunk/matplotlib/examples/axes_grid/demo_parasite_axes2.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/demo_parasite_axes2.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/demo_parasite_axes2.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,54 @@
+from mpl_toolkits.axes_grid.parasite_axes import SubplotHost
+import matplotlib.transforms as mtransforms
+import matplotlib.pyplot as plt
+
+if 1:
+    fig = plt.figure(1)
+
+    host = SubplotHost(fig, 111)
+
+    host.set_ylabel("Density")
+    host.set_xlabel("Distance")
+
+    par1 = host.twinx()
+    par2 = host.twinx()
+
+    par1.set_ylabel("Temperature")
+
+    par2.axis["right"].set_visible(False)
+
+    offset = 60, 0
+    new_axisline = par2.get_grid_helper().new_fixed_axis
+    par2.axis["right2"] = new_axisline(loc="right",
+                                       offset=offset)
+
+    par2.axis["right2"].label.set_visible(True)
+    par2.axis["right2"].set_label("Velocity")
+
+    fig.add_axes(host)
+    plt.subplots_adjust(right=0.75)
+
+    host.set_xlim(0, 2)
+    host.set_ylim(0, 2)
+
+    host.set_xlabel("Distance")
+    host.set_ylabel("Density")
+    par1.set_ylabel("Temperature")
+
+    p1, = host.plot([0, 1, 2], [0, 1, 2], label="Density")
+    p2, = par1.plot([0, 1, 2], [0, 3, 2], label="Temperature")
+    p3, = par2.plot([0, 1, 2], [50, 30, 15], label="Velocity")
+
+    par1.set_ylim(0, 4)
+    par2.set_ylim(1, 65)
+
+    host.legend()
+
+    host.axis["left"].label.set_color(p1.get_color())
+    par1.axis["right"].label.set_color(p2.get_color())
+    par2.axis["right2"].label.set_color(p3.get_color())
+
+    plt.draw()
+    plt.show()
+
+    #plt.savefig("Test")

Added: trunk/matplotlib/examples/axes_grid/parasite_simple.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/parasite_simple.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/parasite_simple.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,24 @@
+from mpl_toolkits.axes_grid.parasite_axes import SubplotHost
+import matplotlib.pyplot as plt
+
+fig = plt.figure(1)
+
+host = SubplotHost(fig, 111)
+fig.add_subplot(host)
+
+par = host.twinx()
+
+host.set_xlabel("Distance")
+host.set_ylabel("Density")
+par.set_ylabel("Temperature")
+
+p1, = host.plot([0, 1, 2], [0, 1, 2], label="Density")
+p2, = par.plot([0, 1, 2], [0, 3, 2], label="Temperature")
+
+host.axis["left"].label.set_color(p1.get_color())
+par.axis["right"].label.set_color(p2.get_color())
+
+host.legend()
+
+plt.show()
+

Added: trunk/matplotlib/examples/axes_grid/parasite_simple2.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/parasite_simple2.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/parasite_simple2.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,42 @@
+import matplotlib.transforms as mtransforms
+import matplotlib.pyplot as plt
+from mpl_toolkits.axes_grid.parasite_axes import SubplotHost
+
+obs = [["01_S1", 3.88, 0.14, 1970, 63],
+       ["01_S4", 5.6, 0.82, 1622, 150],
+       ["02_S1", 2.4, 0.54, 1570, 40],
+       ["03_S1", 4.1, 0.62, 2380, 170]]
+
+
+fig = plt.figure()
+
+ax_kms = SubplotHost(fig, 1,1,1, aspect=1.)
+
+# angular proper motion("/yr) to linear velocity(km/s) at distance=2.3kpc
+pm_to_kms = 1./206265.*2300*3.085e18/3.15e7/1.e5
+
+aux_trans = mtransforms.Affine2D().scale(pm_to_kms, 1.)
+ax_pm = ax_kms.twin(aux_trans)
+ax_pm.set_viewlim_mode("transform")
+
+fig.add_subplot(ax_kms)
+
+for n, ds, dse, w, we in obs:
+    time = ((2007+(10. + 4/30.)/12)-1988.5)
+    v = ds / time * pm_to_kms
+    ve = dse / time * pm_to_kms
+    ax_kms.errorbar([v], [w], xerr=[ve], yerr=[we], color="k")
+
+
+ax_kms.axis["bottom"].set_label("Linear velocity at 2.3 kpc [km/s]")
+ax_kms.axis["left"].set_label("FWHM [km/s]")
+ax_pm.axis["top"].set_label("Proper Motion [$^{''}$/yr]")
+ax_pm.axis["top"].label.set_visible(True)
+ax_pm.axis["right"].major_ticklabels.set_visible(False)
+
+ax_kms.set_xlim(950, 3700)
+ax_kms.set_ylim(950, 3100)
+# xlim and ylim of ax_pms will be automatically adjusted.
+
+plt.draw()
+plt.show()

Added: trunk/matplotlib/examples/axes_grid/scatter_hist.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/scatter_hist.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/scatter_hist.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,60 @@
+import numpy as np
+import matplotlib.pyplot as plt
+
+# the random data
+x = np.random.randn(1000)
+y = np.random.randn(1000)
+
+
+fig = plt.figure(1, figsize=(5.5,5.5))
+
+from mpl_toolkits.axes_grid import make_axes_locatable
+
+axScatter = plt.subplot(111)
+divider = make_axes_locatable(axScatter)
+
+# create a new axes with a height of 1.2 inch above the axScatter
+axHistx = divider.new_vertical(1.2, pad=0.1, sharex=axScatter)
+
+# create a new axes with a width of 1.2 inch on the right side of the
+# axScatter
+axHisty = divider.new_horizontal(1.2, pad=0.1, sharey=axScatter)
+
+fig.add_axes(axHistx)
+fig.add_axes(axHisty)
+
+
+# make some labels invisible
+plt.setp(axHistx.get_xticklabels() + axHisty.get_yticklabels(),
+         visible=False)
+
+# the scatter plot:
+axScatter.scatter(x, y)
+axScatter.set_aspect(1.)
+
+# now determine nice limits by hand:
+binwidth = 0.25
+xymax = np.max( [np.max(np.fabs(x)), np.max(np.fabs(y))] )
+lim = ( int(xymax/binwidth) + 1) * binwidth
+
+bins = np.arange(-lim, lim + binwidth, binwidth)
+axHistx.hist(x, bins=bins)
+axHisty.hist(y, bins=bins, orientation='horizontal')
+
+# the xaxis of axHistx and yaxis of axHisty are shared with axScatter,
+# thus there is no need to manually adjust the xlim and ylim of these
+# axis.
+
+#axHistx.axis["bottom"].major_ticklabels.set_visible(False)
+for tl in axHistx.get_xticklabels():
+    tl.set_visible(False)
+axHistx.set_yticks([0, 50, 100])
+
+#axHisty.axis["left"].major_ticklabels.set_visible(False)
+for tl in axHisty.get_yticklabels():
+    tl.set_visible(False)
+axHisty.set_xticks([0, 50, 100])
+
+plt.draw()
+#plt.show()
+plt.savefig("a.pdf")

Added: trunk/matplotlib/examples/axes_grid/simple_anchored_artists.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/simple_anchored_artists.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/simple_anchored_artists.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,60 @@
+import matplotlib.pyplot as plt
+
+
+def draw_text(ax):
+    from mpl_toolkits.axes_grid.anchored_artists import AnchoredText
+    at = AnchoredText("Figure 1a",
+                      loc=2, prop=dict(size=8), frameon=True,
+                      )
+    at.patch.set_boxstyle("round,pad=0.,rounding_size=0.2")
+    ax.add_artist(at)
+
+    at2 = AnchoredText("Figure 1(b)",
+                       loc=3, prop=dict(size=8), frameon=True,
+                       bbox_to_anchor=(0., 1.)
+                       )
+    at2.patch.set_boxstyle("round,pad=0.,rounding_size=0.2")
+    ax.add_artist(at2)
+
+def draw_circle(ax): # circle in the canvas coordinate
+    from mpl_toolkits.axes_grid.anchored_artists import AnchoredDrawingArea
+    from matplotlib.patches import Circle
+    ada = AnchoredDrawingArea(20, 20, 0, 0,
+                              loc=1, pad=0., frameon=False)
+    p = Circle((10, 10), 10)
+    ada.da.add_artist(p)
+    ax.add_artist(ada)
+
+def draw_ellipse(ax):
+    from mpl_toolkits.axes_grid.anchored_artists import AnchoredEllipse
+    # draw an ellipse of width=0.1, height=0.15 in the data coordinate
+    ae = AnchoredEllipse(ax.transData, width=0.1, height=0.15, angle=0.,
+                         loc=3, pad=0.5, borderpad=0.4, frameon=True)
+
+    ax.add_artist(ae)
+
+def draw_sizebar(ax):
+    from mpl_toolkits.axes_grid.anchored_artists import AnchoredSizeBar
+    # draw a horizontal bar with length of 0.1 in Data coordinate
+    # (ax.transData) with a label underneath.
+    as =  AnchoredSizeBar(ax.transData,
+                          0.1,
+                          r"1$^{\prime}$",
+                          loc=8,
+                          pad=0.1, borderpad=0.5, sep=5,
+                          frameon=False)
+    ax.add_artist(as)
+
+
+if 1:
+    ax = plt.gca()
+    ax.set_aspect(1.)
+
+    draw_text(ax)
+    draw_circle(ax)
+    draw_ellipse(ax)
+    draw_sizebar(ax)
+
+    plt.show()
+
+

Added: trunk/matplotlib/examples/axes_grid/simple_axes_divider1.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/simple_axes_divider1.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/simple_axes_divider1.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,30 @@
+from mpl_toolkits.axes_grid import Size, Divider
+import matplotlib.pyplot as plt
+
+
+fig1 = plt.figure(1, (6, 6))
+
+# fixed size in inch
+horiz = [Size.Fixed(1.), Size.Fixed(.5), Size.Fixed(1.5),
+         Size.Fixed(.5)] 
+vert = [Size.Fixed(1.5), Size.Fixed(.5), Size.Fixed(1.)]
+
+rect = (0.1, 0.1, 0.8, 0.8)
+# divide the axes rectangle into grid whose size is specified by horiz * vert
+divider = Divider(fig1, rect, horiz, vert, aspect=False)
+
+# the rect parameter will be ignore as we will set axes_locator
+ax1 = fig1.add_axes(rect, label="1")
+ax2 = fig1.add_axes(rect, label="2")
+ax3 = fig1.add_axes(rect, label="3")
+ax4 = fig1.add_axes(rect, label="4")
+
+ax1.set_axes_locator(divider.new_locator(nx=0, ny=0))
+ax2.set_axes_locator(divider.new_locator(nx=0, ny=2))
+ax3.set_axes_locator(divider.new_locator(nx=2, ny=2))
+ax4.set_axes_locator(divider.new_locator(nx=2, nx1=4, ny=0))
+
+
+
+plt.draw()
+plt.show()

Added: trunk/matplotlib/examples/axes_grid/simple_axes_divider2.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/simple_axes_divider2.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/simple_axes_divider2.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,28 @@
+from mpl_toolkits.axes_grid import Size, Divider
+import matplotlib.pyplot as plt
+
+fig1 = plt.figure(1, (5.5, 4.))
+
+# the rect parameter will be ignore as we will set axes_locator
+rect = (0.1, 0.1, 0.8, 0.8)
+ax = [fig1.add_axes(rect, label="%d"%i) for i in range(4)]
+
+horiz = [Size.Scaled(1.5), Size.Fixed(.5), Size.Scaled(1.),
+         Size.Scaled(.5)]
+
+vert = [Size.Scaled(1.), Size.Fixed(.5), Size.Scaled(1.5)]
+
+# divide the axes rectangle into grid whose size is specified by horiz * vert
+divider = Divider(fig1, rect, horiz, vert, aspect=False)
+
+ax[0].set_axes_locator(divider.new_locator(nx=0, ny=0))
+ax[1].set_axes_locator(divider.new_locator(nx=0, ny=2))
+ax[2].set_axes_locator(divider.new_locator(nx=2, ny=2))
+ax[3].set_axes_locator(divider.new_locator(nx=2, nx1=4, ny=0))
+
+for ax1 in ax:
+    plt.setp(ax1.get_xticklabels()+ax1.get_yticklabels(),
+             visible=False)
+
+plt.draw()
+plt.show()

Added: trunk/matplotlib/examples/axes_grid/simple_axes_divider3.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/simple_axes_divider3.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/simple_axes_divider3.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,37 @@
+from mpl_toolkits.axes_grid import Size, Divider
+import matplotlib.pyplot as plt
+
+
+fig1 = plt.figure(1, (5.5, 4))
+
+# the rect parameter will be ignore as we will set axes_locator
+rect = (0.1, 0.1, 0.8, 0.8)
+ax = [fig1.add_axes(rect, label="%d"%i) for i in range(4)]
+
+
+horiz = [Size.AxesX(ax[0]), Size.Fixed(.5), Size.AxesX(ax[1])]
+vert = [Size.AxesY(ax[0]), Size.Fixed(.5), Size.AxesY(ax[2])]
+
+# divide the axes rectangle into grid whose size is specified by horiz * vert
+divider = Divider(fig1, rect, horiz, vert, aspect=False)
+
+
+ax[0].set_axes_locator(divider.new_locator(nx=0, ny=0))
+ax[1].set_axes_locator(divider.new_locator(nx=2, ny=0))
+ax[2].set_axes_locator(divider.new_locator(nx=0, ny=2))
+ax[3].set_axes_locator(divider.new_locator(nx=2, ny=2))
+
+ax[0].set_xlim(0, 2)
+ax[1].set_xlim(0, 1)
+
+ax[0].set_ylim(0, 1)
+ax[2].set_ylim(0, 2)
+
+divider.set_aspect(1.)
+
+for ax1 in ax:
+    plt.setp(ax1.get_xticklabels()+ax1.get_yticklabels(),
+             visible=False)
+
+plt.draw()
+plt.show()

Added: trunk/matplotlib/examples/axes_grid/simple_axesgrid.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/simple_axesgrid.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/simple_axesgrid.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,17 @@
+import matplotlib.pyplot as plt
+from mpl_toolkits.axes_grid import AxesGrid
+import numpy as np
+
+im = np.arange(100)
+im.shape = 10, 10
+
+fig = plt.figure(1, (4., 4.))
+grid = AxesGrid(fig, 111, # similar to subplot(111)
+                nrows_ncols = (2, 2), # creates 2x2 grid of axes
+                axes_pad=0.1, # pad between axes in inch.
+                )
+
+for i in range(4):
+    grid[i].imshow(im) # The AxesGrid object work as a list of axes.
+
+plt.show()

Added: trunk/matplotlib/examples/axes_grid/simple_axesgrid2.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/simple_axesgrid2.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/simple_axesgrid2.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,24 @@
+import matplotlib.pyplot as plt
+from mpl_toolkits.axes_grid import AxesGrid
+from demo_image import get_demo_image
+
+F = plt.figure(1, (5.5, 3.5))
+grid = AxesGrid(F, 111, # similar to subplot(111)
+                nrows_ncols = (1, 3),
+                axes_pad = 0.1,
+                add_all=True,
+                label_mode = "L",
+                )
+
+Z, extent = get_demo_image() # demo image
+
+im1=Z
+im2=Z[:,:10]
+im3=Z[:,10:]
+vmin, vmax = Z.min(), Z.max()
+for i, im in enumerate([im1, im2, im3]):
+    ax = grid[i]
+    ax.imshow(im, origin="lower", vmin=vmin, vmax=vmax, interpolation="nearest")
+
+plt.draw()
+plt.show()

Added: trunk/matplotlib/examples/axes_grid/simple_axisline.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/simple_axisline.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/simple_axisline.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,37 @@
+import matplotlib.pyplot as plt
+
+from mpl_toolkits.axes_grid.axislines import SubplotZero
+
+if 1:
+
+    fig = plt.figure(1)
+    fig.subplots_adjust(right=0.85)
+    ax = SubplotZero(fig, 1, 1, 1)
+    fig.add_subplot(ax)
+
+    # make right and top axis invisible
+    ax.axis["right"].set_visible(False)
+    ax.axis["top"].set_visible(False)
+
+    # make xzero axis (horizontal axis line through y=0) visible.
+    ax.axis["xzero"].set_visible(True)
+    ax.axis["xzero"].label.set_text("Axis Zero")
+
+    ax.set_ylim(-2, 4)
+    ax.set_xlabel("Label X")
+    ax.set_ylabel("Label Y")
+    # or
+    #ax.axis["bottom"].label.set_text("Label X")
+    #ax.axis["left"].label.set_text("Label Y")
+
+    # make new (right-side) yaxis, but wth some offset
+    offset = (20, 0)
+    new_axisline = ax.get_grid_helper().new_axisline
+    ax.axis["right2"] = new_axisline(loc="right",
+                                     offset=offset)
+    ax.axis["right2"].label.set_text("Label Y2")
+
+    ax.plot([-2,3,2])
+    plt.draw()
+    plt.show()
+

Added: trunk/matplotlib/examples/axes_grid/simple_axisline2.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/simple_axisline2.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/simple_axisline2.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,24 @@
+import matplotlib.pyplot as plt
+from mpl_toolkits.axes_grid.axislines import SubplotZero
+import numpy as np
+
+fig = plt.figure(1, (4,3))
+
+# a subplot with two additiona axis, "xzero" and "yzero". "xzero" is
+# y=0 line, and "yzero" is x=0 line.
+ax = SubplotZero(fig, 1, 1, 1)
+fig.add_subplot(ax)
+
+# make xzero axis (horizontal axis line through y=0) visible.
+ax.axis["xzero"].set_visible(True)
+ax.axis["xzero"].label.set_text("Axis Zero")
+
+# make other axis (bottom, top, right) invisible.
+for n in ["bottom", "top", "right"]:
+    ax.axis[n].set_visible(False)
+
+xx = np.arange(0, 2*np.pi, 0.01)
+ax.plot(xx, np.sin(xx))
+
+plt.show()
+

Added: trunk/matplotlib/examples/axes_grid/simple_axisline3.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/simple_axisline3.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/simple_axisline3.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,13 @@
+import matplotlib.pyplot as plt
+from mpl_toolkits.axes_grid.axislines import Subplot
+
+fig = plt.figure(1, (3,3))
+
+ax = Subplot(fig, 111)
+fig.add_subplot(ax)
+
+ax.axis["right"].set_visible(False)
+ax.axis["top"].set_visible(False)
+
+plt.show()
+

Added: trunk/matplotlib/examples/axes_grid/simple_axisline4.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/simple_axisline4.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/simple_axisline4.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,22 @@
+import matplotlib.pyplot as plt
+from mpl_toolkits.axes_grid.parasite_axes import SubplotHost
+import numpy as np
+
+fig = plt.figure(1, (4,3))
+
+ax = SubplotHost(fig, 111)
+fig.add_subplot(ax)
+
+xx = np.arange(0, 2*np.pi, 0.01)
+ax.plot(xx, np.sin(xx))
+
+ax2 = ax.twin() # ax2 is responsible for "top" axis and "right" axis
+ax2.set_xticks([0., .5*np.pi, np.pi, 1.5*np.pi, 2*np.pi])
+ax2.set_xticklabels(["0", r"$\frac{1}{2}\pi$",
+                     r"$\pi$", r"$\frac{3}{2}\pi$", r"$2\pi$"])
+
+ax2.axis["right"].major_ticklabels.set_visible(False)
+
+plt.draw()
+plt.show()
+

Added: trunk/matplotlib/examples/axes_grid/simple_rgb.py
===================================================================
--- trunk/matplotlib/examples/axes_grid/simple_rgb.py	                        (rev 0)
+++ trunk/matplotlib/examples/axes_grid/simple_rgb.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,31 @@
+import matplotlib.pyplot as plt
+
+from demo_image import get_demo_image
+from mpl_toolkits.axes_grid.axes_rgb import RGBAxes
+
+def get_rgb():
+    Z, extent = get_demo_image()
+
+    Z[Z<0] = 0.
+    Z = Z/Z.max()
+
+    R = Z[:13,:13]
+    G = Z[2:,2:]
+    B = Z[:13,2:]
+
+    return R, G, B
+
+
+fig = plt.figure(1)
+ax = RGBAxes(fig, [0.1, 0.1, 0.8, 0.8])
+
+r, g, b = get_rgb()
+kwargs = dict(origin="lower", interpolation="nearest")
+ax.imshow_rgb(r, g, b, **kwargs)
+
+ax.RGB.set_xlim(0., 9.5)
+ax.RGB.set_ylim(0.9, 10.6)
+
+
+plt.draw()
+plt.show()

Added: trunk/matplotlib/lib/mpl_toolkits/axes_grid/__init__.py
===================================================================
--- trunk/matplotlib/lib/mpl_toolkits/axes_grid/__init__.py	                        (rev 0)
+++ trunk/matplotlib/lib/mpl_toolkits/axes_grid/__init__.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,9 @@
+"""
+AxesGrid
+"""
+
+
+from axes_divider import Divider, SubplotDivider, LocatableAxes, Size, \
+     make_axes_locatable
+from axes_grid import AxesGrid
+

Added: trunk/matplotlib/lib/mpl_toolkits/axes_grid/anchored_artists.py
===================================================================
--- trunk/matplotlib/lib/mpl_toolkits/axes_grid/anchored_artists.py	                        (rev 0)
+++ trunk/matplotlib/lib/mpl_toolkits/axes_grid/anchored_artists.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,122 @@
+
+
+from matplotlib.font_manager import FontProperties
+from matplotlib import rcParams
+from matplotlib.patches import Rectangle, Ellipse
+
+from matplotlib.offsetbox import AnchoredOffsetbox, AuxTransformBox, VPacker,\
+     TextArea, DrawingArea
+
+
+class AnchoredText(AnchoredOffsetbox):
+    def __init__(self, s, loc, pad=0.4, borderpad=0.5, prop=None, **kwargs):
+
+        self.txt = TextArea(s, textprops=prop,
+                            minimumdescent=False)
+        fp = self.txt._text.get_fontproperties()
+
+        super(AnchoredText, self).__init__(loc, pad=pad, borderpad=borderpad,
+                                           child=self.txt,
+                                           prop=fp,
+                                           **kwargs)
+
+
+class AnchoredSizeBar(AnchoredOffsetbox):
+    def __init__(self, transform, size, label, loc,
+                 pad=0.1, borderpad=0.1, sep=2, prop=None, frameon=True):
+        """
+        Draw a horizontal bar with the size in data coordinate of the give axes.
+        A label will be drawn underneath (center-alinged).
+
+        pad, borderpad in fraction of the legend font size (or prop)
+        sep in points.
+        """
+        self.size_bar = AuxTransformBox(transform)
+        self.size_bar.add_artist(Rectangle((0,0), size, 0, fc="none"))
+
+        self.txt_label = TextArea(label, minimumdescent=False)
+
+        self._box = VPacker(children=[self.size_bar, self.txt_label],
+                            align="center",
+                            pad=0, sep=sep)
+
+        AnchoredOffsetbox.__init__(self, loc, pad=pad, borderpad=borderpad,
+                                   child=self._box,
+                                   prop=prop,
+                                   frameon=frameon)
+
+
+class AnchoredEllipse(AnchoredOffsetbox):
+    def __init__(self, transform, width, height, angle, loc,
+                 pad=0.1, borderpad=0.1, prop=None, frameon=True):
+        """
+        Draw an ellipse the size in data coordinate of the give axes.
+
+        pad, borderpad in fraction of the legend font size (or prop)
+        """
+        self._box = AuxTransformBox(transform)
+        self.ellipse = Ellipse((0,0), width, height, angle)
+        self._box.add_artist(self.ellipse)
+
+        AnchoredOffsetbox.__init__(self, loc, pad=pad, borderpad=borderpad,
+                                   child=self._box,
+                                   prop=prop,
+                                   frameon=frameon)
+
+
+
+class AnchoredDrawingArea(AnchoredOffsetbox):
+    def __init__(self, width, height, xdescent, ydescent,
+                 loc, pad=0.4, borderpad=0.5, prop=None, frameon=True):
+
+        self.da = DrawingArea(width, height, xdescent, ydescent, clip=True)
+
+        super(AnchoredDrawingArea, self).__init__(loc, pad=pad, borderpad=borderpad,
+                                                  child=self.da,
+                                                  prop=None,
+                                                  frameon=frameon)
+
+
+
+if __name__ == "__main__":
+    import matplotlib.pyplot as plt
+    from matplotlib.patches import Circle
+
+    #import matplotlib.offsetbox
+    #matplotlib.offsetbox.DEBUG=False
+
+    #ax = plt.subplot(1,1,1)
+    plt.clf()
+    plt.cla()
+    plt.draw()
+    ax = plt.gca()
+    ax.set_aspect(1.)
+
+    at = AnchoredText("Figure 1a",
+                      loc=2, frameon=True)
+    at.patch.set_boxstyle("round,pad=0.,rounding_size=0.2")
+    ax.add_artist(at)
+
+    ada = AnchoredDrawingArea(20, 20, 0, 0,
+                              loc=1, pad=0., frameon=False)
+    p = Circle((10, 10), 10)
+    ada.da.add_artist(p)
+    ax.add_artist(ada)
+
+
+    as =  AnchoredSizeBar(ax, 0.1, r"1$^{\prime}$",
+                          loc=8,
+                          pad=0.1, borderpad=0.5, sep=5,
+                          frameon=False)
+    ax.add_artist(as)
+
+
+    ae = AnchoredEllipse(ax, width=0.1, height=0.15, angle=0.,
+                         loc=3, pad=0.5, borderpad=0.4, frameon=True)
+
+    ax.add_artist(ae)
+
+    plt.draw()
+    plt.show()
+
+

Added: trunk/matplotlib/lib/mpl_toolkits/axes_grid/axes_divider.py
===================================================================
--- trunk/matplotlib/lib/mpl_toolkits/axes_grid/axes_divider.py	                        (rev 0)
+++ trunk/matplotlib/lib/mpl_toolkits/axes_grid/axes_divider.py	2009-04-17 19:35:59 UTC (rev 7048)
@@ -0,0 +1,652 @@
+"""
+The axes_divider module provide helper classes to adjust the axes
+positions of set of images in the drawing time.
+
+ Size: This provides a classese of units that the size of each axes
+    will be determined. For example, you can specify a fixed size
+
+ Divider: this is the class that uis used calculates the axes
+    position. It divides the given renctangular area into several
+    areas. You intialize the divider by setting the horizontal and
+    vertical list of sizes that the division will be based on. You
+    then use the new_locator method, whose return value is a callable
+    object that can be used to set the axes_locator of the axes.
+
+"""
+
+import matplotlib.axes as maxes
+import matplotlib.transforms as mtransforms
+
+import matplotlib.cbook as cbook
+from matplotlib.axes import SubplotBase
+
+import new
+
+
+class Size(object):
+    """
+    provides a classese of units that will be used with AxesDivider
+    class (or others) to determine the size of each axes. The unit
+    classes define __call__ that returns a tuple of two floats,
+    meaning relative and absolute sizes, respectively.
+
+    Note that this class is nothing more than a simple tuple of two
+    floats. Take a look at the Divid...
 
[truncated message content]