update axes_grid toolkit documentation

leejjoon · leejjoon · commit 89a921210bb9 · 2010-04-20T16:44:01.000Z
svn path=/trunk/matplotlib/; revision=8247
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,5 @@
+2010-04-18 update the axes_grid documentation. -JJL
+
 2010-04-18 Control MaxNLocator parameters after instantiation,
            and via Axes.locator_params method, with corresponding
            pyplot function. -EF
diff --git a/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step01.py b/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step01.py
@@ -1,8 +1,8 @@
 import matplotlib.pyplot as plt
-import mpl_toolkits.axes_grid.axislines as axislines
+import mpl_toolkits.axisartist as axisartist
 
 def setup_axes(fig, rect):
-    ax = axislines.Subplot(fig, rect)
+    ax = axisartist.Subplot(fig, rect)
     fig.add_axes(ax)
 
     ax.set_ylim(-0.1, 1.5)
diff --git a/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step02.py b/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step02.py
@@ -1,8 +1,8 @@
 import matplotlib.pyplot as plt
-import mpl_toolkits.axes_grid.axislines as axislines
+import mpl_toolkits.axisartist as axisartist
 
 def setup_axes(fig, rect):
-    ax = axislines.Subplot(fig, rect)
+    ax = axisartist.Subplot(fig, rect)
     fig.add_axes(ax)
 
     ax.set_ylim(-0.1, 1.5)
diff --git a/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step03.py b/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step03.py
@@ -1,8 +1,8 @@
 import matplotlib.pyplot as plt
-import mpl_toolkits.axes_grid.axislines as axislines
+import mpl_toolkits.axisartist as axisartist
 
 def setup_axes(fig, rect):
-    ax = axislines.Subplot(fig, rect)
+    ax = axisartist.Subplot(fig, rect)
     fig.add_axes(ax)
 
     ax.set_ylim(-0.1, 1.5)
diff --git a/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step04.py b/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step04.py
@@ -1,8 +1,8 @@
 import matplotlib.pyplot as plt
-import mpl_toolkits.axes_grid.axislines as axislines
+import mpl_toolkits.axisartist as axisartist
 
 def setup_axes(fig, rect):
-    ax = axislines.Subplot(fig, rect)
+    ax = axisartist.Subplot(fig, rect)
     fig.add_axes(ax)
 
     ax.set_ylim(-0.1, 1.5)
diff --git a/doc/mpl_toolkits/axes_grid/figures/demo_axis_direction.py b/doc/mpl_toolkits/axes_grid/figures/demo_axis_direction.py
@@ -1,14 +1,14 @@
 
 
 import numpy as np
-import  mpl_toolkits.axes_grid.angle_helper as angle_helper
-import  mpl_toolkits.axes_grid.grid_finder as grid_finder
+import  mpl_toolkits.axisartist.angle_helper as angle_helper
+import  mpl_toolkits.axisartist.grid_finder as grid_finder
 from matplotlib.projections import PolarAxes
 from matplotlib.transforms import Affine2D
 
-import mpl_toolkits.axes_grid.axislines as axislines
+import mpl_toolkits.axisartist as axisartist
 
-from mpl_toolkits.axes_grid.grid_helper_curvelinear import GridHelperCurveLinear
+from mpl_toolkits.axisartist.grid_helper_curvelinear import GridHelperCurveLinear
 
 
 def setup_axes(fig, rect):
@@ -39,7 +39,7 @@ def setup_axes(fig, rect):
                                         )
 
 
-    ax1 = axislines.Subplot(fig, rect, grid_helper=grid_helper)
+    ax1 = axisartist.Subplot(fig, rect, grid_helper=grid_helper)
     ax1.axis[:].toggle(ticklabels=False)
 
     fig.add_subplot(ax1)
diff --git a/doc/mpl_toolkits/axes_grid/figures/demo_ticklabel_alignment.py b/doc/mpl_toolkits/axes_grid/figures/demo_ticklabel_alignment.py
@@ -1,12 +1,12 @@
 
 
 import matplotlib.pyplot as plt
-import mpl_toolkits.axes_grid.axislines as axislines
+import mpl_toolkits.axisartist as axisartist
 
 
 def setup_axes(fig, rect):
     
-    ax = axislines.Subplot(fig, rect)
+    ax = axisartist.Subplot(fig, rect)
     fig.add_subplot(ax)
 
     ax.set_yticks([0.2, 0.8])
diff --git a/doc/mpl_toolkits/axes_grid/figures/parasite_simple.py b/doc/mpl_toolkits/axes_grid/figures/parasite_simple.py
@@ -1,10 +1,7 @@
-from mpl_toolkits.axes_grid.parasite_axes import SubplotHost
+from mpl_toolkits.axes_grid1 import host_subplot
 import matplotlib.pyplot as plt
 
-fig = plt.figure(1)
-
-host = SubplotHost(fig, 111)
-fig.add_subplot(host)
+host = host_subplot(111)
 
 par = host.twinx()
 
@@ -15,10 +12,13 @@
 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())
+leg = plt.legend()
+
+host.yaxis.get_label().set_color(p1.get_color())
+leg.texts[0].set_color(p1.get_color())
 
-host.legend()
+par.yaxis.get_label().set_color(p2.get_color())
+leg.texts[1].set_color(p2.get_color())
 
 plt.show()
 
diff --git a/doc/mpl_toolkits/axes_grid/figures/simple_axis_direction01.py b/doc/mpl_toolkits/axes_grid/figures/simple_axis_direction01.py
@@ -1,8 +1,8 @@
 import matplotlib.pyplot as plt
-import mpl_toolkits.axes_grid.axislines as axislines
+import mpl_toolkits.axisartist as axisartist
 
 fig = plt.figure(figsize=(4,2.5))
-ax1 = fig.add_subplot(axislines.Subplot(fig, "111"))
+ax1 = fig.add_subplot(axisartist.Subplot(fig, "111"))
 fig.subplots_adjust(right=0.8)
 
 ax1.axis["left"].major_ticklabels.set_axis_direction("top")
diff --git a/doc/mpl_toolkits/axes_grid/figures/simple_axis_direction03.py b/doc/mpl_toolkits/axes_grid/figures/simple_axis_direction03.py
@@ -1,9 +1,9 @@
 
 import matplotlib.pyplot as plt
-import mpl_toolkits.axes_grid.axislines as axislines
+import mpl_toolkits.axisartist as axisartist
 
 def setup_axes(fig, rect):
-    ax = axislines.Subplot(fig, rect)
+    ax = axisartist.Subplot(fig, rect)
     fig.add_subplot(ax)
 
     ax.set_yticks([0.2, 0.8])
diff --git a/doc/mpl_toolkits/axes_grid/figures/simple_axis_pad.py b/doc/mpl_toolkits/axes_grid/figures/simple_axis_pad.py
@@ -1,14 +1,14 @@
 
 
 import numpy as np
-import  mpl_toolkits.axes_grid.angle_helper as angle_helper
-import  mpl_toolkits.axes_grid.grid_finder as grid_finder
+import  mpl_toolkits.axisartist.angle_helper as angle_helper
+import  mpl_toolkits.axisartist.grid_finder as grid_finder
 from matplotlib.projections import PolarAxes
 from matplotlib.transforms import Affine2D
 
-import mpl_toolkits.axes_grid.axislines as axislines
+import mpl_toolkits.axisartist as axisartist
 
-from mpl_toolkits.axes_grid.grid_helper_curvelinear import GridHelperCurveLinear
+from mpl_toolkits.axisartist.grid_helper_curvelinear import GridHelperCurveLinear
 
 
 def setup_axes(fig, rect):
@@ -39,7 +39,7 @@ def setup_axes(fig, rect):
                                         )
 
 
-    ax1 = axislines.Subplot(fig, rect, grid_helper=grid_helper)
+    ax1 = axisartist.Subplot(fig, rect, grid_helper=grid_helper)
     #ax1.axis[:].toggle(all=False)
     ax1.axis[:].set_visible(False)
 
diff --git a/doc/mpl_toolkits/axes_grid/figures/simple_axisartist1.py b/doc/mpl_toolkits/axes_grid/figures/simple_axisartist1.py
@@ -0,0 +1,22 @@
+import matplotlib.pyplot as plt
+import mpl_toolkits.axisartist as AA
+
+fig = plt.figure(1)
+fig.subplots_adjust(right=0.85)
+ax = AA.Subplot(fig, 1, 1, 1)
+fig.add_subplot(ax)
+
+# make some axis invisible
+ax.axis["bottom", "top", "right"].set_visible(False)
+
+# make an new axis along the first axis axis (x-axis) which pass
+# throught y=0.
+ax.axis["y=0"] = ax.new_floating_axis(nth_coord=0, value=0,
+                                      axis_direction="bottom")
+ax.axis["y=0"].toggle(all=True)
+ax.axis["y=0"].label.set_text("y = 0")
+
+ax.set_ylim(-2, 4)
+
+plt.show()
+
diff --git a/doc/mpl_toolkits/axes_grid/figures/simple_colorbar.py b/doc/mpl_toolkits/axes_grid/figures/simple_colorbar.py
@@ -0,0 +1,14 @@
+import matplotlib.pyplot as plt
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+import numpy as np
+
+ax = plt.subplot(111)
+im = ax.imshow(np.arange(100).reshape((10,10)))
+
+# create an axes on the right side of ax. The width of cax will be 5%
+# of ax and the padding between cax and ax will be fixed at 0.05 inch.
+divider = make_axes_locatable(ax)
+cax = divider.append_axes("right", size="5%", pad=0.05)
+
+plt.colorbar(im, cax=cax)
+
diff --git a/doc/mpl_toolkits/axes_grid/figures/simple_rgb.py b/doc/mpl_toolkits/axes_grid/figures/simple_rgb.py
@@ -1,6 +1,6 @@
 import matplotlib.pyplot as plt
 
-from mpl_toolkits.axes_grid.axes_rgb import RGBAxes
+from mpl_toolkits.axes_grid1.axes_rgb import RGBAxes
 
 def get_demo_image():
     import numpy as np
diff --git a/doc/mpl_toolkits/axes_grid/index.rst b/doc/mpl_toolkits/axes_grid/index.rst
@@ -13,13 +13,30 @@ multiple axes according to their aspects.
 
 .. image:: ../../_static/demo_axes_grid.png
 
+.. note:: 
+   AxesGrid toolkit has been a part of matplotlib since v
+   0.99. Originally, the toolkit had a single namespace of 
+   *axes_grid*. In more recent version (since svn r8226), the toolkit 
+   has divided into two separate namespace (*axes_grid1* and *axisartist*).
+   While *axes_grid* namespace is maintained for he backward compatibility,
+   use of *axes_grid1* and *axisartist* is recommended.
+
+.. warning:: 
+   *axes_grid* and *axisartist* (but not *axes_grid1*) uses
+   a custome Axes class (derived from the mpl's original Axes class).
+   As a sideeffect, some commands (mostly tick-related) do not work.
+   Use *axes_grid1* to avoid this, or see how things are different in
+   *axes_grid* and *axisartist* (LINK needed)
+
+
 
 Documentation
 =============
 
 .. toctree::
    :maxdepth: 2
 
+   users/overview.rst
    users/index.rst
    howtos/index.rst
    api/index.rst
diff --git a/doc/mpl_toolkits/axes_grid/users/axisartist.rst b/doc/mpl_toolkits/axes_grid/users/axisartist.rst
@@ -1,16 +1,16 @@
-.. _axislines-manual:
+.. _axisartist-manual:
 
-=========
-Axislines
-=========
+====================
+AXISARTIST namespace
+====================
 
-Axislines includes a derived Axes implementation. The
+The AxisArtist namesapce includes a derived Axes implementation. The
 biggest difference is that the artists responsible to draw axis line,
 ticks, ticklabel and axis labels are separated out from the mpl's Axis
-class, which are much more than artists in the original
-mpl. This change was strongly motivated to support curvlinear
-grid. Here are a few things that axes_grid.axislines.Axes is different
-from original Axes from mpl.
+class, which are much more than artists in the original mpl. This
+change was strongly motivated to support curvlinear grid. Here are a
+few things that mpl_tootlkits.axisartist.Axes is different from original
+Axes from mpl.
 
 * Axis elements (axis line(spine), ticks, ticklabel and axis labels)
   are drawn by a AxisArtist instance. Unlike Axis, left, right, top
@@ -19,7 +19,7 @@ from original Axes from mpl.
 
 * gridlines are drawn by a Gridlines instance. The change was
   motivated that in curvelinear coordinate, a gridline may not cross
-  axislines (i.e., no associated ticks). In the original Axes class,
+  axis-lines (i.e., no associated ticks). In the original Axes class,
   gridlines are tied to ticks.
 
 * ticklines can be rotated if necessary (i.e, along the gridlines)
@@ -32,21 +32,21 @@ In summary, all these changes was to support
 .. plot:: mpl_toolkits/axes_grid/examples/demo_floating_axis.py
 
 
-*axes_grid.axislines.Axes* defines a *axis* attribute, which is a
-dictionary of AxisArtist instances. By default, the dictionary has 4
-AxisArtist instances, responsible for drawing of left, right, bottom
-and top axis.
+*mpl_toolkits.axisartist.Axes* class defines a *axis* attribute, which
+is a dictionary of AxisArtist instances. By default, the dictionary
+has 4 AxisArtist instances, responsible for drawing of left, right,
+bottom and top axis.
 
 xaxis and yaxis attributes are still available, however they are set
 to not visible. As separate artists are used for rendering axis, some
 axis-related method in mpl may have no effect.
-In addition to AxisArtist instances, the axes_grid.axislines.Axes will
+In addition to AxisArtist instances, the mpl_toolkits.axisartist.Axes will
 have *gridlines* attribute (Gridlines), which obviously draws grid
 lines.
 
 In both AxisArtist and Gridlines, the calculation of tick and grid
 location is delegated to an instance of GridHelper class.
-axes_grid.axislines.Axes class uses GridHelperRectlinear as a grid
+mpl_toolkits.axisartist.Axes class uses GridHelperRectlinear as a grid
 helper. The GridHelperRectlinear class is a wrapper around the *xaxis*
 and *yaxis* of mpl's original Axes, and it was meant to work as the
 way how mpl's original axes works. For example, tick location changes
@@ -208,7 +208,7 @@ You must understand some underlying concept of directions.
    .. plot:: mpl_toolkits/axes_grid/figures/axis_direction_demo_step01.py
 
    The direction, text angle, and alignments of the ticks, ticklabels and
-   axis-label is determined width respect to the reference direction
+   axis-label is determined with respect to the reference direction
 
  2. *ticklabel_direction* is either the right-hand side (+) of the
     reference direction or the left-hand side (-).
@@ -223,7 +223,7 @@ You must understand some underlying concept of directions.
 
  5. text rotation of ticklabels and label is determined in reference
     to the *ticklabel_direction* or *label_direction*,
-    respectively. The rotation of ticklabels and tlabel is anchored.
+    respectively. The rotation of ticklabels and label is anchored.
 
    .. plot:: mpl_toolkits/axes_grid/figures/axis_direction_demo_step04.py
 
@@ -331,17 +331,17 @@ GridHelper
 
 To actually define a curvelinear coordinate, you have to use your own
 grid helper. A generalised version of grid helper class is supplied
-and this class should be suffice in most of cases. A user may provide
+and this class should suffice in most of cases. A user may provide
 two functions which defines a transformation (and its inverse pair)
 from the curved coordinate to (rectlinear) image coordinate. Note that
 while ticks and grids are drawn for curved coordinate, the data
 transform of the axes itself (ax.transData) is still rectlinear
 (image) coordinate. ::
 
 
-    from  mpl_toolkits.axes_grid.grid_helper_curvelinear \
+    from  mpl_toolkits.axisartist.grid_helper_curvelinear \
          import GridHelperCurveLinear
-    from mpl_toolkits.axes_grid.axislines import Subplot
+    from mpl_toolkits.axisartist import Subplot
 
     # from curved coordinate to rectlinear coordinate.
     def tr(x, y):
@@ -368,7 +368,7 @@ cycles. In those cases, a more customized version of grid helper is
 required. ::
 
 
-    import  mpl_toolkits.axes_grid.angle_helper as angle_helper
+    import  mpl_toolkits.axisartist.angle_helper as angle_helper
 
     # PolarAxes.PolarTransform takes radian. However, we want our coordinate
     # system in degree
diff --git a/doc/mpl_toolkits/axes_grid/users/index.rst b/doc/mpl_toolkits/axes_grid/users/index.rst
@@ -9,6 +9,6 @@
 
 .. toctree::
 
-    overview.rst
     axes_divider.rst
-    axislines.rst
+    axisartist.rst
+
diff --git a/doc/mpl_toolkits/axes_grid/users/overview.rst b/doc/mpl_toolkits/axes_grid/users/overview.rst
diff --git a/examples/axes_grid/demo_curvelinear_grid.py b/examples/axes_grid/demo_curvelinear_grid.py
diff --git a/examples/axes_grid/demo_parasite_axes2.py b/examples/axes_grid/demo_parasite_axes2.py
diff --git a/examples/axes_grid/scatter_hist.py b/examples/axes_grid/scatter_hist.py
diff --git a/examples/axes_grid/simple_axisline4.py b/examples/axes_grid/simple_axisline4.py

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+2010-04-18 update the axes_grid documentation. -JJL`
	`2`	`+`
`1`	`3`	`2010-04-18 Control MaxNLocator parameters after instantiation,`
`2`	`4`	`and via Axes.locator_params method, with corresponding`
`3`	`5`	`pyplot function. -EF`