Thread: SF.net SVN: matplotlib:[7092] trunk/matplotlib/doc/users

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Revision: 7092
          http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7092&view=rev
Author:   leejjoon
Date:     2009-05-07 03:59:28 +0000 (Thu, 07 May 2009)

Log Message:
-----------
add legend guide in documnetation

Modified Paths:
--------------
    trunk/matplotlib/doc/users/plotting.rst

Added Paths:
-----------
    trunk/matplotlib/doc/users/plotting/
    trunk/matplotlib/doc/users/plotting/examples/
    trunk/matplotlib/doc/users/plotting/examples/simple_legend01.py
    trunk/matplotlib/doc/users/plotting/examples/simple_legend02.py
    trunk/matplotlib/doc/users/plotting/legend.rst

Added: trunk/matplotlib/doc/users/plotting/examples/simple_legend01.py
===================================================================

--- trunk/matplotlib/doc/users/plotting/examples/simple_legend01.py	                        (rev 0)
+++ trunk/matplotlib/doc/users/plotting/examples/simple_legend01.py	2009-05-07 03:59:28 UTC (rev 7092)
@@ -0,0 +1,15 @@
+from matplotlib.pyplot import *
+
+subplot(211)
+plot([1,2,3], label="test1")
+plot([3,2,1], label="test2")
+legend(bbox_to_anchor=(0., 1.02, 1., .102), loc=3,
+       ncol=2, mode="expand", borderaxespad=0.)
+
+subplot(223)
+plot([1,2,3], label="test1")
+plot([3,2,1], label="test2")
+legend(bbox_to_anchor=(1.05, 1), loc=2, borderaxespad=0.)
+
+
+show()

Added: trunk/matplotlib/doc/users/plotting/examples/simple_legend02.py
===================================================================
--- trunk/matplotlib/doc/users/plotting/examples/simple_legend02.py	                        (rev 0)
+++ trunk/matplotlib/doc/users/plotting/examples/simple_legend02.py	2009-05-07 03:59:28 UTC (rev 7092)
@@ -0,0 +1,10 @@
+from matplotlib.pyplot import *
+
+p1, = plot([1,2,3], label="test1")
+p2, = plot([3,2,1], label="test2")
+
+l1 = legend([p1], ["Label 1"], loc=1)
+l2 = legend([p2], ["Label 2"], loc=4) # this removes l1 from the axes.
+gca().add_artist(l1) # add l1 as a separate artist to the axes
+
+show()

Added: trunk/matplotlib/doc/users/plotting/legend.rst
===================================================================
--- trunk/matplotlib/doc/users/plotting/legend.rst	                        (rev 0)
+++ trunk/matplotlib/doc/users/plotting/legend.rst	2009-05-07 03:59:28 UTC (rev 7092)
@@ -0,0 +1,181 @@
+.. _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 equivalaent 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 mupltiple 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:

Modified: trunk/matplotlib/doc/users/plotting.rst
===================================================================
--- trunk/matplotlib/doc/users/plotting.rst	2009-05-07 03:51:41 UTC (rev 7091)
+++ trunk/matplotlib/doc/users/plotting.rst	2009-05-07 03:59:28 UTC (rev 7092)
@@ -144,8 +144,7 @@
 ==================================
 :func:`~matplotlib.pyplot.legend` and :func:`~matplotlib.pyplot.figlegend`
 
+:ref:`plotting-guide-legend`
+
 TODO; see :ref:`how-to-contribute-docs`.
 
-
-
-


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.




Thread: SF.net SVN: matplotlib:[7092] trunk/matplotlib/doc/users

matplotlib-checkins