GitHub PullRequestReviewCommentEvent at 2014-01-22 15:47:47
Repository: matplotlib
Actor: tacaswell
Payload: {"comment":{"url":"https://api.github.com/repos/matplotlib/matplotlib/pulls/comments/9079001","id":9079001,"diff_hunk":"@@ -4,315 +4,275 @@\n Legend guide\n ************\n \n-Do not proceed unless you already have read :func:`~matplotlib.pyplot.legend`\n-and :class:`matplotlib.legend.Legend`!\n+.. currentmodule:: matplotlib.pyplot\n \n \n-What to be displayed\n-====================\n+This legend guide is an extension of the documentation available at\n+:func:`~matplotlib.pyplot.legend` - please ensure you are familiar with\n+contents of that documentation before proceeding with this guide.\n \n-The legend command has a following call signature::\n \n-      legend(*args, **kwargs)\n+This guide makes use of some common terms, which are documented here for clarity:\n \n-If len(args) is 2, the first argument should be a list of artist to be\n-labeled, and the second argument should a list of string labels.  If\n-len(args) is 0, it automatically generate the legend from label\n-properties of the child artists by calling\n-:meth:`~matplotlib.axes.Axes.get_legend_handles_labels` method.\n-For example, *ax.legend()* is equivalent to::\n+.. glossary::\n \n-  handles, labels = ax.get_legend_handles_labels()\n-  ax.legend(handles, labels)\n+    legend entry\n+        A legend is made up of one or more legend entries. An entry is made up of\n+        exactly one key and one label.\n \n-The :meth:`~matplotlib.axes.Axes.get_legend_handles_labels` method\n-returns a tuple of two lists, i.e., list of artists and list of labels\n-(python string).  However, it does not return all of its child\n-artists. It returns artists that are currently supported by matplotlib.\n+    legend key\n+        The colored/patterned marker to the left of each legend label.\n \n-For matplotlib v1.0 and earlier, the supported artists are as follows.\n+    legend label\n+        The text which describes the handle represented by the key.\n \n-   * :class:`~matplotlib.lines.Line2D`\n-   * :class:`~matplotlib.patches.Patch`\n-   * :class:`~matplotlib.collections.LineCollection`\n-   * :class:`~matplotlib.collections.RegularPolyCollection`\n-   * :class:`~matplotlib.collections.CircleCollection`\n+    legend handle\n+        The original object which is used to generate an appropriate entry in\n+        the legend.\n \n-And, :meth:`~matplotlib.axes.Axes.get_legend_handles_labels` returns\n-all artists in *ax.lines*, *ax.patches* and\n-artists in *ax.collection* which are instance of\n-:class:`~matplotlib.collections.LineCollection` or\n-:class:`~matplotlib.collections.RegularPolyCollection`.  The label\n-attributes (returned by get_label() method) of collected artists are\n-used as text labels. If label attribute is empty string or starts with\n-\"_\", those artists will be ignored.\n \n+Controlling the legend entries\n+==============================\n \n-Therefore, plots drawn by some *pyplot* commands are not supported by\n-legend.  For example, :func:`~matplotlib.pyplot.fill_between` creates\n-:class:`~matplotlib.collections.PolyCollection` that is not\n-supported. Also support is limited for some commands that create\n-multiple artists. For example, :func:`~matplotlib.pyplot.errorbar`\n-creates multiples :class:`~matplotlib.lines.Line2D` instances.\n+Calling :func:`legend` with no arguments automatically fetches the legend\n+handles and their associated labels. This functionality is equivalent to::\n \n-Unfortunately, there is no easy workaround when you need legend for an\n-artist not supported by matplotlib (You may use one of the supported\n-artist as a proxy. See below)\n+    handles, labels = ax.get_legend_handles_labels()\n+    ax.legend(handles, labels)\n \n-In newer version of matplotlib (v1.1 and later), the matplotlib\n-internals are revised to support\n+The :meth:`~matplotlib.axes.Axes.get_legend_handles_labels` function returns\n+a list of handles/artists which exist on the Axes which can be used to\n+generate entries for the resulting legend.\n \n- * complex plots that creates multiple artists (e.g., bar, errorbar, etc)\n- * custom legend handles\n+For full control of what is being added to the legend, it is common to pass\n+the appropriate handles directly to :func:`legend`::\n \n-See below for details of new functionality.\n+    line2, = plt.plot([1,2,3], label='Line 2')\n+    line1, = plt.plot([3,2,1], label='Line 1')\n+    plt.legend(handles=[line1, line2])\n \n+In some cases, it is not possible to set the label of the handle, so it is\n+possible to pass through the list of labels to :func:`legend`::\n \n-Adjusting the Order of Legend items\n------------------------------------\n+    line2, = plt.plot([1,2,3], label='Line 2')\n+    line1, = plt.plot([3,2,1], label='Line 1')\n+    plt.legend([line1, line2], ['Custom label for line 1', 'Line 1'])\n \n-When you want to customize the list of artists to be displayed in the\n-legend, or their order of appearance. There are a two options. First,\n-you can keep lists of artists and labels, and explicitly use these for\n-the first two argument of the legend call.::\n \n-  p1, = plot([1,2,3])\n-  p2, = plot([3,2,1])\n-  p3, = plot([2,3,1])\n-  legend([p2, p1], [\"line 2\", \"line 1\"])\n+Creating artists specifically for adding to the legend (aka. Proxy artists)\n+===========================================================================\n \n-Or you may use :meth:`~matplotlib.axes.Axes.get_legend_handles_labels`\n-to retrieve list of artist and labels and manipulate them before\n-feeding them to legend call.::\n+Not all handles can be turned into legend entries automatically,","path":"doc/users/legend_guide.rst","position":121,"original_position":121,"commit_id":"ceda68f71bbcd2c3b65872e02a932bc9b1dd8825","original_commit_id":"ceda68f71bbcd2c3b65872e02a932bc9b1dd8825","user":{"login":"tacaswell","id":199813,"avatar_url":"https://gravatar.com/avatar/8744048060e5931c500d3c9d1ecb997e?d=https%3A%2F%2Fidenticons.github.com%2F5923699847bb77c1416ba8ebf940f248.png&r=x","gravatar_id":"8744048060e5931c500d3c9d1ecb997e","url":"https://api.github.com/users/tacaswell","html_url":"https://github.com/tacaswell","followers_url":"https://api.github.com/users/tacaswell/followers","following_url":"https://api.github.com/users/tacaswell/following{/other_user}","gists_url":"https://api.github.com/users/tacaswell/gists{/gist_id}","starred_url":"https://api.github.com/users/tacaswell/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tacaswell/subscriptions","organizations_url":"https://api.github.com/users/tacaswell/orgs","repos_url":"https://api.github.com/users/tacaswell/repos","events_url":"https://api.github.com/users/tacaswell/events{/privacy}","received_events_url":"https://api.github.com/users/tacaswell/received_events","type":"User","site_admin":false},"body":"'As mentioned above, ...'","created_at":"2014-01-22T15:47:47Z","updated_at":"2014-01-22T15:47:47Z","html_url":"https://github.com/matplotlib/matplotlib/pull/2442#discussion_r9079001","pull_request_url":"https://api.github.com/repos/matplotlib/matplotlib/pulls/2442","_links":{"self":{"href":"https://api.github.com/repos/matplotlib/matplotlib/pulls/comments/9079001"},"html":{"href":"https://github.com/matplotlib/matplotlib/pull/2442#discussion_r9079001"},"pull_request":{"href":"https://api.github.com/repos/matplotlib/matplotlib/pulls/2442"}}}}