axes_grid : doc update and new examples

svn path=/trunk/matplotlib/; revision=8010

Author: leejjoon

doc/mpl_toolkits/axes_grid/api/axes_grid_api.rst

@@ -2,6 +2,10 @@
 :mod:`mpl_toolkits.axes_grid.axes_grid`
 =======================================
 
-.. autoclass:: mpl_toolkits.axes_grid.axes_grid.AxesGrid
+.. autoclass:: mpl_toolkits.axes_grid.axes_grid.Grid
+   :members:
+   :undoc-members:
+
+.. autoclass:: mpl_toolkits.axes_grid.axes_grid.ImageGrid
    :members:
    :undoc-members:

doc/mpl_toolkits/axes_grid/api/axis_artist_api.rst

@@ -0,0 +1,16 @@
+
+:mod:`mpl_toolkits.axes_grid.axis_artist`
+=======================================
+
+.. autoclass:: mpl_toolkits.axes_grid.axis_artist.AxisArtist
+   :members:
+   :undoc-members:
+
+.. autoclass:: mpl_toolkits.axes_grid.axis_artist.Ticks
+   :members:
+
+.. autoclass:: mpl_toolkits.axes_grid.axis_artist.AxisLabel
+   :members:
+
+.. autoclass:: mpl_toolkits.axes_grid.axis_artist.TickLabels
+   :members:

doc/mpl_toolkits/axes_grid/api/index.rst

@@ -12,3 +12,4 @@
     axes_size_api.rst
     axes_divider_api.rst
     axes_grid_api.rst
+    axis_artist_api.rst

doc/mpl_toolkits/axes_grid/figures/demo_axis_direction.py

@@ -0,0 +1,98 @@
+
+
+import numpy as np
+import  mpl_toolkits.axes_grid.angle_helper as angle_helper
+import  mpl_toolkits.axes_grid.grid_finder as grid_finder
+from matplotlib.projections import PolarAxes
+from matplotlib.transforms import Affine2D
+
+import mpl_toolkits.axes_grid.axislines as axislines
+
+from mpl_toolkits.axes_grid.grid_helper_curvelinear import GridHelperCurveLinear
+
+
+def setup_axes(fig, rect):
+    """
+    polar projection, but in a rectangular box.
+    """
+
+    # see demo_curvelinear_grid.py for details
+    tr = Affine2D().scale(np.pi/180., 1.) + PolarAxes.PolarTransform()
+
+    extreme_finder = angle_helper.ExtremeFinderCycle(20, 20,
+                                                     lon_cycle = 360,
+                                                     lat_cycle = None,
+                                                     lon_minmax = None,
+                                                     lat_minmax = (0, np.inf),
+                                                     )
+
+    grid_locator1 = angle_helper.LocatorDMS(12)
+    grid_locator2 = grid_finder.MaxNLocator(5)
+
+    tick_formatter1 = angle_helper.FormatterDMS()
+
+    grid_helper = GridHelperCurveLinear(tr,
+                                        extreme_finder=extreme_finder,
+                                        grid_locator1=grid_locator1,
+                                        grid_locator2=grid_locator2,
+                                        tick_formatter1=tick_formatter1
+                                        )
+
+
+    ax1 = axislines.Subplot(fig, rect, grid_helper=grid_helper)
+    ax1.axis[:].toggle(ticklabels=False)
+
+    fig.add_subplot(ax1)
+
+    ax1.set_aspect(1.)
+    ax1.set_xlim(-5, 12)
+    ax1.set_ylim(-5, 10)
+
+    #ax1.grid(True)
+
+    return ax1
+
+
+def add_floating_axis1(ax1):
+    ax1.axis["lat"] = axis = ax1.new_floating_axis(0, 30)
+    axis.label.set_text(r"$\theta = 30^{\circ}$")
+    axis.label.set_visible(True)
+
+    return axis
+
+
+def add_floating_axis2(ax1):
+    ax1.axis["lon"] = axis = ax1.new_floating_axis(1, 6)
+    axis.label.set_text(r"$r = 6$")
+    axis.label.set_visible(True)
+
+    return axis
+
+
+import matplotlib.pyplot as plt
+fig = plt.figure(1, figsize=(8, 4.))
+fig.clf()
+fig.subplots_adjust(left=0.01, right=0.99, bottom=0.01, top=0.99,
+                    wspace=0.01, hspace=0.01)
+
+for i, d in enumerate(["bottom", "left", "top", "right"]):
+    ax1 = setup_axes(fig, rect=241++i)
+    axis = add_floating_axis1(ax1)
+    axis.set_axis_direction(d)
+    ax1.annotate(d, (0, 1), (5, -5),
+                 xycoords="axes fraction", textcoords="offset points",
+                 va="top", ha="left")
+
+for i, d in enumerate(["bottom", "left", "top", "right"]):
+    ax1 = setup_axes(fig, rect=245++i)
+    axis = add_floating_axis2(ax1)
+    axis.set_axis_direction(d)
+    ax1.annotate(d, (0, 1), (5, -5),
+                 xycoords="axes fraction", textcoords="offset points",
+                 va="top", ha="left")
+
+
+
+plt.show()
+
+

doc/mpl_toolkits/axes_grid/figures/demo_ticklabel_alignment.py

@@ -0,0 +1,38 @@
+
+
+import matplotlib.pyplot as plt
+import mpl_toolkits.axes_grid.axislines as axislines
+
+
+def setup_axes(fig, rect):
+    
+    ax = axislines.Subplot(fig, rect)
+    fig.add_subplot(ax)
+
+    ax.set_yticks([0.2, 0.8])
+    ax.set_yticklabels(["short", "loooong"])
+    ax.set_xticks([0.2, 0.8])
+    ax.set_xticklabels([r"$\frac{1}{2}\pi$", r"$\pi$"])
+
+    return ax
+
+fig = plt.figure(1, figsize=(3, 5))
+fig.subplots_adjust(left=0.5, hspace=0.7)
+
+
+
+ax = setup_axes(fig, 311)
+ax.set_ylabel("ha=right")
+ax.set_xlabel("va=baseline")
+
+ax = setup_axes(fig, 312)
+ax.axis["left"].major_ticklabels.set_ha("center")
+ax.axis["bottom"].major_ticklabels.set_va("top")
+ax.set_ylabel("ha=center")
+ax.set_xlabel("va=top")
+
+ax = setup_axes(fig, 313)
+ax.axis["left"].major_ticklabels.set_ha("left")
+ax.axis["bottom"].major_ticklabels.set_va("bottom")
+ax.set_ylabel("ha=left")
+ax.set_xlabel("va=bottom")

doc/mpl_toolkits/axes_grid/figures/demo_ticklabel_direction.py

@@ -0,0 +1,52 @@
+
+import matplotlib.pyplot as plt
+import mpl_toolkits.axes_grid.axislines as axislines
+
+
+def setup_axes(fig, rect):
+    
+    ax = axislines.Subplot(fig, rect)
+    fig.add_subplot(ax)
+
+    ax.set_yticks([0.2, 0.8])
+    #ax.set_yticklabels(["short", "loooong"])
+    ax.set_xticks([0.2, 0.8])
+    #ax.set_xticklabels([r"$\frac{1}{2}\pi$", r"$\pi$"])
+
+    return ax
+
+fig = plt.figure(1, figsize=(6, 3))
+fig.subplots_adjust(bottom=0.2)
+
+
+
+ax = setup_axes(fig, 131)
+for axis in ax.axis.values(): axis.major_ticks.set_tick_out(True)
+#or you can simply do "ax.axis[:].major_ticks.set_tick_out(True)"
+
+
+
+
+ax = setup_axes(fig, 132)
+ax.axis["left"].set_axis_direction("right")
+ax.axis["bottom"].set_axis_direction("top")
+ax.axis["right"].set_axis_direction("left")
+ax.axis["top"].set_axis_direction("bottom")
+
+ax.axis["left"].major_ticklabels.set_pad(0)
+ax.axis["bottom"].major_ticklabels.set_pad(10)
+
+
+
+ax = setup_axes(fig, 133)
+ax.axis["left"].set_axis_direction("right")
+ax.axis[:].major_ticks.set_tick_out(True)
+
+ax.axis["left"].label.set_text("Long Label Left")
+ax.axis["bottom"].label.set_text("Label Bottom")
+ax.axis["right"].label.set_text("Long Label Right")
+ax.axis["right"].label.set_visible(True)
+ax.axis["left"].label.set_pad(0)
+ax.axis["bottom"].label.set_pad(10)
+
+plt.show()

doc/mpl_toolkits/axes_grid/users/axislines.rst

@@ -42,7 +42,7 @@ 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
 have *gridlines* attribute (Gridlines), which obviously draws grid
-lines. 
+lines.
 
 In both AxisArtist and Gridlines, the calculation of tick and grid
 location is delegated to an instance of GridHelper class.
@@ -119,6 +119,43 @@ HowTo
 
     ax.axis["left"].major_ticklabels.set_color("r")
 
+3. To change the attributes of multiple axis::
+
+    ax.axis["left","bottom"].major_ticklabels.set_color("r")
+
+   or to change the attributes of all axis::
+
+    ax.axis[:].major_ticklabels.set_color("r")
+
+4. To change the tick size (length), you need to use
+    axis.major_ticks.set_ticksize method. To change the direction of
+    the ticks (ticks are in opposite direction of ticklabels by
+    default), use axis.major_ticks.set_tick_out method.
+
+    To change the pad between ticks and ticklabels, use
+    axis.major_ticklabels.set_pad method.
+
+    To change the pad between ticklabels and axis label,
+    axis.label.set_pad method.
+
+Examples
+========
+
+Adjusting axis_direction
+------------------------
+
+.. plot:: mpl_toolkits/axes_grid/figures/demo_axis_direction.py
+
+Adjusting ticklabels alignment
+------------------------------
+
+.. plot:: mpl_toolkits/axes_grid/figures/demo_ticklabel_alignment.py
+
+Adjusting ticklabels pad
+------------------------
+
+.. plot:: mpl_toolkits/axes_grid/figures/demo_ticklabel_direction.py
+
 
 GridHelper
 ==========
@@ -138,7 +175,7 @@ transform of the axes itself (ax.transData) is still rectlinear
     from mpl_toolkits.axes_grid.axislines import Subplot
 
     # from curved coordinate to rectlinear coordinate.
-    def tr(x, y): 
+    def tr(x, y):
         x, y = np.asarray(x), np.asarray(y)
         return x, y-x
 
@@ -171,7 +208,7 @@ required. ::
 
     # extreme finder :  find a range of coordinate.
     # 20, 20 : number of sampling points along x, y direction
-    # The first coordinate (longitude, but theta in polar) 
+    # The first coordinate (longitude, but theta in polar)
     #   has a cycle of 360 degree.
     # The second coordinate (latitude, but radius in polar)  has a minimum of 0
     extreme_finder = angle_helper.ExtremeFinderCycle(20, 20,
@@ -225,7 +262,7 @@ limits changes. A floating axis can be created using
 the resulting AxisArtist is properly added to the axes. A recommended
 way is to add it as an item of Axes's axis attribute.::
 
-    # floating axis whose first (index starts from 0) coordinate 
+    # floating axis whose first (index starts from 0) coordinate
     # (theta) is fixed at 60
 
     ax1.axis["lat"] = axis = ax1.new_floating_axis(0, 60)

doc/mpl_toolkits/axes_grid/users/overview.rst

@@ -35,7 +35,7 @@ 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_examples/axes_grid/simple_axesgrid.py
+.. plot:: mpl_toolkits/axes_grid/examples/simple_axesgrid.py
    :include-source:
 
 * The postion of each axes is determined at the drawing time (see
@@ -398,3 +398,11 @@ created. See :ref:`axislines-manual` for more details.
 .. plot:: mpl_toolkits/axes_grid/examples/demo_floating_axis.py
 
 
+Floating Axes
+=============
+
+An axes whose outer axis are defined as floating axis.
+
+.. plot:: mpl_toolkits/axes_grid/examples/demo_floating_axes.py
+
+

examples/axes_grid/demo_curvelinear_grid2.py

@@ -0,0 +1,63 @@
+import numpy as np
+#from matplotlib.path import Path
+
+import matplotlib.pyplot as plt
+
+from  mpl_toolkits.axes_grid.grid_helper_curvelinear import GridHelperCurveLinear
+from mpl_toolkits.axes_grid.axislines import Subplot
+
+import  mpl_toolkits.axes_grid.angle_helper as angle_helper
+
+def curvelinear_test1(fig):
+    """
+    grid for custom transform.
+    """
+
+    def tr(x, y):
+        sgn = np.sign(x)
+        x, y = np.abs(np.asarray(x)), np.asarray(y)
+        return sgn*x**.5, y
+
+    def inv_tr(x,y):
+        sgn = np.sign(x)
+        x, y = np.asarray(x), np.asarray(y)
+        return sgn*x**2, y
+
+    extreme_finder = angle_helper.ExtremeFinderCycle(20, 20,
+                                                     lon_cycle = None,
+                                                     lat_cycle = None,
+                                                     lon_minmax = None, #(0, np.inf),
+                                                     lat_minmax = None,
+                                                     )
+
+    grid_helper = GridHelperCurveLinear((tr, inv_tr),
+                                        extreme_finder=extreme_finder)
+
+    ax1 = Subplot(fig, 111, grid_helper=grid_helper)
+    # ax1 will have a ticks and gridlines defined by the given
+    # transform (+ transData of the Axes). Note that the transform of
+    # the Axes itself (i.e., transData) is not affected by the given
+    # transform.
+
+    fig.add_subplot(ax1)
+
+    ax1.imshow(np.arange(25).reshape(5,5),
+               vmax = 50, cmap=plt.cm.gray_r,
+               interpolation="nearest",
+               origin="lower")
+
+    # tick density
+    grid_helper.grid_finder.grid_locator1._nbins = 6
+    grid_helper.grid_finder.grid_locator2._nbins = 6
+
+
+
+if 1:
+    fig = plt.figure(1, figsize=(7, 4))
+    fig.clf()
+
+    curvelinear_test1(fig)
+    plt.show()
+
+
+