Menu
▾
▴
SF.net SVN: matplotlib:[8247] trunk/matplotlib
|
From: <lee...@us...> - 2010-04-20 16:44:08
|
Revision: 8247
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=8247&view=rev
Author: leejjoon
Date: 2010-04-20 16:44:01 +0000 (Tue, 20 Apr 2010)
Log Message:
-----------
update axes_grid toolkit documentation
Modified Paths:
--------------
trunk/matplotlib/CHANGELOG
trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step01.py
trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step02.py
trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step03.py
trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step04.py
trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/demo_axis_direction.py
trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/demo_ticklabel_alignment.py
trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/parasite_simple.py
trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axis_direction01.py
trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axis_direction03.py
trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axis_pad.py
trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_rgb.py
trunk/matplotlib/doc/mpl_toolkits/axes_grid/index.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/demo_curvelinear_grid.py
trunk/matplotlib/examples/axes_grid/demo_parasite_axes2.py
trunk/matplotlib/examples/axes_grid/scatter_hist.py
trunk/matplotlib/examples/axes_grid/simple_axisline4.py
Added Paths:
-----------
trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axisartist1.py
trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_colorbar.py
trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axisartist.rst
Removed Paths:
-------------
trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axislines.rst
Modified: trunk/matplotlib/CHANGELOG
===================================================================
--- trunk/matplotlib/CHANGELOG 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/CHANGELOG 2010-04-20 16:44:01 UTC (rev 8247)
@@ -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
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step01.py
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step01.py 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step01.py 2010-04-20 16:44:01 UTC (rev 8247)
@@ -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)
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step02.py
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step02.py 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step02.py 2010-04-20 16:44:01 UTC (rev 8247)
@@ -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)
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step03.py
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step03.py 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step03.py 2010-04-20 16:44:01 UTC (rev 8247)
@@ -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)
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step04.py
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step04.py 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/axis_direction_demo_step04.py 2010-04-20 16:44:01 UTC (rev 8247)
@@ -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)
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/demo_axis_direction.py
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/demo_axis_direction.py 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/demo_axis_direction.py 2010-04-20 16:44:01 UTC (rev 8247)
@@ -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 @@
)
- 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)
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/demo_ticklabel_alignment.py
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/demo_ticklabel_alignment.py 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/demo_ticklabel_alignment.py 2010-04-20 16:44:01 UTC (rev 8247)
@@ -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])
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/parasite_simple.py
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/parasite_simple.py 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/parasite_simple.py 2010-04-20 16:44:01 UTC (rev 8247)
@@ -1,11 +1,8 @@
-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 = host_subplot(111)
-host = SubplotHost(fig, 111)
-fig.add_subplot(host)
-
par = host.twinx()
host.set_xlabel("Distance")
@@ -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.legend()
+host.yaxis.get_label().set_color(p1.get_color())
+leg.texts[0].set_color(p1.get_color())
+par.yaxis.get_label().set_color(p2.get_color())
+leg.texts[1].set_color(p2.get_color())
+
plt.show()
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axis_direction01.py
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axis_direction01.py 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axis_direction01.py 2010-04-20 16:44:01 UTC (rev 8247)
@@ -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")
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axis_direction03.py
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axis_direction03.py 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axis_direction03.py 2010-04-20 16:44:01 UTC (rev 8247)
@@ -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])
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axis_pad.py
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axis_pad.py 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axis_pad.py 2010-04-20 16:44:01 UTC (rev 8247)
@@ -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 @@
)
- 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)
Added: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axisartist1.py
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axisartist1.py (rev 0)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_axisartist1.py 2010-04-20 16:44:01 UTC (rev 8247)
@@ -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()
+
Added: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_colorbar.py
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_colorbar.py (rev 0)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_colorbar.py 2010-04-20 16:44:01 UTC (rev 8247)
@@ -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)
+
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_rgb.py
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_rgb.py 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/figures/simple_rgb.py 2010-04-20 16:44:01 UTC (rev 8247)
@@ -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
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/index.rst
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/index.rst 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/index.rst 2010-04-20 16:44:01 UTC (rev 8247)
@@ -13,13 +13,30 @@
.. 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
Copied: trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axisartist.rst (from rev 8246, trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axislines.rst)
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axisartist.rst (rev 0)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axisartist.rst 2010-04-20 16:44:01 UTC (rev 8247)
@@ -0,0 +1,456 @@
+.. _axisartist-manual:
+
+====================
+AXISARTIST namespace
+====================
+
+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 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
+ and bottom axis are drawn by separate artists. And each of them may
+ have different tick location and different tick labels.
+
+* gridlines are drawn by a Gridlines instance. The change was
+ motivated that in curvelinear coordinate, a gridline may not cross
+ 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)
+
+In summary, all these changes was to support
+
+* a curvelinear grid.
+* a floating axis
+
+.. plot:: mpl_toolkits/axes_grid/examples/demo_floating_axis.py
+
+
+*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 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.
+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
+using set_ticks method and etc. should work as expected. But change in
+artist properties (e.g., color) will not work in general, although
+some effort has been made so that some often-change attributes (color,
+etc.) are respected.
+
+
+AxisArtist
+==========
+
+AxisArtist can be considered as a container artist with following
+attributes which will draw ticks, labels, etc.
+
+ * line
+ * major_ticks, major_ticklabels
+ * minor_ticks, minor_ticklabels
+ * offsetText
+ * label
+
+
+line
+----
+
+Derived from Line2d class. Responsible for drawing a spinal(?) line.
+
+major_ticks, minor_ticks
+------------------------
+
+Derived from Line2d class. Note that ticks are markers.
+
+
+major_ticklabels, minor_ticklabels
+----------------------------------
+
+Derived from Text. Note that it is not a list of Text artist, but a
+single artist (similar to a collection).
+
+axislabel
+---------
+
+Derived from Text.
+
+
+Default AxisArtists
+-------------------
+
+By default, following for axis artists are defined.::
+
+ ax.axis["left"], ax.axis["bottom"], ax.axis["right"], ax.axis["top"]
+
+The ticklabels and axislabel of the top and the right axis are set to
+not visible.
+
+For example, if you want to change the color attributes of
+major_ticklabels of the bottom x-axis ::
+
+ ax.axis["bottom"].major_ticklabels.set_color("b")
+
+Similarly, to make ticklabels invisible ::
+
+ ax.axis["bottom"].major_ticklabels.set_visible(False)
+
+AxisAritst provides a helper method to control the visibility of ticks, ticklabels, and label. To make ticklabel invisible, ::
+
+ ax.axis["bottom"].toggle(ticklabels=False)
+
+To make all of ticks, ticklabels, and (axis) label invisible ::
+
+ ax.axis["bottom"].toggle(all=False)
+
+To turn all off but ticks on ::
+
+ ax.axis["bottom"].toggle(all=False, ticks=True)
+
+To turn all on but (axis) label off ::
+
+ ax.axis["bottom"].toggle(all=True, label=False))
+
+
+ax.axis's __getitem__ method can take multiple axis names. For
+example, to turn ticklabels of "top" and "right" axis on, ::
+
+ ax.axis["top","right"].toggle(ticklabels=True))
+
+Note that 'ax.axis["top","right"]' returns a simple proxy object that translate above code to something like below. ::
+
+ for n in ["top","right"]:
+ ax.axis[n].toggle(ticklabels=True))
+
+So, any return values in the for loop are ignored. And you shoud not
+use it anything more than a simple method.
+
+Like the list indexing ":" means all items, i.e., ::
+
+ ax.axis[:].major_ticks.set_color("r")
+
+changes tick color in all axis.
+
+
+HowTo
+=====
+
+1. Changing tick locations and label.
+
+ Same as the original mpl's axes.::
+
+ ax.set_xticks([1,2,3])
+
+2. Changing axis properties like color, etc.
+
+ Change the properties of appropriate artists. For example, to change
+ the color of the ticklabels::
+
+ 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.
+
+
+Rotaion and Alignment of TickLabels
+===================================
+
+This is also quite different from the original mpl and can be
+confusing. When you want to rotate the ticklabels, first consider
+using "set_axis_direction" method. ::
+
+ ax1.axis["left"].major_ticklabels.set_axis_direction("top")
+ ax1.axis["right"].label.set_axis_direction("left")
+
+.. plot:: mpl_toolkits/axes_grid/figures/simple_axis_direction01.py
+
+The parameter for set_axis_direction is one of ["left", "right",
+"bottom", "top"].
+
+You must understand some underlying concept of directions.
+
+ 1. There is a reference direction which is defined as the direction
+ of the axis line with increasing coordinate. For example, the
+ reference direction of the left x-axis is from bottom to top.
+
+ .. 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 with respect to the reference direction
+
+ 2. *ticklabel_direction* is either the right-hand side (+) of the
+ reference direction or the left-hand side (-).
+
+ .. plot:: mpl_toolkits/axes_grid/figures/axis_direction_demo_step02.py
+
+ 3. same for the *label_direction*
+
+ .. plot:: mpl_toolkits/axes_grid/figures/axis_direction_demo_step03.py
+
+ 4. ticks are by default drawn toward the opposite direction of the ticklabels.
+
+ 5. text rotation of ticklabels and label is determined in reference
+ to the *ticklabel_direction* or *label_direction*,
+ respectively. The rotation of ticklabels and label is anchored.
+
+ .. plot:: mpl_toolkits/axes_grid/figures/axis_direction_demo_step04.py
+
+
+On the other hand, there is a concept of "axis_direction". This is a
+default setting of above properties for each, "bottom", "left", "top",
+and "right" axis.
+
+ ========== =========== ========= ========== ========= ==========
+ ? ? left bottom right top
+ ---------- ----------- --------- ---------- --------- ----------
+ axislabel direction '-' '+' '+' '-'
+ axislabel rotation 180 0 0 180
+ axislabel va center top center bottom
+ axislabel ha right center right center
+ ticklabel direction '-' '+' '+' '-'
+ ticklabels rotation 90 0 -90 180
+ ticklabel ha right center right center
+ ticklabel va center baseline center baseline
+ ========== =========== ========= ========== ========= ==========
+
+
+And, 'set_axis_direction("top")' means to adjust the text rotation
+etc, for settings suitable for "top" axis. The concept of axis
+direction can be more clear with curved axis.
+
+.. plot:: mpl_toolkits/axes_grid/figures/demo_axis_direction.py
+
+The axis_drection can be adjusted in the AxisArtist level, or in the
+level of its child arists, i.e., ticks, ticklabels, and axis-label. ::
+
+ ax1.axis["left"].set_axis_direction("top")
+
+changes axis_direction of all the associated artist with the "left"
+axis, while ::
+
+ ax1.axis["left"].major_ticklabels.set_axis_direction("top")
+
+changes the axis_direction of only the major_ticklabels. Note that
+set_axis_direction in the AxisArtist level changes the
+ticklabel_direction and label_direction, while chainging the
+axis_direction of ticks, ticklabels, and axis-label does not affect
+them.
+
+
+If you want to make ticks outward and ticklabels inside the axes,
+use invert_ticklabel_direction method. ::
+
+ ax.axis[:].invert_ticklabel_direction()
+
+A related method is "set_tick_out". It makes ticks outward (as a
+matter of fact, it makes ticks toward the opposite direction of the
+default direction). ::
+
+ ax.axis[:].major_ticks.set_tick_out(True)
+
+.. plot:: mpl_toolkits/axes_grid/figures/simple_axis_direction03.py
+
+
+So, in summary,
+
+ * AxisArtist's methods
+ * set_axis_direction : "left", "right", "bottom", or "top"
+ * set_ticklabel_direction : "+" or "-"
+ * set_axislabel_direction : "+" or "-"
+ * invert_ticklabel_direction
+ * Ticks' methods (major_ticks and minor_ticks)
+ * set_tick_out : True or False
+ * set_ticksize : size in points
+ * TickLabels' methods (major_ticklabels and minor_ticklabels)
+ * set_axis_direction : "left", "right", "bottom", or "top"
+ * set_rotation : angle with respect to the renference direction
+ * set_ha and set_va : see below
+ * AxisLabels' methods (label)
+ * set_axis_direction : "left", "right", "bottom", or "top"
+ * set_rotation : angle with respect to the renference direction
+ * set_ha and set_va
+
+
+
+Adjusting ticklabels alignment
+------------------------------
+
+Alignment of TickLabels are treated specially. See below
+
+.. plot:: mpl_toolkits/axes_grid/figures/demo_ticklabel_alignment.py
+
+Adjusting pad
+--------------
+
+To change the pad between ticks and ticklabels ::
+
+ ax.axis["left"].major_ticklabels.set_pad(10)
+
+Or ticklabels and axis-label ::
+
+ ax.axis["left"].label.set_pad(10)
+
+
+.. plot:: mpl_toolkits/axes_grid/figures/simple_axis_pad.py
+
+
+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 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.axisartist.grid_helper_curvelinear \
+ import GridHelperCurveLinear
+ from mpl_toolkits.axisartist import Subplot
+
+ # from curved coordinate to rectlinear coordinate.
+ def tr(x, y):
+ x, y = np.asarray(x), np.asarray(y)
+ return x, y-x
+
+ # from rectlinear coordinate to curved coordinate.
+ def inv_tr(x,y):
+ x, y = np.asarray(x), np.asarray(y)
+ return x, y+x
+
+
+ grid_helper = GridHelperCurveLinear((tr, inv_tr))
+
+ ax1 = Subplot(fig, 1, 1, 1, grid_helper=grid_helper)
+
+ fig.add_subplot(ax1)
+
+
+You may use matplotlib's Transform instance instead (but a
+inverse transformation must be defined). Often, coordinate range in a
+curved coordinate system may have a limited range, or may have
+cycles. In those cases, a more customized version of grid helper is
+required. ::
+
+
+ import mpl_toolkits.axisartist.angle_helper as angle_helper
+
+ # PolarAxes.PolarTransform takes radian. However, we want our coordinate
+ # system in degree
+ tr = Affine2D().scale(np.pi/180., 1.) + PolarAxes.PolarTransform()
+
+
+ # 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)
+ # 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,
+ lon_cycle = 360,
+ lat_cycle = None,
+ lon_minmax = None,
+ lat_minmax = (0, np.inf),
+ )
+
+ # Find a grid values appropriate for the coordinate (degree,
+ # minute, second). The argument is a approximate number of grids.
+ grid_locator1 = angle_helper.LocatorDMS(12)
+
+ # And also uses an appropriate formatter. Note that,the
+ # acceptable Locator and Formatter class is a bit different than
+ # that of mpl's, and you cannot directly use mpl's Locator and
+ # Formatter here (but may be possible in the future).
+ tick_formatter1 = angle_helper.FormatterDMS()
+
+ grid_helper = GridHelperCurveLinear(tr,
+ extreme_finder=extreme_finder,
+ grid_locator1=grid_locator1,
+ tick_formatter1=tick_formatter1
+ )
+
+
+Again, the *transData* of the axes is still a rectlinear coordinate
+(image coordinate). You may manually do conversion between two
+coordinates, or you may use Parasite Axes for convenience.::
+
+ ax1 = SubplotHost(fig, 1, 2, 2, grid_helper=grid_helper)
+
+ # A parasite axes with given transform
+ ax2 = ParasiteAxesAuxTrans(ax1, tr, "equal")
+ # note that ax2.transData == tr + ax1.transData
+ # Anthing you draw in ax2 will match the ticks and grids of ax1.
+ ax1.parasites.append(ax2)
+
+
+.. plot:: mpl_toolkits/axes_grid/examples/demo_curvelinear_grid.py
+
+
+
+FloatingAxis
+============
+
+A floating axis is an axis one of whose data coordinate is fixed, i.e,
+its location is not fixed in Axes coordinate but changes as axes data
+limits changes. A floating axis can be created using
+*new_floating_axis* method. However, it is your responsibility that
+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
+ # (theta) is fixed at 60
+
+ ax1.axis["lat"] = axis = ax1.new_floating_axis(0, 60)
+ axis.label.set_text(r"$\theta = 60^{\circ}$")
+ axis.label.set_visible(True)
+
+
+See the first example of this page.
+
+Current Limitations and TODO's
+==============================
+
+The code need more refinement. Here is a incomplete list of issues and TODO's
+
+* No easy way to support a user customized tick location (for
+ curvelinear grid). A new Locator class needs to be created.
+
+* FloatingAxis may have coordinate limits, e.g., a floating axis of x
+ = 0, but y only spans from 0 to 1.
+
+* The location of axislabel of FloatingAxis needs to be optionally
+ given as a coordinate value. ex, a floating axis of x=0 with label at y=1
Deleted: trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axislines.rst
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axislines.rst 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/axislines.rst 2010-04-20 16:44:01 UTC (rev 8247)
@@ -1,456 +0,0 @@
-.. _axislines-manual:
-
-=========
-Axislines
-=========
-
-Axislines 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.
-
-* Axis elements (axis line(spine), ticks, ticklabel and axis labels)
- are drawn by a AxisArtist instance. Unlike Axis, left, right, top
- and bottom axis are drawn by separate artists. And each of them may
- have different tick location and different tick labels.
-
-* 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,
- gridlines are tied to ticks.
-
-* ticklines can be rotated if necessary (i.e, along the gridlines)
-
-In summary, all these changes was to support
-
-* a curvelinear grid.
-* a floating axis
-
-.. 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.
-
-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
-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
-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
-using set_ticks method and etc. should work as expected. But change in
-artist properties (e.g., color) will not work in general, although
-some effort has been made so that some often-change attributes (color,
-etc.) are respected.
-
-
-AxisArtist
-==========
-
-AxisArtist can be considered as a container artist with following
-attributes which will draw ticks, labels, etc.
-
- * line
- * major_ticks, major_ticklabels
- * minor_ticks, minor_ticklabels
- * offsetText
- * label
-
-
-line
-----
-
-Derived from Line2d class. Responsible for drawing a spinal(?) line.
-
-major_ticks, minor_ticks
-------------------------
-
-Derived from Line2d class. Note that ticks are markers.
-
-
-major_ticklabels, minor_ticklabels
-----------------------------------
-
-Derived from Text. Note that it is not a list of Text artist, but a
-single artist (similar to a collection).
-
-axislabel
----------
-
-Derived from Text.
-
-
-Default AxisArtists
--------------------
-
-By default, following for axis artists are defined.::
-
- ax.axis["left"], ax.axis["bottom"], ax.axis["right"], ax.axis["top"]
-
-The ticklabels and axislabel of the top and the right axis are set to
-not visible.
-
-For example, if you want to change the color attributes of
-major_ticklabels of the bottom x-axis ::
-
- ax.axis["bottom"].major_ticklabels.set_color("b")
-
-Similarly, to make ticklabels invisible ::
-
- ax.axis["bottom"].major_ticklabels.set_visible(False)
-
-AxisAritst provides a helper method to control the visibility of ticks, ticklabels, and label. To make ticklabel invisible, ::
-
- ax.axis["bottom"].toggle(ticklabels=False)
-
-To make all of ticks, ticklabels, and (axis) label invisible ::
-
- ax.axis["bottom"].toggle(all=False)
-
-To turn all off but ticks on ::
-
- ax.axis["bottom"].toggle(all=False, ticks=True)
-
-To turn all on but (axis) label off ::
-
- ax.axis["bottom"].toggle(all=True, label=False))
-
-
-ax.axis's __getitem__ method can take multiple axis names. For
-example, to turn ticklabels of "top" and "right" axis on, ::
-
- ax.axis["top","right"].toggle(ticklabels=True))
-
-Note that 'ax.axis["top","right"]' returns a simple proxy object that translate above code to something like below. ::
-
- for n in ["top","right"]:
- ax.axis[n].toggle(ticklabels=True))
-
-So, any return values in the for loop are ignored. And you shoud not
-use it anything more than a simple method.
-
-Like the list indexing ":" means all items, i.e., ::
-
- ax.axis[:].major_ticks.set_color("r")
-
-changes tick color in all axis.
-
-
-HowTo
-=====
-
-1. Changing tick locations and label.
-
- Same as the original mpl's axes.::
-
- ax.set_xticks([1,2,3])
-
-2. Changing axis properties like color, etc.
-
- Change the properties of appropriate artists. For example, to change
- the color of the ticklabels::
-
- 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.
-
-
-Rotaion and Alignment of TickLabels
-===================================
-
-This is also quite different from the original mpl and can be
-confusing. When you want to rotate the ticklabels, first consider
-using "set_axis_direction" method. ::
-
- ax1.axis["left"].major_ticklabels.set_axis_direction("top")
- ax1.axis["right"].label.set_axis_direction("left")
-
-.. plot:: mpl_toolkits/axes_grid/figures/simple_axis_direction01.py
-
-The parameter for set_axis_direction is one of ["left", "right",
-"bottom", "top"].
-
-You must understand some underlying concept of directions.
-
- 1. There is a reference direction which is defined as the direction
- of the axis line with increasing coordinate. For example, the
- reference direction of the left x-axis is from bottom to top.
-
- .. 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
-
- 2. *ticklabel_direction* is either the right-hand side (+) of the
- reference direction or the left-hand side (-).
-
- .. plot:: mpl_toolkits/axes_grid/figures/axis_direction_demo_step02.py
-
- 3. same for the *label_direction*
-
- .. plot:: mpl_toolkits/axes_grid/figures/axis_direction_demo_step03.py
-
- 4. ticks are by default drawn toward the opposite direction of the ticklabels.
-
- 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.
-
- .. plot:: mpl_toolkits/axes_grid/figures/axis_direction_demo_step04.py
-
-
-On the other hand, there is a concept of "axis_direction". This is a
-default setting of above properties for each, "bottom", "left", "top",
-and "right" axis.
-
- ========== =========== ========= ========== ========= ==========
- ? ? left bottom right top
- ---------- ----------- --------- ---------- --------- ----------
- axislabel direction '-' '+' '+' '-'
- axislabel rotation 180 0 0 180
- axislabel va center top center bottom
- axislabel ha right center right center
- ticklabel direction '-' '+' '+' '-'
- ticklabels rotation 90 0 -90 180
- ticklabel ha right center right center
- ticklabel va center baseline center baseline
- ========== =========== ========= ========== ========= ==========
-
-
-And, 'set_axis_direction("top")' means to adjust the text rotation
-etc, for settings suitable for "top" axis. The concept of axis
-direction can be more clear with curved axis.
-
-.. plot:: mpl_toolkits/axes_grid/figures/demo_axis_direction.py
-
-The axis_drection can be adjusted in the AxisArtist level, or in the
-level of its child arists, i.e., ticks, ticklabels, and axis-label. ::
-
- ax1.axis["left"].set_axis_direction("top")
-
-changes axis_direction of all the associated artist with the "left"
-axis, while ::
-
- ax1.axis["left"].major_ticklabels.set_axis_direction("top")
-
-changes the axis_direction of only the major_ticklabels. Note that
-set_axis_direction in the AxisArtist level changes the
-ticklabel_direction and label_direction, while chainging the
-axis_direction of ticks, ticklabels, and axis-label does not affect
-them.
-
-
-If you want to make ticks outward and ticklabels inside the axes,
-use invert_ticklabel_direction method. ::
-
- ax.axis[:].invert_ticklabel_direction()
-
-A related method is "set_tick_out". It makes ticks outward (as a
-matter of fact, it makes ticks toward the opposite direction of the
-default direction). ::
-
- ax.axis[:].major_ticks.set_tick_out(True)
-
-.. plot:: mpl_toolkits/axes_grid/figures/simple_axis_direction03.py
-
-
-So, in summary,
-
- * AxisArtist's methods
- * set_axis_direction : "left", "right", "bottom", or "top"
- * set_ticklabel_direction : "+" or "-"
- * set_axislabel_direction : "+" or "-"
- * invert_ticklabel_direction
- * Ticks' methods (major_ticks and minor_ticks)
- * set_tick_out : True or False
- * set_ticksize : size in points
- * TickLabels' methods (major_ticklabels and minor_ticklabels)
- * set_axis_direction : "left", "right", "bottom", or "top"
- * set_rotation : angle with respect to the renference direction
- * set_ha and set_va : see below
- * AxisLabels' methods (label)
- * set_axis_direction : "left", "right", "bottom", or "top"
- * set_rotation : angle with respect to the renference direction
- * set_ha and set_va
-
-
-
-Adjusting ticklabels alignment
-------------------------------
-
-Alignment of TickLabels are treated specially. See below
-
-.. plot:: mpl_toolkits/axes_grid/figures/demo_ticklabel_alignment.py
-
-Adjusting pad
---------------
-
-To change the pad between ticks and ticklabels ::
-
- ax.axis["left"].major_ticklabels.set_pad(10)
-
-Or ticklabels and axis-label ::
-
- ax.axis["left"].label.set_pad(10)
-
-
-.. plot:: mpl_toolkits/axes_grid/figures/simple_axis_pad.py
-
-
-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
-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 \
- import GridHelperCurveLinear
- from mpl_toolkits.axes_grid.axislines import Subplot
-
- # from curved coordinate to rectlinear coordinate.
- def tr(x, y):
- x, y = np.asarray(x), np.asarray(y)
- return x, y-x
-
- # from rectlinear coordinate to curved coordinate.
- def inv_tr(x,y):
- x, y = np.asarray(x), np.asarray(y)
- return x, y+x
-
-
- grid_helper = GridHelperCurveLinear((tr, inv_tr))
-
- ax1 = Subplot(fig, 1, 1, 1, grid_helper=grid_helper)
-
- fig.add_subplot(ax1)
-
-
-You may use matplotlib's Transform instance instead (but a
-inverse transformation must be defined). Often, coordinate range in a
-curved coordinate system may have a limited range, or may have
-cycles. In those cases, a more customized version of grid helper is
-required. ::
-
-
- import mpl_toolkits.axes_grid.angle_helper as angle_helper
-
- # PolarAxes.PolarTransform takes radian. However, we want our coordinate
- # system in degree
- tr = Affine2D().scale(np.pi/180., 1.) + PolarAxes.PolarTransform()
-
-
- # 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)
- # 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,
- lon_cycle = 360,
- lat_cycle = None,
- lon_minmax = None,
- lat_minmax = (0, np.inf),
- )
-
- # Find a grid values appropriate for the coordinate (degree,
- # minute, second). The argument is a approximate number of grids.
- grid_locator1 = angle_helper.LocatorDMS(12)
-
- # And also uses an appropriate formatter. Note that,the
- # acceptable Locator and Formatter class is a bit different than
- # that of mpl's, and you cannot directly use mpl's Locator and
- # Formatter here (but may be possible in the future).
- tick_formatter1 = angle_helper.FormatterDMS()
-
- grid_helper = GridHelperCurveLinear(tr,
- extreme_finder=extreme_finder,
- grid_locator1=grid_locator1,
- tick_formatter1=tick_formatter1
- )
-
-
-Again, the *transData* of the axes is still a rectlinear coordinate
-(image coordinate). You may manually do conversion between two
-coordinates, or you may use Parasite Axes for convenience.::
-
- ax1 = SubplotHost(fig, 1, 2, 2, grid_helper=grid_helper)
-
- # A parasite axes with given transform
- ax2 = ParasiteAxesAuxTrans(ax1, tr, "equal")
- # note that ax2.transData == tr + ax1.transData
- # Anthing you draw in ax2 will match the ticks and grids of ax1.
- ax1.parasites.append(ax2)
-
-
-.. plot:: mpl_toolkits/axes_grid/examples/demo_curvelinear_grid.py
-
-
-
-FloatingAxis
-============
-
-A floating axis is an axis one of whose data coordinate is fixed, i.e,
-its location is not fixed in Axes coordinate but changes as axes data
-limits changes. A floating axis can be created using
-*new_floating_axis* method. However, it is your responsibility that
-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
- # (theta) is fixed at 60
-
- ax1.axis["lat"] = axis = ax1.new_floating_axis(0, 60)
- axis.label.set_text(r"$\theta = 60^{\circ}$")
- axis.label.set_visible(True)
-
-
-See the first example of this page.
-
-Current Limitations and TODO's
-==============================
-
-The code need more refinement. Here is a incomplete list of issues and TODO's
-
-* No easy way to support a user customized tick location (for
- curvelinear grid). A new Locator class needs to be created.
-
-* FloatingAxis may have coordinate limits, e.g., a floating axis of x
- = 0, but y only spans from 0 to 1.
-
-* The location of axislabel of FloatingAxis needs to be optionally
- given as a coordinate value. ex, a floating axis of x=0 with label at y=1
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/index.rst
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/index.rst 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/index.rst 2010-04-20 16:44:01 UTC (rev 8247)
@@ -9,6 +9,6 @@
.. toctree::
- overview.rst
axes_divider.rst
- axislines.rst
+ axisartist.rst
+
Modified: trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/overview.rst
===================================================================
--- trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/overview.rst 2010-04-20 16:43:42 UTC (rev 8246)
+++ trunk/matplotlib/doc/mpl_toolkits/axes_grid/users/overview.rst 2010-04-20 16:44:01 UTC (rev 8247)
@@ -1,7 +1,10 @@
-========
-Overview
-========
+============================
+Overview of AxesGrid toolkit
+============================
+What is AxesGrid toolkit?
+=========================
+
The matplotlib AxesGrid toolkit is a collection of helper classes,
mainly to ease displaying (multiple) images in matplotlib.
@@ -9,30 +12,65 @@
: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`_
+.. 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)
+
+
+AxesGrid toolkit has two namespaces (*axes_grid1* and *axisartist*).
+*axisartist* contains custome Axes class that is meant to support for
+curvilinear grids (e.g., the world coordinate system in astronomy).
+Unlike mpl's original Axes class which uses Axes.xaxis and Axes.yaxis
+to draw ticks, ticklines and etc., Axes in axisartist uses special
+artist (AxisArtist) which can handle tick, ticklines and etc. for
+curved coordinate systems.
+
+.. plot:: mpl_toolkits/axes_grid/examples/demo_floating_axis.py
+
+Since it uses a special artists, some mpl commands that work on
+Axes.xaxis and Axes.yaxis may not work. See LINK for more detail.
+
+
+*axes_grid1* is a collection of helper classes to ease displaying
+(multiple) images with matplotlib. In matplotlib, the axes location
+(and size) is specified in the normalized figure coordinates, which
+may not be ideal for displaying images that needs to have a given
+aspect ratio. For example, it helps you to have a colobar whose
+height always matches that of the image. `AxesGrid`_, `RGB Axes`_ and
+`AxesDivider`_ are helper classes that deals with adjusting the
+location of (multiple) Axes. They 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. `AnchoredArtists`_
includes custom artists which are placed at some anchored position,
like the legend.
+.. plot:: mpl_toolkits/axes_grid/examples/demo_axes_grid.py
+AXES_GRID1
+==========
-AxesGrid
-========
+ImageGrid
+---------
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
+padding between them cannot be easily done in matplotlib. ImageGrid is
used in such case.
.. plot:: mpl_toolkits/axes_grid/examples/simple_axesgrid.py
@@ -60,7 +98,7 @@
-When initialized, AxesGrid creates given number (*ngrids* or *ncols* *
+When initialized, ImageGrid 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
@@ -140,32 +178,10 @@
.. plot:: mpl_toolkits/axes_grid/examples/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
+Behind the scene, the ImageGrid 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
@@ -181,44 +197,45 @@
*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.
+derived from the Locator. It provides *append_axes* method that
+creates a new axes on the given side of ("top", "right", "bottom" and
+"left") of the original axes.
-scatter_hist.py with AxesDivider
---------------------------------
-The "scatter_hist.py" example in mpl can be rewritten using
-*make_axes_locatable*. ::
+colorbar whose height (or width) in sync with the master axes
+-------------------------------------------------------------
- from mpl_toolkits.axes_grid import make_axes_locatable
+.. plot:: mpl_toolkits/axes_grid/figures/simple_colorbar.py
+ :include-source:
- 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)
+scatter_hist.py with AxesDivider
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- # the scatter plot:
+The "scatter_hist.py" example in mpl can be rewritten using
+*make_axes_locatable*. ::
+
+ axScatter = subplot(111)
axScatter.scatter(x, y)
axScatter.set_aspect(1.)
+ # create new axes on the right and on the top of the current axes.
+ divider = make_axes_locatable(axScatter)
+ axHistx = divider.append_axes("top", size=1.2, pad=0.1, sharex=axScatter)
+ axHisty = divider.append_axes("right", size=1.2, pad=0.1, sharey=axScatter)
+
+ # the scatter plot:
# 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/examples/scatter_hist.py
@@ -229,86 +246,42 @@
ParasiteAxes
-============
+------------
-The ParasiteAxes is a axes whose location is identical to its host
+The ParasiteAxes is an 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.
+if the host change its location (e.g., images).
+In most cases, you first create a host axes, which provides a few
+method that can be used to create parasite axes. They are *twinx*,
+*twiny* (which are similar to twinx and twiny in the matplotlib) and
+*twin*. *twin* takes an arbitraty tranfromation that maps between the
+data coordinates of the host axes and the parasite axes. *draw*
+method of the parasite axes are never called. Instead, host axes
+collects artists in parasite axes and draw them as if they belong to
+the host axes, i.e., artists in parasite axes are merged to those of
+the host axes and then drawn according to their zorder. The host and
+parasite axes modifies some of the axes behavior. 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. To create a host axes, you may use *host_suplot* or
+*host_axes* command.
+
+
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.
+*twin* without a transform argument treat the parasite axes to have a
+same data transform as the host. This can be useful when you want the
+top(or right)-axis to have different tick-locations, tick-labels, or
+tick-formatter for bottom(or left)-axis. ::
-
-.. plot:: mpl_toolkits/axes_grid/examples/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$",
@@ -318,23 +291,17 @@
.. plot:: mpl_toolkits/axes_grid/examples/simple_axisline4.py
-AxisLine Axes lets you create a custom axis, ::
- # make new (right-side) yaxis, but w...
[truncated message content] |
