Menu
▾
▴
SF.net SVN: matplotlib:[7489] branches/v0_99_maint/doc/users
|
From: <jd...@us...> - 2009-08-15 17:40:35
|
Revision: 7489
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7489&view=rev
Author: jdh2358
Date: 2009-08-15 17:40:27 +0000 (Sat, 15 Aug 2009)
Log Message:
-----------
some doc reorg
Modified Paths:
--------------
branches/v0_99_maint/doc/users/index.rst
branches/v0_99_maint/doc/users/index_text.rst
Added Paths:
-----------
branches/v0_99_maint/doc/users/annotations_guide.rst
branches/v0_99_maint/doc/users/annotations_overview.rst
branches/v0_99_maint/doc/users/legend.rst
branches/v0_99_maint/doc/users/transforms_tutorial.rst
Removed Paths:
-------------
branches/v0_99_maint/doc/users/annotations.rst
branches/v0_99_maint/doc/users/plotting/annotation.rst
branches/v0_99_maint/doc/users/plotting/legend.rst
Deleted: branches/v0_99_maint/doc/users/annotations.rst
===================================================================
--- branches/v0_99_maint/doc/users/annotations.rst 2009-08-14 18:11:05 UTC (rev 7488)
+++ branches/v0_99_maint/doc/users/annotations.rst 2009-08-15 17:40:27 UTC (rev 7489)
@@ -1,87 +0,0 @@
-.. _annotations-tutorial:
-
-Annotating text
-===============
-
-For a more detailed introduction to annotations, see
-:ref:`plotting-guide-annotation`.
-
-The uses of the basic :func:`~matplotlib.pyplot.text` command above
-place text at an arbitrary position on the Axes. A common use case of
-text is to annotate some feature of the plot, and the
-:func:`~matplotlib.Axes.annotate` method provides helper functionality
-to make annotations easy. In an annotation, there are two points to
-consider: the location being annotated represented by the argument
-``xy`` and the location of the text ``xytext``. Both of these
-arguments are ``(x,y)`` tuples.
-
-.. plot:: pyplots/annotation_basic.py
- :include-source:
-
-
-In this example, both the ``xy`` (arrow tip) and ``xytext`` locations
-(text location) are in data coordinates. There are a variety of other
-coordinate systems one can choose -- you can specify the coordinate
-system of ``xy`` and ``xytext`` with one of the following strings for
-``xycoords`` and ``textcoords`` (default is 'data')
-
-==================== ====================================================
-argument coordinate system
-==================== ====================================================
- 'figure points' points from the lower left corner of the figure
- 'figure pixels' pixels from the lower left corner of the figure
- 'figure fraction' 0,0 is lower left of figure and 1,1 is upper, right
- 'axes points' points from lower left corner of axes
- 'axes pixels' pixels from lower left corner of axes
- 'axes fraction' 0,1 is lower left of axes and 1,1 is upper right
- 'data' use the axes data coordinate system
-==================== ====================================================
-
-For example to place the text coordinates in fractional axes
-coordinates, one could do::
-
- ax.annotate('local max', xy=(3, 1), xycoords='data',
- xytext=(0.8, 0.95), textcoords='axes fraction',
- arrowprops=dict(facecolor='black', shrink=0.05),
- horizontalalignment='right', verticalalignment='top',
- )
-
-For physical coordinate systems (points or pixels) the origin is the
-(bottom, left) of the figure or axes. If the value is negative,
-however, the origin is from the (right, top) of the figure or axes,
-analogous to negative indexing of sequences.
-
-Optionally, you can specify arrow properties which draws an arrow
-from the text to the annotated point by giving a dictionary of arrow
-properties in the optional keyword argument ``arrowprops``.
-
-
-==================== =====================================================
-``arrowprops`` key description
-==================== =====================================================
-width the width of the arrow in points
-frac the fraction of the arrow length occupied by the head
-headwidth the width of the base of the arrow head in points
-shrink move the tip and base some percent away from
- the annotated point and text
-
-\*\*kwargs any key for :class:`matplotlib.patches.Polygon`,
- e.g. ``facecolor``
-==================== =====================================================
-
-
-In the example below, the ``xy`` point is in native coordinates
-(``xycoords`` defaults to 'data'). For a polar axes, this is in
-(theta, radius) space. The text in this example is placed in the
-fractional figure coordinate system. :class:`matplotlib.text.Text`
-keyword args like ``horizontalalignment``, ``verticalalignment`` and
-``fontsize are passed from the `~matplotlib.Axes.annotate` to the
-``Text`` instance
-
-.. plot:: pyplots/annotation_polar.py
- :include-source:
-
-For more on all the wild and wonderful things you can do with
-annotations, including fancy arrows, see :ref:`plotting-guide-annotation`
-and :ref:`pylab_examples-annotation_demo`.
-
Copied: branches/v0_99_maint/doc/users/annotations_guide.rst (from rev 7488, branches/v0_99_maint/doc/users/plotting/annotation.rst)
===================================================================
--- branches/v0_99_maint/doc/users/annotations_guide.rst (rev 0)
+++ branches/v0_99_maint/doc/users/annotations_guide.rst 2009-08-15 17:40:27 UTC (rev 7489)
@@ -0,0 +1,332 @@
+.. _plotting-guide-annotation:
+
+****************
+Annotating Axes
+****************
+
+Do not proceed unless you already have read
+:func:`~matplotlib.pyplot.text` and :func:`~matplotlib.pyplot.annotate`!
+
+
+Annotating with Text with Box
+=============================
+
+Let's start with a simple example.
+
+.. plot:: users/plotting/examples/annotate_text_arrow.py
+
+
+The :func:`~matplotlib.pyplot.text` function in the pyplot module (or
+text method of the Axes class) takes bbox keyword argument, and when
+given, a box around the text is drawn. ::
+
+ bbox_props = dict(boxstyle="rarrow,pad=0.3", fc="cyan", ec="b", lw=2)
+ t = ax.text(0, 0, "Direction", ha="center", va="center", rotation=45,
+ size=15,
+ bbox=bbox_props)
+
+
+The patch object associated with the text can be accessed by::
+
+ bb = t.get_bbox_patch()
+
+The return value is an instance of FancyBboxPatch and the patch
+properties like facecolor, edgewidth, etc. can be accessed and
+modified as usual. To change the shape of the box, use *set_boxstyle*
+method. ::
+
+ bb.set_boxstyle("rarrow", pad=0.6)
+
+The arguments are the name of the box style with its attributes as
+keyword arguments. Currently, followign box styles are implemented.
+
+ ========== ============== ==========================
+ Class Name Attrs
+ ========== ============== ==========================
+ LArrow ``larrow`` pad=0.3
+ RArrow ``rarrow`` pad=0.3
+ Round ``round`` pad=0.3,rounding_size=None
+ Round4 ``round4`` pad=0.3,rounding_size=None
+ Roundtooth ``roundtooth`` pad=0.3,tooth_size=None
+ Sawtooth ``sawtooth`` pad=0.3,tooth_size=None
+ Square ``square`` pad=0.3
+ ========== ============== ==========================
+
+.. plot:: mpl_examples/pylab_examples/fancybox_demo2.py
+
+
+Note that the attrubutes arguments can be specified within the style
+name with separating comma (this form can be used as "boxstyle" value
+of bbox argument when initializing the text instance) ::
+
+ bb.set_boxstyle("rarrow,pad=0.6")
+
+
+
+
+Annotating with Arrow
+=====================
+
+The :func:`~matplotlib.pyplot.annotate` function in the pyplot module
+(or annotate method of the Axes class) is used to draw an arrow
+connecting two points on the plot. ::
+
+ ax.annotate("Annotation",
+ xy=(x1, y1), xycoords='data',
+ xytext=(x2, y2), textcoords='offset points',
+ )
+
+This annotates a point at ``xy`` in the given coordinate (``xycoords``)
+with the text at ``xytext`` given in ``textcoords``. Often, the
+annotated point is specified in the *data* coordinate and the annotating
+text in *offset points*.
+See :func:`~matplotlib.pyplot.annotate` for available coordinate systems.
+
+An arrow connecting two point (xy & xytext) can be optionally drawn by
+specifying the ``arrowprops`` argument. To draw only an arrow, use
+empty string as the first argument. ::
+
+ ax.annotate("",
+ xy=(0.2, 0.2), xycoords='data',
+ xytext=(0.8, 0.8), textcoords='data',
+ arrowprops=dict(arrowstyle="->",
+ connectionstyle="arc3"),
+ )
+
+.. plot:: users/plotting/examples/annotate_simple01.py
+
+The arrow drawing takes a few steps.
+
+1. a connecting path between two points are created. This is
+ controlled by ``connectionstyle`` key value.
+
+2. If patch object is given (*patchA* & *patchB*), the path is clipped to
+ avoid the patch.
+
+3. The path is further shrinked by given amount of pixels (*shirnkA*
+ & *shrinkB*)
+
+4. The path is transmuted to arrow patch, which is controlled by the
+ ``arrowstyle`` key value.
+
+
+.. plot:: users/plotting/examples/annotate_explain.py
+
+
+The creation of the connecting path between two points is controlled by
+``connectionstyle`` key and follwing styles are available.
+
+ ========== =============================================
+ Name Attrs
+ ========== =============================================
+ ``angle`` angleA=90,angleB=0,rad=0.0
+ ``angle3`` angleA=90,angleB=0
+ ``arc`` angleA=0,angleB=0,armA=None,armB=None,rad=0.0
+ ``arc3`` rad=0.0
+ ``bar`` armA=0.0,armB=0.0,fraction=0.3,angle=None
+ ========== =============================================
+
+Note that "3" in ``angle3`` and ``arc3`` is meant to indicate that the
+resulting path is a quadratic spline segment (three control
+points). As will be discussed below, some arrow style option only can
+be used when the connecting path is a quadratic spline.
+
+The behavior of each connection style is (limitedly) demonstrated in the
+example below. (Warning : The behavior of the ``bar`` style is currently not
+well defined, it may be changed in the future).
+
+.. plot:: users/plotting/examples/connectionstyle_demo.py
+
+
+The connecting path (after clipping and shrinking) is then mutated to
+an arrow patch, according to the given ``arrowstyle``.
+
+ ========== =============================================
+ Name Attrs
+ ========== =============================================
+ ``-`` None
+ ``->`` head_length=0.4,head_width=0.2
+ ``-[`` widthB=1.0,lengthB=0.2,angleB=None
+ ``-|>`` head_length=0.4,head_width=0.2
+ ``<-`` head_length=0.4,head_width=0.2
+ ``<->`` head_length=0.4,head_width=0.2
+ ``<|-`` head_length=0.4,head_width=0.2
+ ``<|-|>`` head_length=0.4,head_width=0.2
+ ``fancy`` head_length=0.4,head_width=0.4,tail_width=0.4
+ ``simple`` head_length=0.5,head_width=0.5,tail_width=0.2
+ ``wedge`` tail_width=0.3,shrink_factor=0.5
+ ========== =============================================
+
+.. plot:: mpl_examples/pylab_examples/fancyarrow_demo.py
+
+Some arrowstyles only work with connection style that generates a
+quadratic-spline segment. They are ``fancy``, ``simple``, and ``wedge``.
+For these arrow styles, you must use "angle3" or "arc3" connection
+style.
+
+If the annotation string is given, the patchA is set to the bbox patch
+of the text by default.
+
+.. plot:: users/plotting/examples/annotate_simple02.py
+
+As in the text command, a box around the text can be drawn using
+the ``bbox`` argument.
+
+.. plot:: users/plotting/examples/annotate_simple03.py
+
+By default, the starting point is set to the center of the text
+extent. This can be adjusted with ``relpos`` key value. The values
+are normalized to the extent of the text. For example, (0,0) means
+lower-left corner and (1,1) means top-right.
+
+.. plot:: users/plotting/examples/annotate_simple04.py
+
+
+Using ConnectorPatch
+====================
+
+The ConnectorPatch is like an annotation without a text. While the
+annotate function is recommended in most of situation, the
+ConnectorPatch is useful when you want to connect points in different
+axes. ::
+
+ from matplotlib.patches import ConnectionPatch
+ xy = (0.2, 0.2)
+ con = ConnectionPatch(xyA=xy, xyB=xy, coordsA="data", coordsB="data",
+ axesA=ax1, axesB=ax2)
+ ax2.add_artist(con)
+
+The above code connects point xy in data coordinate of ``ax1`` to
+point xy int data coordiante of ``ax2``. Here is a simple example.
+
+.. plot:: users/plotting/examples/connect_simple01.py
+
+
+While the ConnectorPatch instance can be added to any axes, but you
+may want it to be added to the axes in the latter (?) of the axes
+drawing order to prevent overlap (?) by other axes.
+
+
+Placing Artist at the anchored location of the Axes
+===================================================
+
+There are class of artist that can be placed at the anchored location
+of the Axes. A common example is the legend. This type of artists can
+be created by using the OffsetBox class. A few predefined classes are
+available in ``mpl_toolkits.axes_grid.anchored_artists``. ::
+
+ from mpl_toolkits.axes_grid.anchored_artists import AnchoredText
+ at = AnchoredText("Figure 1a",
+ prop=dict(size=8), frameon=True,
+ loc=2,
+ )
+ at.patch.set_boxstyle("round,pad=0.,rounding_size=0.2")
+ ax.add_artist(at)
+
+
+.. plot:: users/plotting/examples/anchored_box01.py
+
+
+The *loc* keyword has same meaning as in the legend command.
+
+A simple application is when the size of the artist (or collection of
+artists) is knwon in pixel size during the time of creation. For
+example, If you want to draw a circle with fixed size of 20 pixel x 20
+pixel (radius = 10 pixel), you can utilize
+``AnchoredDrawingArea``. The instance is created with a size of the
+drawing area (in pixel). And user can add arbitrary artist to the
+drawing area. Note that the extents of the artists that are added to
+the drawing area has nothing to do with the placement of the drawing
+area itself. The initial size only matters. ::
+
+ from mpl_toolkits.axes_grid.anchored_artists import AnchoredDrawingArea
+
+ ada = AnchoredDrawingArea(20, 20, 0, 0,
+ loc=1, pad=0., frameon=False)
+ p1 = Circle((10, 10), 10)
+ ada.drawing_area.add_artist(p1)
+ p2 = Circle((30, 10), 5, fc="r")
+ ada.drawing_area.add_artist(p2)
+
+The artists that are added to the drawing area should not have
+transform set (they will be overridden) and the dimension of those
+artists are interpreted as a pixel coordinate, i.e., the radius of the
+circles in above example are 10 pixel and 5 pixel, respectively.
+
+.. plot:: users/plotting/examples/anchored_box02.py
+
+Sometimes, you want to your artists scale with data coordinate (or
+other coordinate than canvas pixel). You can use
+``AnchoredAuxTransformBox`` class. This is similar to
+``AnchoredDrawingArea`` except that the extent of the artist is
+determined during the drawing time respecting the specified transform. ::
+
+ from mpl_toolkits.axes_grid.anchored_artists import AnchoredAuxTransformBox
+
+ box = AnchoredAuxTransformBox(ax.transData, loc=2)
+ el = Ellipse((0,0), width=0.1, height=0.4, angle=30) # in data coordinates!
+ box.drawing_area.add_artist(el)
+
+The ellipse in the above example will have width and height
+corresponds to 0.1 and 0.4 in data coordinate and will be
+automatically scaled when the view limits of the axes change.
+
+.. plot:: users/plotting/examples/anchored_box03.py
+
+As in the legend, the bbox_to_anchor argument can be set. Using the
+HPacker and VPacker, you can have an arrangement(?) of artist as in the
+legend (as a matter of fact, this is how the legend is created).
+
+.. plot:: users/plotting/examples/anchored_box04.py
+
+Note that unlike the legend, the ``bbox_transform`` is set
+to IdentityTransform by default.
+
+Advanced Topics
+***************
+
+Zoom effect between Axes
+========================
+
+mpl_toolkits.axes_grid.inset_locator defines some patch classs useful
+for interconnect two axes. Understanding the code requires some
+knowledge of how mpl's transform works. But, utilizing it will be
+straight forward.
+
+
+.. plot:: mpl_examples/pylab_examples/axes_zoom_effect.py
+
+
+Define Custom BoxStyle
+======================
+
+You can use a custom box style. The value for the ``boxstyle`` can be a
+callable object in following forms.::
+
+ def __call__(self, x0, y0, width, height, mutation_size,
+ aspect_ratio=1.):
+ """
+ Given the location and size of the box, return the path of
+ the box around it.
+
+ - *x0*, *y0*, *width*, *height* : location and size of the box
+ - *mutation_size* : a reference scale for the mutation.
+ - *aspect_ratio* : aspect-ration for the mutation.
+ """
+ path = ...
+ return path
+
+Here is a complete example.
+
+.. plot:: users/plotting/examples/custom_boxstyle01.py
+
+However, it is recommended that you derive from the
+matplotlib.patches.BoxStyle._Base as demonstrated below.
+
+.. plot:: users/plotting/examples/custom_boxstyle02.py
+ :include-source:
+
+
+Similarly, you can define custom ConnectionStyle and Custome ArrowStyle.
+See the source code of ``lib/matplotlib/patches.py`` and check
+how each style class is defined.
Copied: branches/v0_99_maint/doc/users/annotations_overview.rst (from rev 7488, branches/v0_99_maint/doc/users/annotations.rst)
===================================================================
--- branches/v0_99_maint/doc/users/annotations_overview.rst (rev 0)
+++ branches/v0_99_maint/doc/users/annotations_overview.rst 2009-08-15 17:40:27 UTC (rev 7489)
@@ -0,0 +1,87 @@
+.. _annotations-tutorial:
+
+Annotating text
+===============
+
+For a more detailed introduction to annotations, see
+:ref:`plotting-guide-annotation`.
+
+The uses of the basic :func:`~matplotlib.pyplot.text` command above
+place text at an arbitrary position on the Axes. A common use case of
+text is to annotate some feature of the plot, and the
+:func:`~matplotlib.Axes.annotate` method provides helper functionality
+to make annotations easy. In an annotation, there are two points to
+consider: the location being annotated represented by the argument
+``xy`` and the location of the text ``xytext``. Both of these
+arguments are ``(x,y)`` tuples.
+
+.. plot:: pyplots/annotation_basic.py
+ :include-source:
+
+
+In this example, both the ``xy`` (arrow tip) and ``xytext`` locations
+(text location) are in data coordinates. There are a variety of other
+coordinate systems one can choose -- you can specify the coordinate
+system of ``xy`` and ``xytext`` with one of the following strings for
+``xycoords`` and ``textcoords`` (default is 'data')
+
+==================== ====================================================
+argument coordinate system
+==================== ====================================================
+ 'figure points' points from the lower left corner of the figure
+ 'figure pixels' pixels from the lower left corner of the figure
+ 'figure fraction' 0,0 is lower left of figure and 1,1 is upper, right
+ 'axes points' points from lower left corner of axes
+ 'axes pixels' pixels from lower left corner of axes
+ 'axes fraction' 0,1 is lower left of axes and 1,1 is upper right
+ 'data' use the axes data coordinate system
+==================== ====================================================
+
+For example to place the text coordinates in fractional axes
+coordinates, one could do::
+
+ ax.annotate('local max', xy=(3, 1), xycoords='data',
+ xytext=(0.8, 0.95), textcoords='axes fraction',
+ arrowprops=dict(facecolor='black', shrink=0.05),
+ horizontalalignment='right', verticalalignment='top',
+ )
+
+For physical coordinate systems (points or pixels) the origin is the
+(bottom, left) of the figure or axes. If the value is negative,
+however, the origin is from the (right, top) of the figure or axes,
+analogous to negative indexing of sequences.
+
+Optionally, you can specify arrow properties which draws an arrow
+from the text to the annotated point by giving a dictionary of arrow
+properties in the optional keyword argument ``arrowprops``.
+
+
+==================== =====================================================
+``arrowprops`` key description
+==================== =====================================================
+width the width of the arrow in points
+frac the fraction of the arrow length occupied by the head
+headwidth the width of the base of the arrow head in points
+shrink move the tip and base some percent away from
+ the annotated point and text
+
+\*\*kwargs any key for :class:`matplotlib.patches.Polygon`,
+ e.g. ``facecolor``
+==================== =====================================================
+
+
+In the example below, the ``xy`` point is in native coordinates
+(``xycoords`` defaults to 'data'). For a polar axes, this is in
+(theta, radius) space. The text in this example is placed in the
+fractional figure coordinate system. :class:`matplotlib.text.Text`
+keyword args like ``horizontalalignment``, ``verticalalignment`` and
+``fontsize are passed from the `~matplotlib.Axes.annotate` to the
+``Text`` instance
+
+.. plot:: pyplots/annotation_polar.py
+ :include-source:
+
+For more on all the wild and wonderful things you can do with
+annotations, including fancy arrows, see :ref:`plotting-guide-annotation`
+and :ref:`pylab_examples-annotation_demo`.
+
Modified: branches/v0_99_maint/doc/users/index.rst
===================================================================
--- branches/v0_99_maint/doc/users/index.rst 2009-08-14 18:11:05 UTC (rev 7488)
+++ branches/v0_99_maint/doc/users/index.rst 2009-08-15 17:40:27 UTC (rev 7489)
@@ -20,8 +20,11 @@
shell.rst
index_text.rst
artists.rst
+ legend_guide.rst
event_handling.rst
- plotting.rst
+ annotation_guide.rst
+ legend.rst
+ transforms_tutorial.rst
toolkits.rst
screenshots.rst
whats_new.rst
Modified: branches/v0_99_maint/doc/users/index_text.rst
===================================================================
--- branches/v0_99_maint/doc/users/index_text.rst 2009-08-14 18:11:05 UTC (rev 7488)
+++ branches/v0_99_maint/doc/users/index_text.rst 2009-08-15 17:40:27 UTC (rev 7489)
@@ -9,6 +9,6 @@
text_props.rst
mathtext.rst
usetex.rst
- annotations.rst
+ annotations_intro.rst
Copied: branches/v0_99_maint/doc/users/legend.rst (from rev 7488, branches/v0_99_maint/doc/users/plotting/legend.rst)
===================================================================
--- branches/v0_99_maint/doc/users/legend.rst (rev 0)
+++ branches/v0_99_maint/doc/users/legend.rst 2009-08-15 17:40:27 UTC (rev 7489)
@@ -0,0 +1,182 @@
+.. _plotting-guide-legend:
+
+************
+Legend guide
+************
+
+Do not proceed unless you already have read :func:`~matplotlib.pyplot.legend` and
+:class:`matplotlib.legend.Legend`!
+
+
+What to be displayed
+====================
+
+The legend command has a following call signature::
+
+ legend(*args, **kwargs)
+
+If len(args) is 2, the first argument should be a list of artist to be
+labeled, and the second argument should a list of string labels. If
+len(args) is 0, it automatically generate the legend from label
+properties of the child artists by calling
+:meth:`~matplotlib.axes.Axes.get_legend_handles_labels` method.
+For example, *ax.legend()* is equivalent to::
+
+ handles, labels = ax.get_legend_handles_labels()
+ ax.legend(handles, labels)
+
+The :meth:`~matplotlib.axes.Axes.get_legend_handles_labels` method
+returns a tuple of two lists, i.e., list of artists and list of labels
+(python string). However, it does not return all of its child
+artists. It returns all artists in *ax.lines* and *ax.patches* and
+some artists in *ax.collection* which are instance of
+:class:`~matplotlib.collections.LineCollection` or
+:class:`~matplotlib.collections.RegularPolyCollection`. The label
+attributes (returned by get_label() method) of collected artists are
+used as text labels. If label attribute is empty string or starts with
+"_", that artist will be ignored.
+
+
+ * Note that not all kind of artists are supported by the legend. The
+ following is the list of artists that are currently supported.
+
+ * :class:`~matplotlib.lines.Line2D`
+ * :class:`~matplotlib.patches.Patch`
+ * :class:`~matplotlib.collections.LineCollection`
+ * :class:`~matplotlib.collections.RegularPolyCollection`
+
+ Unfortunately, there is no easy workaround when you need legend for
+ an artist not in the above list (You may use one of the supported
+ artist as a proxy. See below), or customize it beyond what is
+ supported by :class:`matplotlib.legend.Legend`.
+
+ * Remember that some *pyplot* commands return artist not supported by
+ legend, e.g., :func:`~matplotlib.pyplot.fill_between` returns
+ :class:`~matplotlib.collections.PolyCollection` that is not
+ supported. Or some return multiple artists. For example,
+ :func:`~matplotlib.pyplot.plot` returns list of
+ :class:`~matplotlib.lines.Line2D` instances, and
+ :func:`~matplotlib.pyplot.errorbar` returns a length 3 tuple of
+ :class:`~matplotlib.lines.Line2D` instances.
+
+ * The legend does not care about the axes that given artists belongs,
+ i.e., the artists may belong to other axes or even none.
+
+
+Adjusting the Order of Legend items
+-----------------------------------
+
+When you want to customize the list of artists to be displayed in the
+legend, or their order of appearance. There are a two options. First,
+you can keep lists of artists and labels, and explicitly use these for
+the first two argument of the legend call.::
+
+ p1, = plot([1,2,3])
+ p2, = plot([3,2,1])
+ p3, = plot([2,3,1])
+ legend([p2, p1], ["line 2", "line 1"])
+
+Or you may use :meth:`~matplotlib.axes.Axes.get_legend_handles_labels`
+to retrieve list of artist and labels and manipulate them before
+feeding them to legend call.::
+
+ ax = subplot(1,1,1)
+ p1, = ax.plot([1,2,3], label="line 1")
+ p2, = ax.plot([3,2,1], label="line 2")
+ p3, = ax.plot([2,3,1], label="line 3")
+
+ handles, labels = ax.get_legend_handles_labels()
+
+ # reverse the order
+ ax.legend(handles[::-1], labels[::-1])
+
+ # or sort them by labels
+ import operator
+ hl = sorted(zip(handles, labels),
+ key=operator.itemgetter(1))
+ handles2, labels2 = zip(*hl)
+
+ ax.legend(handles2, labels2)
+
+
+Using Proxy Artist
+------------------
+
+When you want to display legend for an artist not supported by the
+matplotlib, you may use other supported artist as a proxy. For
+example, you may creates an proxy artist without adding it to the axes
+(so the proxy artist will not be drawn in the main axes) and feet it
+to the legend function.::
+
+ p = Rectangle((0, 0), 1, 1, fc="r")
+ legend([p], ["Red Rectangle"])
+
+
+Multicolumn Legend
+==================
+
+By specifying the keyword argument *ncol*, you can have a multi-column
+legend. Also, mode="expand" horizontally expand the legend to fill the
+axes area. See `legend_demo3.py
+<http://matplotlib.sourceforge.net/examples/pylab_examples/legend_demo3.html>`_
+for example.
+
+
+Legend location
+===============
+
+The location of the legend can be specified by the keyword argument
+*loc*, either by string or a integer number.
+
+============= ======
+ String Number
+============= ======
+ upper right 1
+ upper left 2
+ lower left 3
+ lower right 4
+ right 5
+ center left 6
+ center right 7
+ lower center 8
+ upper center 9
+ center 10
+============= ======
+
+By default, the legend will anchor to the bbox of the axes
+(for legend) or the bbox of the figure (figlegend). You can specify
+your own bbox using *bbox_to_anchor* argument. *bbox_to_anchor* can be an
+instance of :class:`~matplotlib.transforms.BboxBase`, a tuple of 4
+floats (x, y, width, height of the bbox), or a tuple of 2 floats (x, y
+with width=height=0). Unless *bbox_transform* argument is given, the
+coordinates (even for the bbox instance) are considered as normalized
+axes coordinates.
+
+For example, if you want your axes legend located at the figure corner
+(instead of the axes corner)::
+
+ l = legend(bbox_to_anchor=(0, 0, 1, 1), transform=gcf().transFigure)
+
+Also, you can place above or outer right-hand side of the axes,
+
+.. plot:: users/plotting/examples/simple_legend01.py
+ :include-source:
+
+
+Multiple Legend
+===============
+
+Sometime, you want to split the legend into multiple ones.::
+
+ p1, = plot([1,2,3])
+ p2, = plot([3,2,1])
+ legend([p1], ["Test1"], loc=1)
+ legend([p2], ["Test2"], loc=4)
+
+However, the above code only shows the second legend. When the legend
+command is called, a new legend instance is created and old ones are
+removed from the axes. Thus, you need to manually add the removed
+legend.
+
+.. plot:: users/plotting/examples/simple_legend02.py
+ :include-source:
Deleted: branches/v0_99_maint/doc/users/plotting/annotation.rst
===================================================================
--- branches/v0_99_maint/doc/users/plotting/annotation.rst 2009-08-14 18:11:05 UTC (rev 7488)
+++ branches/v0_99_maint/doc/users/plotting/annotation.rst 2009-08-15 17:40:27 UTC (rev 7489)
@@ -1,332 +0,0 @@
-.. _plotting-guide-annotation:
-
-****************
-Annotating Axes
-****************
-
-Do not proceed unless you already have read
-:func:`~matplotlib.pyplot.text` and :func:`~matplotlib.pyplot.annotate`!
-
-
-Annotating with Text with Box
-=============================
-
-Let's start with a simple example.
-
-.. plot:: users/plotting/examples/annotate_text_arrow.py
-
-
-The :func:`~matplotlib.pyplot.text` function in the pyplot module (or
-text method of the Axes class) takes bbox keyword argument, and when
-given, a box around the text is drawn. ::
-
- bbox_props = dict(boxstyle="rarrow,pad=0.3", fc="cyan", ec="b", lw=2)
- t = ax.text(0, 0, "Direction", ha="center", va="center", rotation=45,
- size=15,
- bbox=bbox_props)
-
-
-The patch object associated with the text can be accessed by::
-
- bb = t.get_bbox_patch()
-
-The return value is an instance of FancyBboxPatch and the patch
-properties like facecolor, edgewidth, etc. can be accessed and
-modified as usual. To change the shape of the box, use *set_boxstyle*
-method. ::
-
- bb.set_boxstyle("rarrow", pad=0.6)
-
-The arguments are the name of the box style with its attributes as
-keyword arguments. Currently, followign box styles are implemented.
-
- ========== ============== ==========================
- Class Name Attrs
- ========== ============== ==========================
- LArrow ``larrow`` pad=0.3
- RArrow ``rarrow`` pad=0.3
- Round ``round`` pad=0.3,rounding_size=None
- Round4 ``round4`` pad=0.3,rounding_size=None
- Roundtooth ``roundtooth`` pad=0.3,tooth_size=None
- Sawtooth ``sawtooth`` pad=0.3,tooth_size=None
- Square ``square`` pad=0.3
- ========== ============== ==========================
-
-.. plot:: mpl_examples/pylab_examples/fancybox_demo2.py
-
-
-Note that the attrubutes arguments can be specified within the style
-name with separating comma (this form can be used as "boxstyle" value
-of bbox argument when initializing the text instance) ::
-
- bb.set_boxstyle("rarrow,pad=0.6")
-
-
-
-
-Annotating with Arrow
-=====================
-
-The :func:`~matplotlib.pyplot.annotate` function in the pyplot module
-(or annotate method of the Axes class) is used to draw an arrow
-connecting two points on the plot. ::
-
- ax.annotate("Annotation",
- xy=(x1, y1), xycoords='data',
- xytext=(x2, y2), textcoords='offset points',
- )
-
-This annotates a point at ``xy`` in the given coordinate (``xycoords``)
-with the text at ``xytext`` given in ``textcoords``. Often, the
-annotated point is specified in the *data* coordinate and the annotating
-text in *offset points*.
-See :func:`~matplotlib.pyplot.annotate` for available coordinate systems.
-
-An arrow connecting two point (xy & xytext) can be optionally drawn by
-specifying the ``arrowprops`` argument. To draw only an arrow, use
-empty string as the first argument. ::
-
- ax.annotate("",
- xy=(0.2, 0.2), xycoords='data',
- xytext=(0.8, 0.8), textcoords='data',
- arrowprops=dict(arrowstyle="->",
- connectionstyle="arc3"),
- )
-
-.. plot:: users/plotting/examples/annotate_simple01.py
-
-The arrow drawing takes a few steps.
-
-1. a connecting path between two points are created. This is
- controlled by ``connectionstyle`` key value.
-
-2. If patch object is given (*patchA* & *patchB*), the path is clipped to
- avoid the patch.
-
-3. The path is further shrinked by given amount of pixels (*shirnkA*
- & *shrinkB*)
-
-4. The path is transmuted to arrow patch, which is controlled by the
- ``arrowstyle`` key value.
-
-
-.. plot:: users/plotting/examples/annotate_explain.py
-
-
-The creation of the connecting path between two points is controlled by
-``connectionstyle`` key and follwing styles are available.
-
- ========== =============================================
- Name Attrs
- ========== =============================================
- ``angle`` angleA=90,angleB=0,rad=0.0
- ``angle3`` angleA=90,angleB=0
- ``arc`` angleA=0,angleB=0,armA=None,armB=None,rad=0.0
- ``arc3`` rad=0.0
- ``bar`` armA=0.0,armB=0.0,fraction=0.3,angle=None
- ========== =============================================
-
-Note that "3" in ``angle3`` and ``arc3`` is meant to indicate that the
-resulting path is a quadratic spline segment (three control
-points). As will be discussed below, some arrow style option only can
-be used when the connecting path is a quadratic spline.
-
-The behavior of each connection style is (limitedly) demonstrated in the
-example below. (Warning : The behavior of the ``bar`` style is currently not
-well defined, it may be changed in the future).
-
-.. plot:: users/plotting/examples/connectionstyle_demo.py
-
-
-The connecting path (after clipping and shrinking) is then mutated to
-an arrow patch, according to the given ``arrowstyle``.
-
- ========== =============================================
- Name Attrs
- ========== =============================================
- ``-`` None
- ``->`` head_length=0.4,head_width=0.2
- ``-[`` widthB=1.0,lengthB=0.2,angleB=None
- ``-|>`` head_length=0.4,head_width=0.2
- ``<-`` head_length=0.4,head_width=0.2
- ``<->`` head_length=0.4,head_width=0.2
- ``<|-`` head_length=0.4,head_width=0.2
- ``<|-|>`` head_length=0.4,head_width=0.2
- ``fancy`` head_length=0.4,head_width=0.4,tail_width=0.4
- ``simple`` head_length=0.5,head_width=0.5,tail_width=0.2
- ``wedge`` tail_width=0.3,shrink_factor=0.5
- ========== =============================================
-
-.. plot:: mpl_examples/pylab_examples/fancyarrow_demo.py
-
-Some arrowstyles only work with connection style that generates a
-quadratic-spline segment. They are ``fancy``, ``simple``, and ``wedge``.
-For these arrow styles, you must use "angle3" or "arc3" connection
-style.
-
-If the annotation string is given, the patchA is set to the bbox patch
-of the text by default.
-
-.. plot:: users/plotting/examples/annotate_simple02.py
-
-As in the text command, a box around the text can be drawn using
-the ``bbox`` argument.
-
-.. plot:: users/plotting/examples/annotate_simple03.py
-
-By default, the starting point is set to the center of the text
-extent. This can be adjusted with ``relpos`` key value. The values
-are normalized to the extent of the text. For example, (0,0) means
-lower-left corner and (1,1) means top-right.
-
-.. plot:: users/plotting/examples/annotate_simple04.py
-
-
-Using ConnectorPatch
-====================
-
-The ConnectorPatch is like an annotation without a text. While the
-annotate function is recommended in most of situation, the
-ConnectorPatch is useful when you want to connect points in different
-axes. ::
-
- from matplotlib.patches import ConnectionPatch
- xy = (0.2, 0.2)
- con = ConnectionPatch(xyA=xy, xyB=xy, coordsA="data", coordsB="data",
- axesA=ax1, axesB=ax2)
- ax2.add_artist(con)
-
-The above code connects point xy in data coordinate of ``ax1`` to
-point xy int data coordiante of ``ax2``. Here is a simple example.
-
-.. plot:: users/plotting/examples/connect_simple01.py
-
-
-While the ConnectorPatch instance can be added to any axes, but you
-may want it to be added to the axes in the latter (?) of the axes
-drawing order to prevent overlap (?) by other axes.
-
-
-Placing Artist at the anchored location of the Axes
-===================================================
-
-There are class of artist that can be placed at the anchored location
-of the Axes. A common example is the legend. This type of artists can
-be created by using the OffsetBox class. A few predefined classes are
-available in ``mpl_toolkits.axes_grid.anchored_artists``. ::
-
- from mpl_toolkits.axes_grid.anchored_artists import AnchoredText
- at = AnchoredText("Figure 1a",
- prop=dict(size=8), frameon=True,
- loc=2,
- )
- at.patch.set_boxstyle("round,pad=0.,rounding_size=0.2")
- ax.add_artist(at)
-
-
-.. plot:: users/plotting/examples/anchored_box01.py
-
-
-The *loc* keyword has same meaning as in the legend command.
-
-A simple application is when the size of the artist (or collection of
-artists) is knwon in pixel size during the time of creation. For
-example, If you want to draw a circle with fixed size of 20 pixel x 20
-pixel (radius = 10 pixel), you can utilize
-``AnchoredDrawingArea``. The instance is created with a size of the
-drawing area (in pixel). And user can add arbitrary artist to the
-drawing area. Note that the extents of the artists that are added to
-the drawing area has nothing to do with the placement of the drawing
-area itself. The initial size only matters. ::
-
- from mpl_toolkits.axes_grid.anchored_artists import AnchoredDrawingArea
-
- ada = AnchoredDrawingArea(20, 20, 0, 0,
- loc=1, pad=0., frameon=False)
- p1 = Circle((10, 10), 10)
- ada.drawing_area.add_artist(p1)
- p2 = Circle((30, 10), 5, fc="r")
- ada.drawing_area.add_artist(p2)
-
-The artists that are added to the drawing area should not have
-transform set (they will be overridden) and the dimension of those
-artists are interpreted as a pixel coordinate, i.e., the radius of the
-circles in above example are 10 pixel and 5 pixel, respectively.
-
-.. plot:: users/plotting/examples/anchored_box02.py
-
-Sometimes, you want to your artists scale with data coordinate (or
-other coordinate than canvas pixel). You can use
-``AnchoredAuxTransformBox`` class. This is similar to
-``AnchoredDrawingArea`` except that the extent of the artist is
-determined during the drawing time respecting the specified transform. ::
-
- from mpl_toolkits.axes_grid.anchored_artists import AnchoredAuxTransformBox
-
- box = AnchoredAuxTransformBox(ax.transData, loc=2)
- el = Ellipse((0,0), width=0.1, height=0.4, angle=30) # in data coordinates!
- box.drawing_area.add_artist(el)
-
-The ellipse in the above example will have width and height
-corresponds to 0.1 and 0.4 in data coordinate and will be
-automatically scaled when the view limits of the axes change.
-
-.. plot:: users/plotting/examples/anchored_box03.py
-
-As in the legend, the bbox_to_anchor argument can be set. Using the
-HPacker and VPacker, you can have an arrangement(?) of artist as in the
-legend (as a matter of fact, this is how the legend is created).
-
-.. plot:: users/plotting/examples/anchored_box04.py
-
-Note that unlike the legend, the ``bbox_transform`` is set
-to IdentityTransform by default.
-
-Advanced Topics
-***************
-
-Zoom effect between Axes
-========================
-
-mpl_toolkits.axes_grid.inset_locator defines some patch classs useful
-for interconnect two axes. Understanding the code requires some
-knowledge of how mpl's transform works. But, utilizing it will be
-straight forward.
-
-
-.. plot:: mpl_examples/pylab_examples/axes_zoom_effect.py
-
-
-Define Custom BoxStyle
-======================
-
-You can use a custom box style. The value for the ``boxstyle`` can be a
-callable object in following forms.::
-
- def __call__(self, x0, y0, width, height, mutation_size,
- aspect_ratio=1.):
- """
- Given the location and size of the box, return the path of
- the box around it.
-
- - *x0*, *y0*, *width*, *height* : location and size of the box
- - *mutation_size* : a reference scale for the mutation.
- - *aspect_ratio* : aspect-ration for the mutation.
- """
- path = ...
- return path
-
-Here is a complete example.
-
-.. plot:: users/plotting/examples/custom_boxstyle01.py
-
-However, it is recommended that you derive from the
-matplotlib.patches.BoxStyle._Base as demonstrated below.
-
-.. plot:: users/plotting/examples/custom_boxstyle02.py
- :include-source:
-
-
-Similarly, you can define custom ConnectionStyle and Custome ArrowStyle.
-See the source code of ``lib/matplotlib/patches.py`` and check
-how each style class is defined.
Deleted: branches/v0_99_maint/doc/users/plotting/legend.rst
===================================================================
--- branches/v0_99_maint/doc/users/plotting/legend.rst 2009-08-14 18:11:05 UTC (rev 7488)
+++ branches/v0_99_maint/doc/users/plotting/legend.rst 2009-08-15 17:40:27 UTC (rev 7489)
@@ -1,182 +0,0 @@
-.. _plotting-guide-legend:
-
-************
-Legend guide
-************
-
-Do not proceed unless you already have read :func:`~matplotlib.pyplot.legend` and
-:class:`matplotlib.legend.Legend`!
-
-
-What to be displayed
-====================
-
-The legend command has a following call signature::
-
- legend(*args, **kwargs)
-
-If len(args) is 2, the first argument should be a list of artist to be
-labeled, and the second argument should a list of string labels. If
-len(args) is 0, it automatically generate the legend from label
-properties of the child artists by calling
-:meth:`~matplotlib.axes.Axes.get_legend_handles_labels` method.
-For example, *ax.legend()* is equivalent to::
-
- handles, labels = ax.get_legend_handles_labels()
- ax.legend(handles, labels)
-
-The :meth:`~matplotlib.axes.Axes.get_legend_handles_labels` method
-returns a tuple of two lists, i.e., list of artists and list of labels
-(python string). However, it does not return all of its child
-artists. It returns all artists in *ax.lines* and *ax.patches* and
-some artists in *ax.collection* which are instance of
-:class:`~matplotlib.collections.LineCollection` or
-:class:`~matplotlib.collections.RegularPolyCollection`. The label
-attributes (returned by get_label() method) of collected artists are
-used as text labels. If label attribute is empty string or starts with
-"_", that artist will be ignored.
-
-
- * Note that not all kind of artists are supported by the legend. The
- following is the list of artists that are currently supported.
-
- * :class:`~matplotlib.lines.Line2D`
- * :class:`~matplotlib.patches.Patch`
- * :class:`~matplotlib.collections.LineCollection`
- * :class:`~matplotlib.collections.RegularPolyCollection`
-
- Unfortunately, there is no easy workaround when you need legend for
- an artist not in the above list (You may use one of the supported
- artist as a proxy. See below), or customize it beyond what is
- supported by :class:`matplotlib.legend.Legend`.
-
- * Remember that some *pyplot* commands return artist not supported by
- legend, e.g., :func:`~matplotlib.pyplot.fill_between` returns
- :class:`~matplotlib.collections.PolyCollection` that is not
- supported. Or some return multiple artists. For example,
- :func:`~matplotlib.pyplot.plot` returns list of
- :class:`~matplotlib.lines.Line2D` instances, and
- :func:`~matplotlib.pyplot.errorbar` returns a length 3 tuple of
- :class:`~matplotlib.lines.Line2D` instances.
-
- * The legend does not care about the axes that given artists belongs,
- i.e., the artists may belong to other axes or even none.
-
-
-Adjusting the Order of Legend items
------------------------------------
-
-When you want to customize the list of artists to be displayed in the
-legend, or their order of appearance. There are a two options. First,
-you can keep lists of artists and labels, and explicitly use these for
-the first two argument of the legend call.::
-
- p1, = plot([1,2,3])
- p2, = plot([3,2,1])
- p3, = plot([2,3,1])
- legend([p2, p1], ["line 2", "line 1"])
-
-Or you may use :meth:`~matplotlib.axes.Axes.get_legend_handles_labels`
-to retrieve list of artist and labels and manipulate them before
-feeding them to legend call.::
-
- ax = subplot(1,1,1)
- p1, = ax.plot([1,2,3], label="line 1")
- p2, = ax.plot([3,2,1], label="line 2")
- p3, = ax.plot([2,3,1], label="line 3")
-
- handles, labels = ax.get_legend_handles_labels()
-
- # reverse the order
- ax.legend(handles[::-1], labels[::-1])
-
- # or sort them by labels
- import operator
- hl = sorted(zip(handles, labels),
- key=operator.itemgetter(1))
- handles2, labels2 = zip(*hl)
-
- ax.legend(handles2, labels2)
-
-
-Using Proxy Artist
-------------------
-
-When you want to display legend for an artist not supported by the
-matplotlib, you may use other supported artist as a proxy. For
-example, you may creates an proxy artist without adding it to the axes
-(so the proxy artist will not be drawn in the main axes) and feet it
-to the legend function.::
-
- p = Rectangle((0, 0), 1, 1, fc="r")
- legend([p], ["Red Rectangle"])
-
-
-Multicolumn Legend
-==================
-
-By specifying the keyword argument *ncol*, you can have a multi-column
-legend. Also, mode="expand" horizontally expand the legend to fill the
-axes area. See `legend_demo3.py
-<http://matplotlib.sourceforge.net/examples/pylab_examples/legend_demo3.html>`_
-for example.
-
-
-Legend location
-===============
-
-The location of the legend can be specified by the keyword argument
-*loc*, either by string or a integer number.
-
-============= ======
- String Number
-============= ======
- upper right 1
- upper left 2
- lower left 3
- lower right 4
- right 5
- center left 6
- center right 7
- lower center 8
- upper center 9
- center 10
-============= ======
-
-By default, the legend will anchor to the bbox of the axes
-(for legend) or the bbox of the figure (figlegend). You can specify
-your own bbox using *bbox_to_anchor* argument. *bbox_to_anchor* can be an
-instance of :class:`~matplotlib.transforms.BboxBase`, a tuple of 4
-floats (x, y, width, height of the bbox), or a tuple of 2 floats (x, y
-with width=height=0). Unless *bbox_transform* argument is given, the
-coordinates (even for the bbox instance) are considered as normalized
-axes coordinates.
-
-For example, if you want your axes legend located at the figure corner
-(instead of the axes corner)::
-
- l = legend(bbox_to_anchor=(0, 0, 1, 1), transform=gcf().transFigure)
-
-Also, you can place above or outer right-hand side of the axes,
-
-.. plot:: users/plotting/examples/simple_legend01.py
- :include-source:
-
-
-Multiple Legend
-===============
-
-Sometime, you want to split the legend into multiple ones.::
-
- p1, = plot([1,2,3])
- p2, = plot([3,2,1])
- legend([p1], ["Test1"], loc=1)
- legend([p2], ["Test2"], loc=4)
-
-However, the above code only shows the second legend. When the legend
-command is called, a new legend instance is created and old ones are
-removed from the axes. Thus, you need to manually add the removed
-legend.
-
-.. plot:: users/plotting/examples/simple_legend02.py
- :include-source:
Added: branches/v0_99_maint/doc/users/transforms_tutorial.rst
===================================================================
--- branches/v0_99_maint/doc/users/transforms_tutorial.rst (rev 0)
+++ branches/v0_99_maint/doc/users/transforms_tutorial.rst 2009-08-15 17:40:27 UTC (rev 7489)
@@ -0,0 +1,428 @@
+.. _transformstutorial:
+
+**************************
+Transformations Tutorial
+**************************
+
+Like any graphics packages, matplotlib is built on top of a
+transformation framework to easily move between coordinate systems,
+the userland `data` coordinate system, the `axes` coordinate system,
+the `figure` coordinate system, and the `display` coordinate system.
+In 95% of your plotting, you won't need to think about this, as it
+happens under the hood, but as you push the limits of custom figure
+generation, it helps to have an understanding of these objects so you
+can reuse the existing transformations matplotlib makes available to
+you, or create your own. The table below summarizes the existing
+coordinate systems, the transformation object you should use to work
+in that coordinate system, and the description of that system. In the
+`Transformation Object` column, ``ax`` is a :class:`~matplotlib.axes.Axes` instance,
+and ``fig`` is a :class:`~matplotlib.figure.Figure` instance.
+
+========== ===================== ==============================================================================================================================================================
+Coordinate Transformation Object Description
+========== ===================== ==============================================================================================================================================================
+`data` ``ax.transData`` The userland data coordinate system, controlled by the xlim and ylim
+`axes` ``ax.transAxes`` The coordinate system of the :class:`~matplotlib.axes.Axes`; (0,0) is bottom left of the axes, and (1,1) is top right of the axes
+`figure` ``fig.transFigure`` The coordinate system of the :class:`~matplotlib.figure.Figure`; (0,0) is bottom left of the figure, and (1,1) is top right of the figure
+`display` `None` This is the pixel coordinate system of the display; (0,0) is the bottom left of the display, and (width, height) is the top right of the display in pixels
+========== ===================== ==============================================================================================================================================================
+
+
+All of the transformation objects take inputs in their coordinate
+system, and transform the input to the `display` coordinate system.
+That is why the `display` coordinate system has `None` for the
+`Transformation Object` column -- it already is in display
+coordinates. The transformations also know how to invert themselves,
+to go from `display` back to the native coordinate system. This is
+particularly useful when processing events frmo the user interface,
+which typically occur in display space, and you want to know where the
+mouse click or key-press occurred in your data coordinate system.
+
+.. _data-coords:
+
+Data coordinates
+================
+
+Let's start with the most commonly used coordinate, the `data`
+coordinate system. Whenever, you add data to the axes, matplotlib
+updates the datalimits, most commonly updated in with the
+:meth:`~matplotlib.axes.Axes.set_xlim` and
+:meth:`~matplotlib.axes.Axes.set_ylim` methods. For example, in the
+figure below, the data limits stretch from 0 to 10 on the x-axis, and
+-1 to 1 on the y-axis.
+
+.. plot::
+ :include-source:
+
+ import numpy as np
+ import matplotlib.pyplot as plt
+
+ x = np.arange(0, 10, 0.005)
+ y = np.exp(-x/2.) * np.sin(2*np.pi*x)
+
+ fig = plt.figure()
+ ax = fig.add_subplot(111)
+ ax.plot(x, y)
+ ax.set_xlim(0, 10)
+ ax.set_ylim(-1, 1)
+
+ plt.show()
+
+You can use the ``ax.transData`` instance to transform from your
+`data` to your `display` coordinate system, either a single point or a
+sequence of points as shown below:
+
+.. sourcecode:: ipython
+
+ In [14]: type(ax.transData)
+ Out[14]: <class 'matplotlib.transforms.CompositeGenericTransform'>
+
+ In [15]: ax.transData.transform((5, 0))
+ Out[15]: array([ 335.175, 247. ])
+
+ In [16]: ax.transData.transform([(5, 0), (1,2)])
+ Out[16]:
+ array([[ 335.175, 247. ],
+ [ 132.435, 642.2 ]])
+
+You can use the :meth`~matplotlib.transforms.Transform.inverted`
+method to create a transform which will take you from display to data
+coordinates:
+
+.. sourcecode:: ipython
+
+ In [41]: inv = ax.transData.inverted()
+
+ In [42]: type(inv)
+ Out[42]: <class 'matplotlib.transforms.CompositeGenericTransform'>
+
+ In [43]: inv.transform((335.175, 247.))
+ Out[43]: array([ 5., 0.])
+
+If your are typing along with this tutorial, the exact values of the
+display coordinates may differ if you have a different window size or
+dpi setting. Likewise, in the figure below, the display labeled
+points are probably not the same as in the ipython session because the
+documentation figure size defaults are different.
+
+.. plot:: pyplots/annotate_transform.py
+
+
+.. note::
+ If you run the source code in the example above in a GUI backend,
+ you may also find that the two arrows for the `data` and `display`
+ annotations do not point to exactly the same point. This is because
+ the display point was computed before the figure was displayed, and
+ the GUI backend may slightly resize the figure when it is created.
+ The effect is more pronounced if you resize the figure yourself.
+ This is one good reason why you rarely want to work in display
+ space, but you can connect to the ``'on_draw'``
+ :class:`~matplotlib.backend_bases.Event` to update figure
+ coordinates on figure draws; see :ref:`event-handling-tutorial`.
+
+When you change the x or y limits of your axes, the data limits are
+updated so the transformation yields a new display point. Note that
+when we just change the ylim, only the y-display coordinate is
+altered, and when we change the xlim too, both are altered. More on
+this later when we talk about the
+:class:`~matplotlib.transforms.Bbox`.
+
+.. sourcecode:: ipython
+
+ In [54]: ax.transData.transform((5, 0))
+ Out[54]: array([ 335.175, 247. ])
+
+ In [55]: ax.set_ylim(-1,2)
+ Out[55]: (-1, 2)
+
+ In [56]: ax.transData.transform((5, 0))
+ Out[56]: array([ 335.175 , 181.13333333])
+
+ In [57]: ax.set_xlim(10,20)
+ Out[57]: (10, 20)
+
+ In [58]: ax.transData.transform((5, 0))
+ Out[58]: array([-171.675 , 181.13333333])
+
+
+
+.. _axes-coords:
+
+Axes coordinates
+================
+
+After the `data` coordinate system, `axes` is probably the second most
+useful coordinate system. Here the point (0,0) is the bottom left
+of your axes or subplot, (0.5, 0.5) is the center, and (1.0,
+1.0) is the top right. You can also refer to points outside the
+range, so (-0.1, 1.1) is to the left and above your axes. This
+coordinate system is extremely useful when making placing text in your
+axes, because you often want a text bubble in a fixed, location, eg
+the upper left of the axes pane, and have that location remain fixed
+when you pan or zoom. Here is a simple example that creates four
+panels and labels them 'A', 'B', 'C', 'D' as you often see in journals.
+
+.. plot::
+ :include-source:
+
+ import numpy as np
+ import matplotlib.pyplot as plt
+
+ fig = plt.figure()
+ for i, label in enumerate(('A', 'B', 'C', 'D')):
+ ax = fig.add_subplot(2,2,i+1)
+ ax.text(0.05, 0.95, label, transform=ax.transAxes,
+ fontsize=16, fontweight='bold', va='top')
+
+ plt.show()
+
+You can also make lines or patches in the axes coordinate system, but
+this is less useful in my experience than using ``ax.transAxes`` for
+placing text. Nonetheless, here is a silly example which plots some
+random dots in `data` space, and overlays a semi-transparent
+:class:`~matplotlib.patches.Circle` centered in the middle of the axes
+with a radius one quarter of the axes -- if your axes does not
+preserve aspect ratio (see :meth:`~matplotlib.axes.Axes.set_aspect`),
+this will look like an ellipse. Use the pan/zoom tool to move around,
+or manually change the data xlim and ylim, and you will see the data
+move, but the circle will remain fixed because it is not in `data`
+coordinates and will always remain at the center of the axes.
+
+.. plot::
+ :include-source:
+
+ import numpy as np
+ import matplotlib.pyplot as plt
+ import matplotlib.patches as patches
+ fig = plt.figure()
+ ax = fig.add_subplot(111)
+ x, y = 10*np.random.rand(2, 1000)
+ ax.plot(x, y, 'go') # plot some data in data coordinates
+
+ circ = patches.Circle((0.5, 0.5), 0.25, transform=ax.transAxes,
+ facecolor='yellow', alpha=0.5)
+ ax.add_patch(circ)
+
+ plt.show()
+
+.. blended_transformations:
+
+Blended transformations
+=======================
+
+Drawing in `blended` coordinate spaces which mix `axes` with `data`
+coordinates is extremely useful, for example to create a horizontal
+span which highlights some region of the y-data but spans across the
+x-axis regardless of the data limits, pan or zoom level, etc. In fact
+these blended lines and spans are so useful, we have built in
+functions to make them easy to plot (see
+:meth:`~matplotlib.axes.Axes.axhline`,
+:meth:`~matplotlib.axes.Axes.axvline`,
+:meth:`~matplotlib.axes.Axes.axhspan`,
+:meth:`~matplotlib.axes.Axes.axvspan`) but for didactic purposes we
+will implement the horizontal span here using a blended
+transformation. This trick only works for separable transformations,
+like you see in normal cartesian coordinate systems, but not on
+inseparable transformations like the
+:class:`~matplotlib.projections.polar.PolarAxes.PolarTransform`.
+
+.. plot::
+ :include-source:
+
+ import numpy as np
+ import matplotlib.pyplot as plt
+ import matplotlib.patches as patches
+ import matplotlib.transforms as transforms
+
+ fig = plt.figure()
+ ax = fig.add_subplot(111)
+
+ x = np.random.randn(1000)
+
+ ax.hist(x, 30)
+ ax.set_title(r'$\sigma=1 \/ \dots \/ \sigma=2$', fontsize=16)
+
+ # the x coords of this transformation are data, and the
+ # y coord are axes
+ trans = transforms.blended_transform_factory(
+ ax.transData, ax.transAxes)
+
+ # highlight the 1..2 stddev region with a span.
+ # We want x to be in data coordinates and y to
+ # span from 0..1 in axes coords
+ rect = patches.Rectangle((1,0), width=1, height=1,
+ transform=trans, color='yellow',
+ alpha=0.5)
+
+ ax.add_patch(rect)
+
+ plt.show()
+
+
+.. offset-transforms-shadow:
+
+Using offset transforms to create a shadow effect
+=================================================
+
+One use of transformations is to create a new transformation that is
+offset from another annotation, eg to place one object shited a bit
+relative to another object. Typically you want the shift to be in
+some physical dimension, like points or inches rather than in data
+coordinates, so that the shift effect is constant at different zoom
+levels and dpi settings.
+
+One use for an offset is to create a shadow effect, where you draw one
+object identical to the first just to the right of it, and just below
+it, adjusting the zorder to make sure the shadow is drawn first and
+then the object it is sh...
[truncated message content] |
